@enclave-vm/broker 2.19.1 → 2.20.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/event-filter.d.ts CHANGED
@@ -2,7 +2,17 @@
2
2
  * Event Filter
3
3
  *
4
4
  * Filters stream events based on configurable rules.
5
- * Includes ReDoS (Regular Expression Denial of Service) protection.
5
+ *
6
+ * Two properties hold for every filter, whatever its patterns and whatever the event:
7
+ *
8
+ * - Evaluating one event takes a bounded time. Patterns that can take long (regular expressions
9
+ * and globs) run under a time limit (`regexTimeoutMs`, 100 ms by default), and a filter can be
10
+ * given a budget for all of its evaluations together.
11
+ * - An event the filter could not evaluate is not sent. In exclude mode a pattern that cannot
12
+ * be evaluated counts as matching; in include mode it counts as not matching.
13
+ *
14
+ * A filter decides what a client is sent, for the client's convenience. It is not a
15
+ * confidentiality control: keep data that a client must not see out of the events.
6
16
  *
7
17
  * @packageDocumentation
8
18
  */
@@ -17,70 +27,116 @@ export interface EventFilterOptions {
17
27
  */
18
28
  config: EventFilterConfig;
19
29
  /**
20
- * Callback for filter errors (e.g., regex errors).
30
+ * Callback for filter errors (a pattern that could not be evaluated, an evaluation that ran
31
+ * out of time).
21
32
  */
22
33
  onError?: (error: Error, event: StreamEvent) => void;
34
+ /**
35
+ * Total processor time, in milliseconds, this filter may spend evaluating regular
36
+ * expressions and globs over its whole life. When it is used up, those patterns count as not
37
+ * evaluable for every later event. Set it for a filter that lives as long as one stream and whose patterns
38
+ * were not written by the embedder.
39
+ *
40
+ * @default no budget
41
+ */
42
+ budgetMs?: number;
43
+ /**
44
+ * Expand brace sets (`{a,b}`) and extended globs (`+(a|b)`) in glob patterns. When false,
45
+ * those characters are matched as text.
46
+ *
47
+ * @default true
48
+ */
49
+ expandGlobs?: boolean;
23
50
  }
24
51
  /**
25
52
  * Event Filter
26
53
  *
27
- * Provides efficient event filtering with:
54
+ * Provides event filtering with:
28
55
  * - Type-based filtering
29
56
  * - Content pattern matching (exact, prefix, regex, glob)
30
- * - Compiled and cached regex patterns
57
+ * - Patterns compiled once per filter
58
+ * - A time limit per evaluated event and an optional budget per filter
31
59
  */
