@enclave-vm/broker
Tool broker and session management for the EnclaveJS streaming runtime. It runs scripts in an@enclave-vm/core sandbox on your server, gives them the tools you register, and streams what happens as events, in process or over HTTP.
The broker does not authenticate callers, limit request rates or encrypt sessions. Put authentication in front of its routes, and tell the routes who the caller is (see Who may see a session).
Installation
Quick Start
callTool(name, args). broker.execute() resolves with the final result; the events of the run are handed to onEvent.
Broker Configuration
Limits
The limits of the broker bound every session. A session created in process can name its own value for a limit (the other limits keep the broker’s values); a session created over HTTP can only lower
maxToolCalls and its lifetime.
Tools and Secrets
argsSchema before the handler runs. Secrets are handed to the handler only and are not part of any event. Tool arguments and the result of a script are part of the events: keep secrets out of them.
Sessions
broker.execute() creates a session, runs the script and removes the session. To keep a session around, create it yourself:
createSession({ sessionId }) throws for an id that is in use, and when sessions.maxSessions sessions are registered. A finished session stays registered, so that it can be replayed, until the next cleanup.
What a session keeps
A session keeps its most recent events for replays, up tohistory.maxEvents events and history.maxBytes bytes. When a bound is reached the oldest events are dropped; session.firstReplayableSeq is the lowest sequence number from which everything is still kept.
Cancelling
A session runs in the broker’s process, on its thread. Cancelling a session aborts the tool call in flight and refuses every later one. It does not interrupt a script that is computing: such a script holds the thread until it ends or reachestoolTimeoutMs.
HTTP API
Express Integration
To mount the routes under a prefix, register them on an Express router and mount the router:
createExpressRouter is deprecated: it registers no route. For another framework, adapt its request and response to BrokerRequest and BrokerResponse and call the handlers of handler.getRoutes().
Who may see a session
Withidentify, every session belongs to the caller that created it:
GET /sessionslists the caller’s own sessions.- Reading, replaying and ending a session is answered only for its owner. Another caller gets
404, the answer of an id that does not exist. - A request for which the hook returns nothing, or throws, is answered with
401. - A session created in process has no owner and is not reachable over the routes, unless you create it with
owner.
broker.getSession(context.sessionId as SessionId)?.owner, the caller the hook returned), or leaves it to the data store.
Handler Options
OPTIONS) themselves, and a browser sends it without the credential: authentication in front of the routes has to let OPTIONS requests through to them.
maxStreamsPerSessionbounds the streams one session has open (the request that created it and the replay streams). A further one is answered with429.maxBufferedBytes: a reader that falls behind by more is disconnected. When it is the creator of the session, the session is cancelled.
The Request Body of POST /sessions
400 and creates no session.
configvalues are positive integers.maxToolCallsandmaxExecutionMscannot exceed the broker’s limits (a larger value is lowered to them), andheartbeatIntervalMsis kept between 1 second and 5 minutes.sessionIdiss_followed by 1 to 128 characters ofA-Z a-z 0-9 . _ : ~ -. An id in use is answered with409.filterhas bounds: 16 rules, 32 patterns, 256 characters per pattern.encryption: { mode: 'required' }is refused: the broker does not encrypt sessions.
Answers
An error answer is
{ code, message } with a fixed message.
Event Filtering
Filter which events are sent to a client.Type-Based Filtering
Content-Based Filtering
field, a pattern is matched against the payload as JSON text.
- Evaluating one event takes a bounded time: regular expressions and globs run under
regexTimeoutMs(100 ms by default). ThebudgetMsoption ofcreateEventFilterbounds all evaluations of one filter together. - An event the filter could not evaluate (a pattern that does not compile, an evaluation that ran out of time) is not sent, in either mode.
- In exclude mode a glob is matched as text:
*also matches/and a leading dot. In include mode a glob follows path rules. - A filter that arrives in a request gets at most 100 ms per event and 500 ms per stream, and its globs are matched without brace and extglob expansion.
Always-Allowed Events
session_init and final are sent whatever the filter says, unless the configuration sets its own alwaysAllow list.
Tools from OpenAPI
- A failure while polling is reported with the
errorevent when it has a listener, and ingetStats()either way. The tools of the last specification that was applied stay registered; tools are replaced in one step, and a source never replaces a tool it does not manage. - 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. authandloaderOptions.headersgo to the origin ofbaseUrlonly: not to a specification on another origin (the source’sheadersare for the specification host), and not along a redirect to another origin. A header parameter of the specification cannot replace them.- Upstream responses are read up to
loaderOptions.maxResponseBytes(10 MB by default), specifications up tomaxSpecBytes(32 MB), and fetching a specification is bounded byfetchTimeoutMs.