@enclave-vm/client
Browser and Node.js client SDK for connecting to an EnclaveJS broker. Provides streaming execution, event handling, cancellation, and automatic reconnection.Installation
Quick Start
Client Configuration
fetch (see Node.js Usage), these are all the options. Any other option makes the constructor throw a TypeError that names it: the client has no encryption, auth, serverUrl or reconnect option. A value the client cannot use, such as a timeout of 0, throws as well.
The client does not encrypt. Requests and events travel as plain JSON over HTTP and are protected only by the transport: use an
https: base URL, and send credentials with headers.Executing Code
Basic Execution
executeStream() returns the handle at once, not a promise. execute(code, options) is the same as executeStream(code, options).wait().
Execution Options
Both methods take the same options: the three below, plus the event handlers.SessionLimits, the client sends sessionTtlMs, maxToolCalls and heartbeatIntervalMs to the broker.
timeout and limits.sessionTtlMs are different things. timeout is how long the client waits for the broker to say something; a session that keeps sending events, heartbeats included, stays open. limits.sessionTtlMs asks the broker to limit how long the session may last.
Event Handlers
All Event Types
execute(), or from wait() on the handle.
Tools run on the broker. onToolCall and onToolResultApplied tell the client about them; the client executes nothing and has no API to register tools.
Event Handler Shortcuts
Session Handle
executeStream() returns a session handle for managing the execution:
Session Result
Cancelling
There are three ways to cancel a session, and they do the same:CANCELLED, and the broker is asked to end it with DELETE {baseUrl}/sessions/:sessionId. No further event of the session is delivered after that. Cancelling does not reject: if the broker does not confirm the stop, onError is called with the code CANCEL_FAILED, and the script may still be running.
Error Handling
A session that fails is not a rejected promise.execute() and wait() resolve with success: false and an error:
Error Codes
error.code is one of the client’s codes below, or the code that the broker sent with the end of the session.
Session Lookup
getSession() asks the broker about a session. It resolves with null when the broker does not know the session, and it is the one method that rejects, with an EnclaveClientError:
Reconnection
A connection counts as lost when a request fails, when the stream ends before the session is complete, or when the broker stays silent for longer than the client waits. WithautoReconnect on, the client then reconnects, up to maxReconnectAttempts times in a row and with a growing delay, and asks the broker for the events after the last one it delivered. Every event is delivered once and in order, and nothing is delivered after the final event.
If the attempts are used up, or autoReconnect is off, the session fails with the code of the last failure.
Connection State
ConnectionState is re-exported from @enclave-vm/stream. The client tracks the connection of each session internally; the session handle does not expose it.
Multiple Sessions
Browser Usage
Node.js Usage
fetch, the fetch option is required. The implementation has to return a standard Response: the client reads the events from its body stream.