@enclave-vm/broker package - the orchestration layer for EnclaveJS.
Installation
Broker Class
The main entry point: a tool registry, a secret store and a session manager.Constructor
BrokerConfig
A key that is not listed is ignored and reported with a warning. A limit that is not a number makes the constructor throw.
Methods
tool(name, definition)
Register a tool. Throws when a tool of that name is registered.secret(key, value)
execute(code, options?)
Create a session, run the script, remove the session, and resolve with the result.createSession(config?)
createSession throws a BrokerError with code SESSION_EXISTS, INVALID_SESSION_ID or MAX_SESSIONS_REACHED.
openapi(config)
Register an OpenAPI source. See OpenApiSource.Other members
SessionLimits
Defined in@enclave-vm/types.
BrokerSession Class
getEvents()returns the events the session keeps: all of them until a bound ofhistoryis reached, the most recent ones afterwards.firstReplayableSeqis the lowest sequence number from which every event is still kept.- A
tool_callevent holds its own copy of the arguments. cancel()aborts the tool call in flight and refuses later ones. It does not interrupt a script that is computing; the script ends by itself or attoolTimeoutMs.
SessionManager Class
maxSessions bounds the registered sessions. A finished session stays registered until the next cleanup, and a session past sessionTtlMs is cancelled at the next cleanup.
HTTP API
SessionHandler
handler.getRoutes() returns { method, path, handler } entries for other frameworks. BrokerRequest carries method, path, params, query, body, headers, signal (aborted when the caller goes away) and raw (the framework’s request object). BrokerResponse needs status(), json(), setHeader(), write(), end() and may offer flush(), bufferedBytes() and destroy().
createExpressRouter is deprecated: it registers no route.
POST /sessions
Create a session, runcode, and stream the events.
Request:
final. The header X-Session-ID holds the session id.
Example:
GET /sessions
List sessions: all of them, or the caller’s own whenidentify is set.
Response:
GET /sessions/:sessionId
Response:GET /sessions/:sessionId/stream
Replay the kept events with a sequence number offromSeq or higher, then follow the session until its final event.
Answers
410 EVENTS_GONE when events from fromSeq on are no longer kept, and 429 TOO_MANY_STREAMS when the session has maxStreamsPerSession streams open.
DELETE /sessions/:sessionId
End a session.POST /sessions/:sessionId/cancel does the same; it is the cancelUrl of the session_init event.
Response:
Error answers
GET /code/actions
Returns the current action catalog: every registered tool, with the OpenAPI service it comes from. Response:version field is derived from the hashes of all source specifications. Consumers can compare version strings to detect catalog changes.
Wiring: Use CatalogHandler to register this route:
EventFilter Class
- An event the filter could not evaluate is not sent: a pattern that does not compile, a field that cannot be serialized, an evaluation that exceeded
regexTimeoutMsor the budget. - In exclude mode a glob is matched as text (
*also matches/and a leading dot). - A filter is not a confidentiality control.
OpenApiSource Class
Methods
Events
Behaviour
- Tools are replaced in one step; a failed update changes nothing. A source never replaces a tool it does not manage:
start()andrefresh()reject, and a polled update is reported as a failure. - A path parameter fills its own segment of the path; a value that would leave the segment empty or turn it into
.or..fails the call withINVALID_PATH_PARAMETER. authandloaderOptions.headersare sent to the origin ofbaseUrlonly. A redirect to another origin is followed without them, and at most five redirects are followed.- A header parameter of the specification cannot replace
author a header ofloaderOptions.headers.
Complete Example
identify separates sessions, not data: the two tools above return the same users to every caller that may create a session. A tool that reads data restricted per caller applies that restriction itself, with the owner of its session (broker.getSession(context.sessionId as SessionId)?.owner, the caller identify returned), or leaves it to the data store. See the broker example in Architecture.
Related
- Broker Overview - Guide
- @enclave-vm/types - Type definitions
- @enclave-vm/client - Client SDK