@enclave-vm/runtime 2.20.0-rc.1 → 2.20.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 +48 -44
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,34 +1,24 @@
|
|
|
1
1
|
# @enclave-vm/runtime
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](LICENSE)
|
|
5
|
-
[](https://www.typescriptlang.org/)
|
|
6
|
-
|
|
7
|
-
> Building blocks of a runtime worker for EnclaveJS: session bookkeeping and channels
|
|
8
|
-
|
|
9
|
-
The @enclave-vm/runtime package contains the building blocks of a runtime worker: a worker object that keeps track of sessions, a session executor, and the channels between a worker and a broker.
|
|
3
|
+
Building blocks of an EnclaveJS runtime worker (session bookkeeping and channels), for developers who want to build a worker of their own. It does not execute code.
|
|
10
4
|
|
|
11
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@enclave-vm/runtime)
|
|
6
|
+
[](https://github.com/agentfront/enclave/blob/main/LICENSE)
|
|
7
|
+
[](https://nodejs.org)
|
|
12
8
|
|
|
13
|
-
|
|
9
|
+
The package builds on [`@enclave-vm/core`](https://www.npmjs.com/package/@enclave-vm/core) (sessions), [`@enclave-vm/stream`](https://www.npmjs.com/package/@enclave-vm/stream) and [`@enclave-vm/types`](https://www.npmjs.com/package/@enclave-vm/types). It contains a worker object that keeps track of sessions, a session executor, and the channels between a worker and a broker.
|
|
14
10
|
|
|
15
|
-
|
|
16
|
-
- **Session executor**: `SessionExecutor` holds one session and forwards its events to a channel
|
|
17
|
-
- **Channels**: `MemoryChannel` (in process) and `WebSocketChannel` (client side of a WebSocket connection)
|
|
18
|
-
- **`RuntimeNotImplementedError`**: thrown by the operations that are not implemented
|
|
19
|
-
- **`enclave-runtime`**: a command line program that says a standalone worker is not implemented and exits with an error
|
|
11
|
+
> **This package is not a runnable service.** It does not execute code, starts no server and opens no port. It has no authentication, no TLS, no CORS, no HTTP or WebSocket endpoints, no serverless entry points, and it reads no environment variables. An `execute` request never runs code: it ends with `RuntimeNotImplementedError`. To run scripts, use [`@enclave-vm/broker`](https://www.npmjs.com/package/@enclave-vm/broker) (sessions, tools and streaming over HTTP) or [`@enclave-vm/core`](https://www.npmjs.com/package/@enclave-vm/core) (the sandbox).
|
|
20
12
|
|
|
21
|
-
##
|
|
13
|
+
## Install
|
|
22
14
|
|
|
23
15
|
```bash
|
|
24
16
|
npm install @enclave-vm/runtime
|
|
25
|
-
# or
|
|
26
|
-
yarn add @enclave-vm/runtime
|
|
27
|
-
# or
|
|
28
|
-
pnpm add @enclave-vm/runtime
|
|
29
17
|
```
|
|
30
18
|
|
|
31
|
-
|
|
19
|
+
Requires Node.js 18 or later. `WebSocketChannel` also needs the `ws` package where there is no global `WebSocket` (see [Channels](#channels)).
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
32
22
|
|
|
33
23
|
```typescript
|
|
34
24
|
import { createRuntimeWorker, createMemoryChannel, RuntimeNotImplementedError } from '@enclave-vm/runtime';
|
|
@@ -55,7 +45,7 @@ console.log(worker.getSessions()); // []
|
|
|
55
45
|
await worker.stop();
|
|
56
46
|
```
|
|
57
47
|
|
|
58
|
-
## Runtime
|
|
48
|
+
## Runtime worker
|
|
59
49
|
|
|
60
50
|
`createRuntimeWorker(config?)` returns a worker (the class is exported as `RuntimeWorkerImpl`).
|
|
61
51
|
|
|
@@ -70,25 +60,25 @@ await worker.stop();
|
|
|
70
60
|
|
|
71
61
|
`handleRequest()` trusts its caller: nothing authenticates a request or checks where it came from.
|
|
72
62
|
|
|
73
|
-
- **`execute`** never runs the code. A valid request rejects with `RuntimeNotImplementedError` (code `NOT_IMPLEMENTED`): the channel receives `session_init`, then a `final` event with `ok: false` and `error.code: 'NOT_IMPLEMENTED'`, and the session is removed again. A request to a worker that is not running,
|
|
63
|
+
- **`execute`** never runs the code. A valid request rejects with `RuntimeNotImplementedError` (code `NOT_IMPLEMENTED`): the channel receives `session_init`, then a `final` event with `ok: false` and `error.code: 'NOT_IMPLEMENTED'`, and the session is removed again. A request to a worker that is not running, a request without a string `code`, a session id that is in use, or a worker at `maxSessions` rejects with another error.
|
|
74
64
|
- **`cancel`** cancels the session with that id if the worker holds it. Otherwise the request is ignored.
|
|
75
65
|
- **`tool_result`** passes the result to the session with that id if the worker holds it. Otherwise the request is ignored.
|
|
76
66
|
- **`ping`** is accepted. Nothing is sent back.
|
|
77
67
|
|
|
78
68
|
### Configuration
|
|
79
69
|
|
|
80
|
-
| Option | Default |
|
|
81
|
-
| --------------------- | ------------- | --------------------------------------------------------------------------------------- |
|
|
82
|
-
| `maxSessions` | `10` | Maximum number of sessions the worker holds. A positive integer, otherwise `RangeError` |
|
|
83
|
-
| `debug` | `false` | Log to the console |
|
|
84
|
-
| `port` | `3001` | Not used: no server is started |
|
|
85
|
-
| `host` | `'127.0.0.1'` | Not used: no server is started |
|
|
86
|
-
| `wsPath` | `'/ws'` | Not used: no server is started |
|
|
87
|
-
| `defaultLimits` | `{}` | Accepted, not read by the worker |
|
|
88
|
-
| `heartbeatIntervalMs` | `15000` | Accepted, not read by the worker |
|
|
89
|
-
| `connectionTimeoutMs` | `30000` | Accepted, not read by the worker |
|
|
70
|
+
| Option | Type | Default | Meaning |
|
|
71
|
+
| --------------------- | ------------------------ | ------------- | --------------------------------------------------------------------------------------- |
|
|
72
|
+
| `maxSessions` | `number` | `10` | Maximum number of sessions the worker holds. A positive integer, otherwise `RangeError` |
|
|
73
|
+
| `debug` | `boolean` | `false` | Log to the console |
|
|
74
|
+
| `port` | `number` | `3001` | Not used: no server is started |
|
|
75
|
+
| `host` | `string` | `'127.0.0.1'` | Not used: no server is started |
|
|
76
|
+
| `wsPath` | `string` | `'/ws'` | Not used: no server is started |
|
|
77
|
+
| `defaultLimits` | `Partial<SessionLimits>` | `{}` | Accepted, not read by the worker |
|
|
78
|
+
| `heartbeatIntervalMs` | `number` | `15000` | Accepted, not read by the worker |
|
|
79
|
+
| `connectionTimeoutMs` | `number` | `30000` | Accepted, not read by the worker |
|
|
90
80
|
|
|
91
|
-
## Session
|
|
81
|
+
## Session executor
|
|
92
82
|
|
|
93
83
|
`createSessionExecutor({ sessionId?, code, limits?, channel, debug? })` creates a `SessionExecutor`. It keeps the code and never runs it.
|
|
94
84
|
|
|
@@ -120,10 +110,10 @@ await remote.connect();
|
|
|
120
110
|
- It sends no credentials. Authenticate the connection in the server behind the URL.
|
|
121
111
|
- It parses incoming messages as JSON and hands them to the handlers without validating them against a schema. Validate them in the handler.
|
|
122
112
|
- While it is not connected it keeps at most `maxBufferedMessages` events (default 1000) and drops the rest.
|
|
123
|
-
- It reconnects with exponential backoff (`reconnect.maxRetries`, default 5).
|
|
113
|
+
- It reconnects with exponential backoff (`reconnect.maxRetries`, default 5). `connectionTimeoutMs` defaults to 10000.
|
|
124
114
|
- Where there is no global `WebSocket`, it needs the `ws` package, which is not installed with this package.
|
|
125
115
|
|
|
126
|
-
## Command
|
|
116
|
+
## Command line
|
|
127
117
|
|
|
128
118
|
```bash
|
|
129
119
|
npx enclave-runtime --help
|
|
@@ -131,16 +121,30 @@ npx enclave-runtime --help
|
|
|
131
121
|
|
|
132
122
|
The `enclave-runtime` program does not start a worker. It checks its arguments (`--port`, `--host`, `--max-sessions`, `--debug`), prints that a standalone worker is not implemented, and exits with code 1. `--help` prints the help and exits with code 0.
|
|
133
123
|
|
|
134
|
-
##
|
|
124
|
+
## Security notes
|
|
125
|
+
|
|
126
|
+
- Nothing in this package authenticates or authorizes: `handleRequest()` acts on every request it is given, and `WebSocketChannel` sends no credentials.
|
|
127
|
+
- There is no transport security of its own: no TLS and no encryption. Use a `wss:` URL and authenticate in the server you connect to.
|
|
128
|
+
- Messages received over a `WebSocketChannel` are not validated.
|
|
129
|
+
- No code is executed, so no sandbox is involved. For sandboxed execution see `@enclave-vm/core` and `@enclave-vm/broker`.
|
|
130
|
+
|
|
131
|
+
## Related packages
|
|
132
|
+
|
|
133
|
+
| Package | Role |
|
|
134
|
+
| ---------------------------------------------------------------------- | --------------------------------------- |
|
|
135
|
+
| [@enclave-vm/core](https://www.npmjs.com/package/@enclave-vm/core) | The sandbox that executes scripts |
|
|
136
|
+
| [@enclave-vm/broker](https://www.npmjs.com/package/@enclave-vm/broker) | Tool broker, sessions and HTTP routes |
|
|
137
|
+
| [@enclave-vm/types](https://www.npmjs.com/package/@enclave-vm/types) | Protocol types and Zod schemas |
|
|
138
|
+
| [@enclave-vm/stream](https://www.npmjs.com/package/@enclave-vm/stream) | NDJSON and reconnection helpers |
|
|
139
|
+
| [@enclave-vm/client](https://www.npmjs.com/package/@enclave-vm/client) | Browser and Node.js client for a broker |
|
|
140
|
+
|
|
141
|
+
## Documentation
|
|
135
142
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
| [@enclave-vm/stream](../stream) | Streaming protocol implementation |
|
|
141
|
-
| [@enclave-vm/broker](../broker) | Tool broker and session management |
|
|
142
|
-
| [@enclave-vm/client](../client) | Browser/Node.js client SDK |
|
|
143
|
+
- Documentation: https://agentfront.dev/docs/guides/enclave
|
|
144
|
+
- Repository: https://github.com/agentfront/enclave
|
|
145
|
+
- Architecture: https://github.com/agentfront/enclave/blob/main/README-ARCHITECTURE.md
|
|
146
|
+
- Security policy: https://github.com/agentfront/enclave/blob/main/SECURITY.md
|
|
143
147
|
|
|
144
148
|
## License
|
|
145
149
|
|
|
146
|
-
Apache-2.0
|
|
150
|
+
Apache-2.0. See [LICENSE](https://github.com/agentfront/enclave/blob/main/LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@enclave-vm/runtime",
|
|
3
|
-
"version": "2.20.
|
|
3
|
+
"version": "2.20.1",
|
|
4
4
|
"description": "Building blocks of a runtime worker for EnclaveJS: session bookkeeping and channels (does not execute code)",
|
|
5
5
|
"author": "AgentFront <info@agentfront.dev>",
|
|
6
6
|
"homepage": "https://github.com/agentfront/enclave",
|
|
@@ -36,9 +36,9 @@
|
|
|
36
36
|
"enclave-runtime": "./cli.js"
|
|
37
37
|
},
|
|
38
38
|
"dependencies": {
|
|
39
|
-
"@enclave-vm/core": "2.20.
|
|
40
|
-
"@enclave-vm/stream": "2.20.
|
|
41
|
-
"@enclave-vm/types": "2.20.
|
|
39
|
+
"@enclave-vm/core": "2.20.1",
|
|
40
|
+
"@enclave-vm/stream": "2.20.1",
|
|
41
|
+
"@enclave-vm/types": "2.20.1"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
44
|
"ws": "^8.19.0"
|