JavaScript Client

A JavaScript client for interacting with the Pie server.

Installation

npm install @pie-project/client

Quick Start

import { PieClient } from '@pie-project/client';

async function main() {
    const client = new PieClient('ws://127.0.0.1:8080');
    
    try {
        await client.connect();
        await client.authenticate('username');
        
        const instance = await client.launchInstanceFromRegistry(
            'text-completion',
            ['--prompt', 'Hello, world!']
        );
        
        while (true) {
            const { event, msg } = await instance.recv();
            
            if (event === 'Stdout') {
                process.stdout.write(msg);
            } else if (event === 'Completed') {
                break;
            }
        }
    } finally {
        await client.close();
    }
}

main();

PieClient

The main client class for connecting to a Pie server.

Constructor

new PieClient(serverUri)

Parameter	Type	Description
serverUri	string	WebSocket URI (e.g., "ws://127.0.0.1:8080")

Methods

Method	Returns	Description
connect()	Promise<void>	Establish WebSocket connection
close()	Promise<void>	Close the connection
authenticate(username)	Promise<void>	Authenticate with server
uploadProgram(bytes)	Promise<void>	Upload a WASM program
programExists(hash)	Promise<boolean>	Check if program exists
launchInstance(hash, args, detached)	Promise<Instance>	Launch by hash
launchInstanceFromRegistry(name, args, detached)	Promise<Instance>	Launch from registry
attachInstance(instanceId)	Promise<Instance>	Attach to existing instance
listInstances()	Promise<Array>	List running instances
terminateInstance(instanceId)	Promise<void>	Terminate an instance
ping()	Promise<void>	Check connectivity

Example

const client = new PieClient('ws://127.0.0.1:8080');

await client.connect();
await client.authenticate('username');

// Upload a custom inferlet
const wasmBytes = await fs.promises.readFile('my_inferlet.wasm');
await client.uploadProgram(wasmBytes);

// Check if already uploaded
const exists = await client.programExists(programHash);

Instance

Represents a running program instance.

Properties

Property	Type	Description
instanceId	string	Unique instance identifier

Methods

Method	Returns	Description
send(message)	Promise<void>	Send a string message
recv()	Promise<{event, msg}>	Receive next event
terminate()	Promise<void>	Request termination

Example

const instance = await client.launchInstanceFromRegistry('chat');

// Send a message
await instance.send('What is the meaning of life?');

// Receive response
const { event, msg } = await instance.recv();
console.log(msg);

// Terminate when done
await instance.terminate();

Event Types

Events returned by instance.recv():

Event	Description
Message	Text message from instance
Stdout	Streaming stdout output
Stderr	Streaming stderr output
Blob	Binary data received
Completed	Instance finished successfully
Aborted	Instance was aborted
Exception	Instance raised an exception
ServerError	Server-side error
OutOfResources	Resource limit reached

Handling Events

while (true) {
    const { event, msg } = await instance.recv();
    
    switch (event) {
        case 'Stdout':
            process.stdout.write(msg);
            break;
        case 'Stderr':
            console.error(msg);
            break;
        case 'Completed':
            console.log('\nDone!');
            return;
        case 'Exception':
            throw new Error(`Inferlet error: ${msg}`);
        case 'ServerError':
            throw new Error(`Server error: ${msg}`);
    }
}

Detached Instances

Launch instances that persist after disconnection:

// Launch detached
const instance = await client.launchInstanceFromRegistry(
    'long-task',
    [],
    true  // detached
);
const instanceId = instance.instanceId;

// Disconnect
await client.close();

// Later, reconnect and attach
const client2 = new PieClient('ws://127.0.0.1:8080');
await client2.connect();
await client2.authenticate('username');

const attached = await client2.attachInstance(instanceId);
const { event, msg } = await attached.recv();

Browser Usage

The client works in browsers with WebSocket support:

<script type="module">
import { PieClient } from '@pie-project/client';

const client = new PieClient('ws://localhost:8080');
await client.connect();
// ...
</script>

Error Handling

try {
    await client.connect();
    await client.authenticate('username');
} catch (error) {
    if (error.message.includes('ECONNREFUSED')) {
        console.error('Server not running');
    } else {
        console.error('Connection error:', error);
    }
}