32
60
  export declare class EventFilter {
33
- private readonly config;
61
+ private readonly exclude;
34
62
  private readonly alwaysAllow;
35
- private readonly compiledRegexes;
63
+ private readonly rules;
64
+ private readonly timeoutMs;
65
+ private readonly budgetMs?;
66
+ private readonly expandGlobs;
36
67
  private readonly onError?;
68
+ private spentMs;
37
69
  constructor(options: EventFilterOptions);
38
70
  /**
39
71
  * Check if an event should be sent to the client.
40
72
  */
41
73
  shouldSend(event: StreamEvent): boolean;
74
+ /**
75
+ * Decide one event that is not always allowed.
76
+ */
77
+ private decide;
42
78
  /**
43
79
  * Filter an array of events.
44
80
  */
45
81
  filter(events: StreamEvent[]): StreamEvent[];
46
82
  /**
47
- * Check if event matches any filter rule.
83
+ * Whether the budget of this filter is used up.
48
84
  */
49
- private matchesAnyRule;
85
+ private budgetUsedUp;
50
86
  /**
51
- * Check if event matches a specific rule.
87
+ * Evaluate all rules, slow patterns included, under the time limit. Returns undefined when
88
+ * the evaluation did not finish.
89
+ *
90
+ * The limit is a limit on elapsed time. When it is reached although the thread got little
91
+ * processor time meanwhile (the machine was busy with something else), the evaluation is
92
+ * tried again, a bounded number of times, so that a busy machine does not drop events. An
93
+ * evaluation that used its time on a processor is not tried again.
52
94
  */
53
- private matchesRule;
95
+ private evaluateWithinLimit;
54
96
  /**
55
- * Check if event type matches filter.
97
+ * Check if event matches any filter rule. With `slow` false, patterns that need the time
98
+ * limit are put off and the answer is undefined when it depends on one of them.
56
99
  */
57
- private matchesTypeFilter;
100
+ private matchesAnyRule;
58
101
  /**
59
- * Check if event content matches filter.
102
+ * Check if event matches a specific rule. If the rule has both a type filter and a content
103
+ * filter, both must match.
60
104
  */
61
- private matchesContentFilter;
105
+ private matchesRule;
62
106
  /**
63
107
  * Check if event matches a content pattern.
64
108
  */
65
109
  private matchesPattern;
66
110
  /**
67
- * Get field value from event using dot notation.
111
+ * What a pattern that cannot be evaluated counts as: a match when matching keeps an event
112
+ * back (exclude), no match when matching lets it through (include).
113
+ */
114
+ private notEvaluable;
115
+ /**
116
+ * The subject text in the case the pattern compares in.
117
+ */
118
+ private textOf;
119
+ /**
120
+ * The text of the field a pattern reads, computed once per event.
121
+ */
122
+ private subjectOf;
123
+ /**
124
+ * Compile one rule.
68
125
  */
69
- private getFieldValue;
126
+ private compileRule;
70
127
  /**
71
- * Stringify a value for matching.
128
+ * Compile a glob. Returns null when the pattern does not compile.
72
129
  */
73
- private stringify;
130
+ private compileGlob;
74
131
  /**
75
- * Match against a compiled regex with ReDoS protection.
76
- * Enforces input length limits to prevent catastrophic backtracking.
132
+ * Compile every glob of this filter again.
77
133
  */
78
- private matchRegex;
134
+ private recompileGlobs;
79
135
  /**
80
- * Pre-compile all regex patterns for efficiency.
81
- * Includes ReDoS vulnerability detection and logging.
136
+ * Compile one content pattern. A pattern that does not compile is kept as "cannot be
137
+ * evaluated"; its text is not logged.
82
138
  */
83
- private compilePatterns;
139
+ private compilePattern;
84
140
  }
85
141
  /**
86
142
  * Create an event filter.
@@ -33,6 +33,10 @@ interface ExpressResponse {
33
33
  end(): void;
34
34
  flushHeaders?(): void;
35
35
  flush?(): void;
36
+ writableLength?: number;
37
+ writableFinished?: boolean;
38
+ destroy?(): void;
39
+ on?(event: string, handler: () => void): void;
36
40
  }
37
41
  /**
38
42
  * Express Router-like interface
@@ -46,18 +50,9 @@ interface ExpressRouter {
46
50
  /**
47
51
  * Create an Express router from SessionHandler
48
52
  *
49
- * @example
50
- * ```ts
51
- * import express from 'express';
52
- * import { createBroker, createSessionHandler, createExpressRouter } from '@enclave-vm/broker';
53
- *
54
- * const broker = createBroker();
55
- * const handler = createSessionHandler({ broker });
56
- * const router = createExpressRouter(handler);
57
- *
58
- * const app = express();
59
- * app.use('/api', router);
60
- * ```
53
+ * @deprecated The object this function returns registers no route: mounting it serves
54
+ * nothing. Use `registerExpressRoutes(app, handler)`, which registers the handler's routes on
55
+ * an Express application or router. The function is kept so that existing imports resolve.
61
56
  */
62
57
  export declare function createExpressRouter(handler: SessionHandler): ExpressRouter;
