@enclave-vm/client package - the client SDK for EnclaveJS.
Installation
EnclaveClient Class
The main client class for connecting to EnclaveJS brokers. It starts sessions over HTTP, reads their events as a stream, and returns their results.Constructor
EnclaveClientConfig
These are all the options. The constructor throws a
TypeError:
- for any other option, and the message names it. The client has no
encryption,auth,serverUrlorreconnectoption. - for a value it cannot use, for example an empty
baseUrl, atimeoutof0, orheaderswith a value that is not a string. - when there is no global
fetchand none is passed.
Methods
execute(code, options?)
Execute code and wait for the result.success: false. The call is the same as executeStream(code, options).wait().
Example:
executeStream(code, options?)
Execute code and return a handle for the running session.options as they arrive.
Example:
getSession(sessionId)
Get session information from the broker.null when the broker answers 404. Rejects with an EnclaveClientError: SESSION_ERROR for a session ID that is not valid and for any other error status, TIMEOUT when the broker does not answer in time, NETWORK_ERROR when the request fails.
cancelSession(sessionId, reason?)
Cancel a session that this client is running. See Cancellation.Execute Options
execute() and executeStream() take the same options: ExecuteOptions together with the event handlers.
A session ID is a string that starts with
s_. Anything else is refused before a request is made: execute() and executeStream() give a SESSION_ERROR result, and getSession() rejects. A session with an ID that is already running on the same client is refused the same way.
Session Handle
Session Result
Event Handling
Event Handlers
ErrorPayload and ToolProgressPhase are types of @enclave-vm/types.
The
final event has no handler of its own. It ends the session, and its content becomes the SessionResult that wait() and execute() resolve with.
Tools run on the broker. onToolCall and onToolResultApplied tell the client about them; the client executes nothing and has no API to register tools or to submit tool results.
Processing Events
Event Types
onEvent, getEvents() and result.events work with the events themselves.
Cancellation
A session is cancelled withcancel() on its handle, with cancelSession(), or by aborting the signal it was started with. All three do the same:
- The session ends in the client as
CANCELLED, and no further event of it is delivered. - The broker is asked to end the session with
DELETE {baseUrl}/sessions/:sessionId.
onError is called with the code CANCEL_FAILED: the script may still be running.
A session that is started with a signal that is already aborted ends as CANCELLED without a request being made.
Using AbortController
Transport and Credentials
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.PARSE_ERROR.
Requests
config carries the limits of the session: { maxExecutionMs, maxToolCalls, heartbeatIntervalMs }, where maxExecutionMs is limits.sessionTtlMs. Session IDs are URL-encoded in the request paths.
Reconnection
Automatic Reconnection
final event, or when the broker stays silent for longer than the client waits. The client then reconnects:
- up to
maxReconnectAttemptstimes in a row. The count starts again when a connection delivers a new event. - after a delay that is based on
reconnectDelayand grows with each attempt in a row. - asking 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
finalevent.
autoReconnect is false, the session fails with the code of the last failure.
Timeouts
timeout is how long the client waits for the broker:
- for the answer to a request.
- for the next event on an open stream. Here the wait is never shorter than two heartbeat intervals of the session (15 seconds each, unless
limits.heartbeatIntervalMsasks for another).
TIMEOUT.
timeout does not limit how long a script runs. A session that keeps sending events, heartbeats included, stays open. To ask the broker for a limit on the duration of a session, use limits.sessionTtlMs.
Error Handling
A session that fails is not a rejected promise.execute() and wait() resolve with success: false and an error, whose code is one of the client’s codes or the code that the broker sent in the final event.
Error Codes
EnclaveClientError
getSession() rejects with an EnclaveClientError. It is the one method of the client that rejects.
Complete Example
Browser Usage
Exports
ConnectionState is re-exported from @enclave-vm/stream.
Related
- Client Overview - Usage guide
- @enclave-vm/types - Type definitions
- @enclave-vm/react - React hooks