Skip to main content
API reference for the @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)

Secrets are handed to the handlers of the tools that name them, and to nothing else.

execute(code, options?)

Create a session, run the script, remove the session, and resolve with the result.
Example:

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 of history is reached, the most recent ones afterwards. firstReplayableSeq is the lowest sequence number from which every event is still kept.
  • A tool_call event 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 at toolTimeoutMs.

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

Without identify, whoever can reach the routes can list, read, replay and end every session. See Who may see a session.
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, run code, and stream the events. Request:
Response: NDJSON stream of events, ending with final. The header X-Session-ID holds the session id. Example:

GET /sessions

List sessions: all of them, or the caller’s own when identify is set. Response:

GET /sessions/:sessionId

Response:

GET /sessions/:sessionId/stream

Replay the kept events with a sequence number of fromSeq 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 semantics: The 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:
The route answers every caller alike: put your own authentication in front of it.

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 regexTimeoutMs or 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() and refresh() 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 with INVALID_PATH_PARAMETER.
  • auth and loaderOptions.headers are sent to the origin of baseUrl only. A redirect to another origin is followed without them, and at most five redirects are followed.
  • A header parameter of the specification cannot replace auth or a header of loaderOptions.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.