63
58
  /**
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Request validation
3
+ *
4
+ * What a request to the session routes must look like before any part of it is used. A request
5
+ * body is data of the caller: every field is checked for its type and its range here, and what
6
+ * is not a known field is not read at all.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ import type { SessionId, EventFilterConfig } from '@enclave-vm/types';
11
+ /**
12
+ * Outcome of a validation: the checked value, or the answer for the caller.
13
+ */
14
+ export type Validated<T> = {
15
+ ok: true;
16
+ value: T;
17
+ } | {
18
+ ok: false;
19
+ code: string;
20
+ message: string;
21
+ };
22
+ /**
23
+ * The limits a request may ask for, as they arrived (checked, not yet bounded).
24
+ */
25
+ export interface RequestedLimits {
26
+ maxExecutionMs?: number;
27
+ maxToolCalls?: number;
28
+ heartbeatIntervalMs?: number;
29
+ }
30
+ /**
31
+ * A checked body of `POST /sessions`.
32
+ */
33
+ export interface ParsedCreateSessionRequest {
34
+ code: string;
35
+ sessionId?: SessionId;
36
+ config: RequestedLimits;
37
+ filter?: EventFilterConfig;
38
+ }
39
+ /**
40
+ * Bounds of an event filter that arrives in a request. They keep the work a filter can cause
41
+ * per event small; an embedder that builds a filter in process is not bound by them.
42
+ */
43
+ export declare const REQUEST_FILTER_LIMITS: {
44
+ /** Rules per filter */
45
+ readonly maxRules: 16;
46
+ /** Content patterns per filter, over all rules */
47
+ readonly maxPatterns: 32;
48
+ /** Characters per pattern */
49
+ readonly maxPatternLength: 256;
50
+ /** Characters per field path */
51
+ readonly maxFieldLength: 128;
52
+ /** Event types per type filter and per always-allow list */
53
+ readonly maxTypes: 32;
54
+ /** Characters per event type */
55
+ readonly maxTypeLength: 64;
56
+ /** Characters of the JSON text in the `filter` query parameter */
57
+ readonly maxQueryLength: 8192;
58
+ /** Time limit for the evaluation of one event, in milliseconds */
59
+ readonly evaluationTimeoutMs: 100;
60
+ /** Time all evaluations of one filter may take together, in milliseconds */
61
+ readonly budgetMs: 500;
62
+ };
63
+ /**
64
+ * Whether a value is a session id a request may name.
65
+ */
66
+ export declare function isRequestSessionId(value: unknown): value is SessionId;
67
+ /**
68
+ * A plain JSON object: not null, not an array.
69
+ */
70
+ export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
71
+ /**
72
+ * Check the body of `POST /sessions`.
73
+ */
74
+ export declare function parseCreateSessionRequest(body: unknown): Validated<ParsedCreateSessionRequest>;
75
+ /**
76
+ * Check an event filter that arrived in a request and copy it. The copy holds the known fields
77
+ * only, each within the bounds of REQUEST_FILTER_LIMITS, and its time limit is the request
78
+ * limit or lower.
79
+ */
80
+ export declare function parseFilterConfig(value: unknown): Validated<EventFilterConfig>;
81
+ /**
82
+ * Check the `filter` query parameter of the stream route: JSON text of a filter.
83
+ */
84
+ export declare function parseFilterParameter(value: unknown): Validated<EventFilterConfig>;
@@ -25,7 +25,54 @@ export interface SessionHandlerConfig {
25
25
  * @default ['*']
26
26
  */
27
27
  allowedOrigins?: string[];
28
+ /**
29
+ * Request headers a cross-origin page may send, in addition to the ones the routes always
30
+ * allow: `Content-Type`, `Accept`, `Last-Event-ID` and `Authorization`. Name here what your
31
+ * clients send besides (an API-key header, a tenant header); a browser refuses to send a
32
+ * header the preflight answer does not list. Each entry is a header name.
33
+ * @default []
34
+ */
35
+ allowedHeaders?: string[];
36
+ /**
37
+ * Tells the routes who the caller of a request is.
38
+ *
39
+ * With this hook every session belongs to the caller that created it: the list holds the
40
+ * caller's own sessions, and reading, replaying and ending a session is answered only for its
41
+ * owner (another caller gets the answer of an id that does not exist). A request for which the
42
+ * hook returns no identity, or throws, is answered with 401.
43
+ *
44
+ * The hook receives the adapted request; `request.raw` is the request object of the HTTP
45
+ * framework, where an authentication middleware usually leaves its result. Return a stable,
46
+ * non-empty string per caller (a user id, a tenant id, an API key id).
47
+ *
48
+ * Without this hook the routes do not tell callers apart: whoever can reach them can list,
49
+ * read, replay and end every session. Mount them only where every caller is trusted alike.
50
+ */
51
+ identify?: CallerIdentifier;
52
+ /**
53
+ * Serve `GET /sessions` (the list of sessions).
54
+ * @default true
55
+ */
56
+ sessionList?: boolean;
57
+ /**
58
+ * Maximum number of streams one session has open at a time: the stream of the request that
59
+ * created it and the streams of `GET /sessions/:sessionId/stream`. A further stream is
60
+ * answered with 429.
61
+ * @default 8
62
+ */
63
+ maxStreamsPerSession?: number;
64
+ /**
65
+ * How far a reader may fall behind, in bytes written to it and not yet taken, before its
66
+ * stream is dropped. Dropping the stream of the request that created a session ends the
67
+ * session. Needs a response that reports `bufferedBytes()` (the Express adapter does).
68
+ * @default 8388608 (8MB)
69
+ */
70
+ maxBufferedBytes?: number;
28
71
  }
