@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/README.md +190 -139
- package/broker-session.d.ts +45 -2
- package/broker.d.ts +16 -2
- package/errors.d.ts +24 -0
- package/esm/index.mjs +1922 -663
- package/event-filter.d.ts +80 -24
- package/http/express-adapter.d.ts +7 -12
- package/http/request-validation.d.ts +84 -0
- package/http/session-handler.d.ts +100 -2
- package/http/types.d.ts +18 -1
- package/index.d.ts +4 -1
- package/index.js +1938 -670
- package/limits.d.ts +32 -0
- package/openapi/http-utils.d.ts +54 -0
- package/openapi/openapi-source.d.ts +29 -1
- package/openapi/openapi-spec-poller.d.ts +2 -0
- package/openapi/openapi-tool-loader.d.ts +22 -0
- package/package.json +4 -4
- package/session-history.d.ts +69 -0
- package/session-manager.d.ts +10 -2
package/limits.d.ts
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Session limits
|
|
3
|
+
*
|
|
4
|
+
* How the limits of a session are put together from the package defaults, the broker's
|
|
5
|
+
* configuration and the configuration of one session, and what a limit must be before it is used.
|
|
6
|
+
*
|
|
7
|
+
* @packageDocumentation
|
|
8
|
+
*/
|
|
9
|
+
import type { SessionLimits } from '@enclave-vm/types';
|
|
10
|
+
/**
|
|
11
|
+
* The longest delay a timer can hold.
|
|
12
|
+
*/
|
|
13
|
+
export declare const MAX_TIMER_MS: number;
|
|
14
|
+
/**
|
|
15
|
+
* A delay that a timer runs as given.
|
|
16
|
+
*/
|
|
17
|
+
export declare function timerDelay(ms: number): number;
|
|
18
|
+
/**
|
|
19
|
+
* Merge limit objects field by field. A later object replaces a field only when it gives it a
|
|
20
|
+
* value, so a session that names one limit keeps every other limit of the layers before it.
|
|
21
|
+
* Keys that are not session limits are dropped.
|
|
22
|
+
*/
|
|
23
|
+
export declare function mergeSessionLimits(...layers: Array<Partial<SessionLimits> | undefined>): Partial<SessionLimits>;
|
|
24
|
+
/**
|
|
25
|
+
* The complete limits of a session: the given fields over the package defaults.
|
|
26
|
+
*
|
|
27
|
+
* Every numeric limit must be a number. A limit ends up in the configuration of the sandbox and
|
|
28
|
+
* in timers, so a value of another type is refused here instead of being passed on.
|
|
29
|
+
*
|
|
30
|
+
* @throws TypeError when a limit has the wrong type
|
|
31
|
+
*/
|
|
32
|
+
export declare function resolveSessionLimits(limits?: Partial<SessionLimits>): Required<SessionLimits>;
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HTTP helpers of the OpenAPI integration
|
|
3
|
+
*
|
|
4
|
+
* What the broker reads from a specification host or an upstream is bounded in size, and the
|
|
5
|
+
* headers the embedder configured for one origin are not sent to another.
|
|
6
|
+
*
|
|
7
|
+
* @packageDocumentation
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* A response body is larger than the limit it is read with.
|
|
11
|
+
*/
|
|
12
|
+
export declare class ResponseTooLargeError extends Error {
|
|
13
|
+
readonly code = "RESPONSE_TOO_LARGE";
|
|
14
|
+
constructor(maxBytes: number);
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Whether two URLs have the same origin. A URL that cannot be parsed has no origin.
|
|
18
|
+
*/
|
|
19
|
+
export declare function sameOrigin(a: string, b: string): boolean;
|
|
20
|
+
/**
|
|
21
|
+
* Read a response body as text, up to `maxBytes`. Reading stops at the limit.
|
|
22
|
+
*
|
|
23
|
+
* @param truncate - return what was read up to the limit instead of throwing
|
|
24
|
+
* @throws ResponseTooLargeError when the body is larger and `truncate` is not set
|
|
25
|
+
*/
|
|
26
|
+
export declare function readBodyText(response: Response, maxBytes: number, truncate?: boolean): Promise<string>;
|
|
27
|
+
/**
|
|
28
|
+
* A request with the headers the embedder configured for its origin.
|
|
29
|
+
*/
|
|
30
|
+
export interface OriginBoundRequest {
|
|
31
|
+
method: string;
|
|
32
|
+
headers: Record<string, string>;
|
|
33
|
+
/**
|
|
34
|
+
* Headers that are no credential and follow a redirect to any origin, such as the validators of
|
|
35
|
+
* a conditional request (`If-None-Match`, `If-Modified-Since`). Sent with every request.
|
|
36
|
+
*/
|
|
37
|
+
portableHeaders?: Record<string, string>;
|
|
38
|
+
/**
|
|
39
|
+
* Send the configured headers again when a redirect comes back to the request's own origin
|
|
40
|
+
* after another (`A → B → A`). Off by default: what B chooses on A is then sent with A's
|
|
41
|
+
* headers.
|
|
42
|
+
*/
|
|
43
|
+
restoreOnOrigin?: boolean;
|
|
44
|
+
body?: BodyInit;
|
|
45
|
+
signal?: AbortSignal;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* `fetch` that keeps the request's headers on the origin they were configured for.
|
|
49
|
+
*
|
|
50
|
+
* Redirects are followed here, at most a few. A redirect within the origin of the request is
|
|
51
|
+
* followed with the same headers. A redirect to another origin is followed without them (a
|
|
52
|
+
* content type for a body that is sent again is kept), and they are not restored afterwards.
|
|
53
|
+
*/
|
|
54
|
+
export declare function fetchOriginBound(url: string, request: OriginBoundRequest): Promise<Response>;
|
|
@@ -35,6 +35,8 @@ export interface OpenApiSourceStats {
|
|
|
35
35
|
lastUpdate: string;
|
|
36
36
|
specHash: string;
|
|
37
37
|
pollHealth: SourceHealthStatus;
|
|
38
|
+
/** Message of the last failure, until a specification is applied again */
|
|
39
|
+
lastError?: string;
|
|
38
40
|
}
|
|
39
41
|
/**
|
|
40
42
|
* Tool update event data.
|
|
@@ -54,12 +56,20 @@ export declare class OpenApiSource extends EventEmitter {
|
|
|
54
56
|
private previousToolNames;
|
|
55
57
|
private lastUpdate;
|
|
56
58
|
private specHash;
|
|
57
|
-
private
|
|
59
|
+
private loaded;
|
|
60
|
+
private syncFailed;
|
|
61
|
+
private pollFailing;
|
|
62
|
+
private lastError;
|
|
58
63
|
private disposed;
|
|
59
64
|
private _syncLock;
|
|
60
65
|
constructor(toolRegistry: ToolRegistry, config: OpenApiSourceConfig);
|
|
61
66
|
/**
|
|
62
67
|
* Initial load + start polling.
|
|
68
|
+
*
|
|
69
|
+
* A failure while polling (a specification that cannot be fetched, parsed or applied) is
|
|
70
|
+
* reported with the `error` event when it has a listener, and always through `getStats()`:
|
|
71
|
+
* `pollHealth` becomes `unhealthy` and `lastError` holds the message. The tools of the last
|
|
72
|
+
* specification that was applied stay registered.
|
|
63
73
|
*/
|
|
64
74
|
start(): Promise<void>;
|
|
65
75
|
/**
|
|
@@ -68,12 +78,30 @@ export declare class OpenApiSource extends EventEmitter {
|
|
|
68
78
|
stop(): void;
|
|
69
79
|
/**
|
|
70
80
|
* Manual refresh (for webhook triggers).
|
|
81
|
+
*
|
|
82
|
+
* @throws when the specification cannot be fetched or applied; the registered tools are
|
|
83
|
+
* then what they were before
|
|
71
84
|
*/
|
|
72
85
|
refresh(): Promise<void>;
|
|
73
86
|
/**
|
|
74
87
|
* Sync tools based on a new spec (diff-based update).
|
|
75
88
|
*/
|
|
76
89
|
private syncTools;
|
|
90
|
+
/**
|
|
91
|
+
* Replace the tools of this source with the tools of a loaded specification, in one step:
|
|
92
|
+
* either every tool of the new specification is registered and every tool that is gone is
|
|
93
|
+
* removed, or nothing changes. A tool this source does not manage is never replaced.
|
|
94
|
+
*/
|
|
95
|
+
private applyTools;
|
|
96
|
+
/**
|
|
97
|
+
* Record a failure and tell the `error` listeners, if there are any. Without a listener the
|
|
98
|
+
* failure is kept for `getStats()`; it is never raised from here.
|
|
99
|
+
*/
|
|
100
|
+
private reportError;
|
|
101
|
+
/**
|
|
102
|
+
* Emit an event. A listener that throws does not stop the source.
|
|
103
|
+
*/
|
|
104
|
+
private notify;
|
|
77
105
|
/**
|
|
78
106
|
* Get the set of tool names managed by this source.
|
|
79
107
|
*/
|
|
@@ -42,6 +42,8 @@ export interface OpenApiPollerConfig {
|
|
|
42
42
|
unhealthyThreshold?: number;
|
|
43
43
|
/** Additional headers for fetch requests */
|
|
44
44
|
headers?: Record<string, string>;
|
|
45
|
+
/** Largest specification that is read, in bytes @default 33554432 (32MB) */
|
|
46
|
+
maxSpecBytes?: number;
|
|
45
47
|
}
|
|
46
48
|
/**
|
|
47
49
|
* Events emitted by the poller.
|
|
@@ -7,6 +7,10 @@
|
|
|
7
7
|
* @packageDocumentation
|
|
8
8
|
*/
|
|
9
9
|
import type { ToolDefinition } from '../tool-registry';
|
|
10
|
+
/**
|
|
11
|
+
* Largest specification that is read when the options name no limit.
|
|
12
|
+
*/
|
|
13
|
+
export declare const DEFAULT_MAX_SPEC_BYTES: number;
|
|
10
14
|
/**
|
|
11
15
|
* Options for the OpenAPI tool loader.
|
|
12
16
|
*/
|
|
@@ -25,6 +29,14 @@ export interface LoaderOptions {
|
|
|
25
29
|
perToolDeadlineMs?: number;
|
|
26
30
|
/** Source/service name prefix for default tool names (prevents collisions across sources) */
|
|
27
31
|
sourceName?: string;
|
|
32
|
+
/** Largest upstream response body a tool call reads, in bytes @default 10485760 (10MB) */
|
|
33
|
+
maxResponseBytes?: number;
|
|
34
|
+
/** Headers for the request that fetches the specification (`fromURL`) */
|
|
35
|
+
specHeaders?: Record<string, string>;
|
|
36
|
+
/** Timeout of the request that fetches the specification, body included, in ms @default 30000 */
|
|
37
|
+
specTimeoutMs?: number;
|
|
38
|
+
/** Largest specification that is read, in bytes @default 33554432 (32MB) */
|
|
39
|
+
maxSpecBytes?: number;
|
|
28
40
|
}
|
|
29
41
|
/**
|
|
30
42
|
* Authentication configuration for upstream API requests.
|
|
@@ -46,12 +58,22 @@ export declare class OpenApiToolLoader {
|
|
|
46
58
|
private constructor();
|
|
47
59
|
/**
|
|
48
60
|
* Create a loader from a URL.
|
|
61
|
+
*
|
|
62
|
+
* `auth` and `options.headers` belong to the upstream API. They go with the request for the
|
|
63
|
+
* specification only when the specification is on the origin of `options.baseUrl`, or when
|
|
64
|
+
* no base URL is given: the specification then decides where the tools send their requests,
|
|
65
|
+
* so its host is trusted with the credential either way. What the specification host itself
|
|
66
|
+
* needs goes into `options.specHeaders`.
|
|
49
67
|
*/
|
|
50
68
|
static fromURL(url: string, options?: LoaderOptions, auth?: UpstreamAuth): Promise<OpenApiToolLoader>;
|
|
51
69
|
/**
|
|
52
70
|
* Create a loader from a spec object.
|
|
53
71
|
*/
|
|
54
72
|
static fromSpec(spec: Record<string, unknown>, options?: LoaderOptions, auth?: UpstreamAuth): Promise<OpenApiToolLoader>;
|
|
73
|
+
/**
|
|
74
|
+
* Put the upstream credential into a set of request headers.
|
|
75
|
+
*/
|
|
76
|
+
private static applyAuth;
|
|
55
77
|
/**
|
|
56
78
|
* Get all loaded tool definitions.
|
|
57
79
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@enclave-vm/broker",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.20.0-rc.1",
|
|
4
4
|
"description": "Tool broker and session management for the EnclaveJS streaming runtime",
|
|
5
5
|
"author": "AgentFront <info@agentfront.dev>",
|
|
6
6
|
"homepage": "https://github.com/agentfront/enclave",
|
|
@@ -34,9 +34,9 @@
|
|
|
34
34
|
}
|
|
35
35
|
},
|
|
36
36
|
"dependencies": {
|
|
37
|
-
"@enclave-vm/core": "2.
|
|
38
|
-
"@enclave-vm/stream": "2.
|
|
39
|
-
"@enclave-vm/types": "2.
|
|
37
|
+
"@enclave-vm/core": "2.20.0-rc.1",
|
|
38
|
+
"@enclave-vm/stream": "2.20.0-rc.1",
|
|
39
|
+
"@enclave-vm/types": "2.20.0-rc.1",
|
|
40
40
|
"minimatch": "^11.0.1",
|
|
41
41
|
"zod": "^4.6.6"
|
|
42
42
|
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Session history
|
|
3
|
+
*
|
|
4
|
+
* The events a session keeps so that a client can replay what it missed. The history is the
|
|
5
|
+
* end of the session's event sequence, bounded in number and in size: when a bound is reached,
|
|
6
|
+
* the oldest events are dropped, and a replay can only start at an event that is still kept.
|
|
7
|
+
*
|
|
8
|
+
* @packageDocumentation
|
|
9
|
+
*/
|
|
10
|
+
import type { StreamEvent } from '@enclave-vm/types';
|
|
11
|
+
import { SessionEmitter } from '@enclave-vm/core';
|
|
12
|
+
import type { SessionEmitterConfig } from '@enclave-vm/core';
|
|
13
|
+
/**
|
|
14
|
+
* Bounds of the events a session keeps for a replay.
|
|
15
|
+
*/
|
|
16
|
+
export interface SessionHistoryLimits {
|
|
17
|
+
/**
|
|
18
|
+
* Maximum number of kept events.
|
|
19
|
+
* @default 10000
|
|
20
|
+
*/
|
|
21
|
+
maxEvents?: number;
|
|
22
|
+
/**
|
|
23
|
+
* Maximum size of the kept events together, measured as serialized JSON.
|
|
24
|
+
* @default 4194304 (4MB)
|
|
25
|
+
*/
|
|
26
|
+
maxBytes?: number;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Default bounds of a session's history.
|
|
30
|
+
*/
|
|
31
|
+
export declare const DEFAULT_SESSION_HISTORY_LIMITS: Required<SessionHistoryLimits>;
|
|
32
|
+
/**
|
|
33
|
+
* The complete history bounds: the given fields over the defaults.
|
|
34
|
+
*
|
|
35
|
+
* @throws TypeError when a bound is not a non-negative number
|
|
36
|
+
*/
|
|
37
|
+
export declare function resolveHistoryLimits(limits?: SessionHistoryLimits): Required<SessionHistoryLimits>;
|
|
38
|
+
/**
|
|
39
|
+
* A session emitter whose history is bounded.
|
|
40
|
+
*/
|
|
41
|
+
export declare class BoundedSessionEmitter extends SessionEmitter {
|
|
42
|
+
private readonly limits;
|
|
43
|
+
private kept;
|
|
44
|
+
private keptBytes;
|
|
45
|
+
private droppedThrough;
|
|
46
|
+
private ended;
|
|
47
|
+
/**
|
|
48
|
+
* Size of the event that is emitted next, when the caller knows it already. Used once.
|
|
49
|
+
*/
|
|
50
|
+
nextEventSize?: number;
|
|
51
|
+
constructor(config: SessionEmitterConfig, limits?: SessionHistoryLimits);
|
|
52
|
+
/**
|
|
53
|
+
* Emit a stream event: keep it within the bounds, then hand it to the listeners.
|
|
54
|
+
*/
|
|
55
|
+
emit(event: StreamEvent): void;
|
|
56
|
+
/**
|
|
57
|
+
* The kept events, oldest first.
|
|
58
|
+
*/
|
|
59
|
+
getEmittedEvents(): StreamEvent[];
|
|
60
|
+
/**
|
|
61
|
+
* Drop every kept event.
|
|
62
|
+
*/
|
|
63
|
+
clearHistory(): void;
|
|
64
|
+
/**
|
|
65
|
+
* The lowest sequence number a replay can start from: every event from there on is kept.
|
|
66
|
+
*/
|
|
67
|
+
get firstReplayableSeq(): number;
|
|
68
|
+
private keep;
|
|
69
|
+
}
|
package/session-manager.d.ts
CHANGED
|
@@ -38,6 +38,10 @@ export interface SessionInfo {
|
|
|
38
38
|
createdAt: number;
|
|
39
39
|
expiresAt: number;
|
|
40
40
|
isExpired: boolean;
|
|
41
|
+
/**
|
|
42
|
+
* The caller the session belongs to, if any
|
|
43
|
+
*/
|
|
44
|
+
owner?: string;
|
|
41
45
|
}
|
|
42
46
|
/**
|
|
43
47
|
* Session creation result
|
|
@@ -65,7 +69,11 @@ export declare class SessionManager {
|
|
|
65
69
|
/**
|
|
66
70
|
* Create a new session
|
|
67
71
|
*
|
|
68
|
-
*
|
|
72
|
+
* A session id names one session for as long as that session is registered: an id that is in
|
|
73
|
+
* use is refused.
|
|
74
|
+
*
|
|
75
|
+
* @throws BrokerError if the id is not usable or is in use, or if max sessions is reached
|
|
76
|
+
* @throws Error if the manager is disposed
|
|
69
77
|
*/
|
|
70
78
|
create(config?: BrokerSessionConfig): CreateSessionResult;
|
|
71
79
|
/**
|
|
@@ -87,7 +95,7 @@ export declare class SessionManager {
|
|
|
87
95
|
/**
|
|
88
96
|
* Terminate a session
|
|
89
97
|
*/
|
|
90
|
-
terminate(sessionId: SessionId, reason?: string): Promise<boolean>;
|
|
98
|
+
terminate(sessionId: SessionId, reason?: string, expectedSession?: BrokerSession): Promise<boolean>;
|
|
91
99
|
/**
|
|
92
100
|
* Execute code in a new session and wait for completion
|
|
93
101
|
*
|