72
+ /**
73
+ * Returns the identity of the caller of a request, or nothing when there is none.
74
+ */
75
+ export type CallerIdentifier = (request: BrokerRequest) => string | null | undefined | Promise<string | null | undefined>;
29
76
  /**
30
77
  * Route handler function type
31
78
  */
@@ -39,6 +86,12 @@ export declare class SessionHandler {
39
86
  private readonly broker;
40
87
  private readonly cors;
41
88
  private readonly allowedOrigins;
89
+ private readonly allowedRequestHeaders;
90
+ private readonly identify?;
91
+ private readonly sessionList;
92
+ private readonly maxStreamsPerSession;
93
+ private readonly maxBufferedBytes;
94
+ private readonly streams;
42
95
  constructor(config: SessionHandlerConfig);
43
96
  /**
44
97
  * Get route definitions for registration with HTTP frameworks
@@ -57,7 +110,27 @@ export declare class SessionHandler {
57
110
  */
58
111
  handleCors(req: BrokerRequest, res: BrokerResponse): Promise<void>;
59
112
  /**
60
- * List all active sessions
113
+ * Who the caller of a request is.
114
+ *
115
+ * Without an `identify` hook there is no caller identity and every request passes. With one,
116
+ * a request without an identity is answered with 401 here and `undefined` is returned.
117
+ */
118
+ private callerOf;
119
+ /**
120
+ * Whether a caller may reach a session: always without an `identify` hook, otherwise only the
121
+ * caller that owns it. A session without an owner belongs to no caller.
122
+ */
123
+ private mayReach;
124
+ /**
125
+ * The session a request names, if it exists and its caller may reach it. Otherwise the answer
126
+ * has been sent (401, 400 or 404) and `undefined` is returned. A session of another caller is
127
+ * answered exactly like an id that does not exist.
128
+ */
129
+ private sessionOf;
130
+ /** Optional identifier for one creation, sent again on a conditional stop. */
131
+ private instanceIdOf;
132
+ /**
133
+ * List sessions: all of them, or the caller's own when callers are identified
61
134
  *
62
135
  * GET /sessions
63
136
  */
@@ -71,6 +144,10 @@ export declare class SessionHandler {
71
144
  * Returns NDJSON stream of events
72
145
  */
73
146
  createSession(req: BrokerRequest, res: BrokerResponse): Promise<void>;
147
+ /**
148
+ * Answer a failed session creation with a code and a fixed text.
149
+ */
150
+ private sendCreateFailure;
74
151
  /**
75
152
  * Get session information
76
153
  *
@@ -87,8 +164,19 @@ export declare class SessionHandler {
87
164
  * Terminate a session
88
165
  *
89
166
  * DELETE /sessions/:sessionId
167
+ * POST /sessions/:sessionId/cancel (the URL a session announces in its first event)
90
168
  */
91
169
  terminateSession(req: BrokerRequest, res: BrokerResponse): Promise<void>;
170
+ /**
171
+ * The filter for a configuration that arrived in a request and passed validation. It gets a
172
+ * budget for the whole stream, and its globs are matched without expansion.
173
+ */
174
+ private requestFilter;
175
+ /**
176
+ * The limits a request gets: what it asks for, never above what the broker is configured
177
+ * with. A request may lower a limit; it cannot raise one.
178
+ */
179
+ private boundLimits;
92
180
  /**
93
181
  * Convert BrokerSession to info response
94
182
  */
@@ -98,9 +186,19 @@ export declare class SessionHandler {
98
186
  */
99
187
  private sessionInfoToResponse;
100
188
  /**
101
- * Write a stream event as NDJSON
189
+ * Count one more stream of a session. Returns the function that gives the place back, or
190
+ * undefined when the session has as many streams as `maxStreamsPerSession` allows.
191
+ */
192
+ private acquireStream;
193
+ /**
194
+ * Write a stream event as NDJSON. Returns false when the reader of this response has fallen
195
+ * behind by more than `maxBufferedBytes`: it must be dropped, nothing more is written to it.
102
196
  */
103
197
  private writeEvent;
198
+ /**
199
+ * Close the connection of a reader that does not take what it is sent.
200
+ */
201
+ private dropReader;
104
202
  /**
105
203
  * Send an error response
106
204
  */
package/http/types.d.ts CHANGED
@@ -38,6 +38,12 @@ export interface BrokerRequest {
38
38
  * Abort signal for cancellation
39
39
  */
40
40
  signal?: AbortSignal;
41
+ /**
42
+ * The request object of the HTTP framework this request was adapted from, when the adapter
43
+ * provides it. An `identify` hook finds there what an authentication middleware left on the
44
+ * request.
45
+ */
46
+ raw?: unknown;
41
47
  }
42
48
  /**
43
49
  * HTTP response abstraction
@@ -58,7 +64,7 @@ export interface BrokerResponse {
58
64
  /**
59
65
  * Write data to response stream
60
66
  */
61
- write(data: string): void;
67
+ write(data: string): boolean | void;
62
68
  /**
63
69
  * End the response
64
70
  */
@@ -67,6 +73,17 @@ export interface BrokerResponse {
67
73
  * Flush the response buffer (for streaming)
68
74
  */
69
75
  flush?(): void;
76
+ /**
77
+ * How many bytes written to this response its reader has not taken yet. With it, a stream
78
+ * whose reader falls behind by more than `maxBufferedBytes` is dropped; an adapter that
79
+ * cannot tell leaves it out.
80
+ */
81
+ bufferedBytes?(): number;
82
+ /**
83
+ * Close the connection of this response without waiting for its reader. Used to drop a
84
+ * reader; without it the response is ended.
85
+ */
86
+ destroy?(): void;
70
87
  }
71
88
  /**
72
89
  * Create session request body
package/index.d.ts CHANGED
@@ -7,14 +7,17 @@
7
7
  */
8
8
  export { Broker, createBroker } from './broker';
9
9
  export type { BrokerConfig, ExecuteOptions } from './broker';
10
+ export { BrokerError, BrokerErrorCode } from './errors';
10
11
  export { ToolRegistry, createToolRegistry } from './tool-registry';
11
12
  export type { ToolDefinition, ToolHandler, ToolContext, ToolValidationResult, ToolExecutionResult, } from './tool-registry';
12
13
  export { BrokerSession, createBrokerSession } from './broker-session';
13
14
  export type { BrokerSessionConfig } from './broker-session';
15
+ export { DEFAULT_SESSION_HISTORY_LIMITS } from './session-history';
16
+ export type { SessionHistoryLimits } from './session-history';
14
17
  export { SessionManager, createSessionManager } from './session-manager';
15
18
  export type { SessionManagerConfig, SessionInfo, CreateSessionResult } from './session-manager';
16
19
  export { SessionHandler, createSessionHandler, registerExpressRoutes, createExpressRouter } from './http';
17
- export type { SessionHandlerConfig, RouteHandler, BrokerRequest, BrokerResponse, CreateSessionRequest, SessionInfoResponse, ListSessionsResponse, ErrorResponse, StreamOptions, } from './http';
20
+ export type { SessionHandlerConfig, CallerIdentifier, RouteHandler, BrokerRequest, BrokerResponse, CreateSessionRequest, SessionInfoResponse, ListSessionsResponse, ErrorResponse, StreamOptions, } from './http';
18
21
  export { EventFilter, createEventFilter, createTypeFilter, createContentFilter } from './event-filter';
19
22
  export type { EventFilterOptions } from './event-filter';
20
23
  export { OpenApiSpecPoller, OpenApiToolLoader, OpenApiSource, CatalogHandler } from './openapi';