@tinyactors/node 0.1.0 → 0.3.0

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.
Files changed (43) hide show
  1. package/README.md +648 -154
  2. package/docs/guide/browser.md +494 -0
  3. package/docs/guide/capacity.md +202 -0
  4. package/docs/guide/charts.md +578 -0
  5. package/docs/guide/hibernation.md +201 -0
  6. package/docs/guide/inspection.md +381 -0
  7. package/docs/guide/io-processors.md +269 -0
  8. package/docs/guide/migration.md +323 -0
  9. package/docs/guide/other-systems.md +275 -0
  10. package/docs/guide/quickjs.md +135 -0
  11. package/docs/guide/services.md +317 -0
  12. package/docs/guide/snapshots.md +186 -0
  13. package/docs/guide/telemetry.md +265 -0
  14. package/docs/guide/testing.md +272 -0
  15. package/docs/values.md +107 -0
  16. package/index.d.ts +1166 -1820
  17. package/index.mjs +6 -0
  18. package/lib/convenience.mjs +162 -0
  19. package/lib/direct.mjs +65 -0
  20. package/package.json +29 -16
  21. package/index.js +0 -34
  22. package/lib/actor.js +0 -85
  23. package/lib/debug/breakpoints.js +0 -349
  24. package/lib/debug/console.js +0 -149
  25. package/lib/debug/expressions.js +0 -133
  26. package/lib/debug/frames.js +0 -119
  27. package/lib/debug/labels.js +0 -142
  28. package/lib/debug/macrosteps.js +0 -207
  29. package/lib/debug/protocol.js +0 -186
  30. package/lib/debug/sources.js +0 -218
  31. package/lib/debug/variables.js +0 -265
  32. package/lib/debug.js +0 -1434
  33. package/lib/definition.js +0 -139
  34. package/lib/errors.js +0 -24
  35. package/lib/events.js +0 -56
  36. package/lib/image.js +0 -90
  37. package/lib/loader.js +0 -68
  38. package/lib/metrics.js +0 -333
  39. package/lib/native.js +0 -8
  40. package/lib/otlp.js +0 -332
  41. package/lib/statechart.js +0 -768
  42. package/lib/system.js +0 -2183
  43. package/lib/tracing.js +0 -164
@@ -0,0 +1,275 @@
1
+ # Other systems
2
+
3
+ A host is one **system**, named by its `systemID`. An actor of one system
4
+ can send to an actor of another (another host, in this process or on
5
+ another machine) by its address, `tinyactors://<systemID>/...`. The host
6
+ decides whether an address is its own. A send to another system goes to
7
+ your **transport**, a handler that carries it there; the other side
8
+ gives it to its host with `host.send`. The transport and the wire are
9
+ yours: a socket, a queue, HTTP, a worker's `postMessage`.
10
+
11
+ ## Two systems
12
+
13
+ Each send to another system reaches the `transport` handler as a `Send`.
14
+ Its `target` and `origin` are `Address`es, and its `message` is the
15
+ outgoing half, an object of `target`, `event`, `data`, `sendid`,
16
+ `origin` and `traceparent` (`null` for a field the send lacks), which
17
+ the receiving side passes to `host.send(message)` as it is, in this
18
+ process or in another binding's: a Python host takes it too. On a wire,
19
+ `encode` writes the message as it is, its addresses as CBOR's tag 32 (as
20
+ a Python host's `encode` does), and `decode` reads them back as
21
+ `Address`es. (`JSON.stringify` writes an `Address` as its text, so a
22
+ message goes through JSON as it is: see "Addresses" below.)
23
+
24
+ ```js
25
+ import { Address, compileCharts, decode, encode, Host } from '@tinyactors/node';
26
+
27
+ const shopChart = `
28
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
29
+ datamodel="ecmascript" name="checkout" initial="paying">
30
+ <state id="paying">
31
+ <onentry>
32
+ <send event="charge" target="tinyactors://bank/@teller"><param name="amount" expr="12"/></send>
33
+ </onentry>
34
+ <transition event="approved" target="done"><log expr="'approved by ' + _event.origin"/></transition>
35
+ </state>
36
+ <final id="done"/>
37
+ </scxml>`;
38
+ const bankChart = `
39
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
40
+ datamodel="ecmascript" name="teller" initial="open">
41
+ <state id="open">
42
+ <transition event="charge">
43
+ <log expr="'charging ' + _event.data.amount + ' for ' + _event.origin"/>
44
+ <send event="approved" targetexpr="_event.origin"/>
45
+ </transition>
46
+ </state>
47
+ </scxml>`;
48
+
49
+ const image = (name, text) => {
50
+ const compiled = compileCharts([{ name, text }]);
51
+ const bytes = compiled.image;
52
+ compiled.close();
53
+ return bytes;
54
+ };
55
+
56
+ // The wire: bytes in a queue, delivered on a later turn of the event loop.
57
+ const hosts = {};
58
+ const wire = (message) => {
59
+ const bytes = encode(message);
60
+ setTimeout(() => {
61
+ const received = decode(bytes);
62
+ hosts[received.target.system].send(received);
63
+ });
64
+ };
65
+
66
+ const log = (host, entry) => console.log(entry.text);
67
+ hosts.shop = new Host({ systemID: 'shop' }, { log, transport: (host, send) => wire(send.message) });
68
+ hosts.bank = new Host({ systemID: 'bank' }, { log, transport: (host, send) => wire(send.message) });
69
+ hosts.shop.addImage(image('checkout.scxml', shopChart));
70
+ hosts.bank.addImage(image('teller.scxml', bankChart));
71
+
72
+ hosts.bank.spawn(hosts.bank.chart('teller'), { name: 'teller' });
73
+ hosts.shop.spawn(hosts.shop.chart('checkout'));
74
+ await new Promise((resolve) => setTimeout(resolve, 50));
75
+ await Promise.all([hosts.shop.idle(), hosts.bank.idle()]);
76
+ hosts.shop.close();
77
+ hosts.bank.close();
78
+ ```
79
+
80
+ ```output
81
+ charging 12 for tinyactors://shop/#_scxml_1
82
+ approved by tinyactors://bank/#_scxml_1
83
+ ```
84
+
85
+ The receiver answers to `_event.origin`, which is the sender's full
86
+ address, so the answer goes back through the bank's transport.
87
+
88
+ **A send that cannot be delivered** is the transport's to report. While
89
+ the handler runs, `send.fail()` does it. Later, on the sending host,
90
+ `host.fail(sender, sendid)` does, where `sender` is the message's
91
+ `origin` (the actor that sent it, not its target): the sender gets
92
+ `error.communication` with that `sendid`.
93
+ Delivery that worked needs no answer. Without a `transport` handler, each
94
+ send to another system is failed.
95
+
96
+ **An input's target may be an address.** `host.send` takes a session, an
97
+ address string or an `Address`; a local address (`tinyactors://shop/@teller`
98
+ on the host named `shop`) is resolved by the host to its actor. A message's
99
+ `origin` is the sender's address as the other side gave it, and becomes
100
+ the event's `_event.origin`.
101
+
102
+ ## Over a socket
103
+
104
+ Across processes, a transport writes each message as a frame on a
105
+ connection. Over TCP, call `socket.setNoDelay(true)` on both ends: the
106
+ frames are small, and an answer is often a frame too, so with Nagle's
107
+ algorithm on (Node.js's default) a second small write waits for the
108
+ peer's delayed acknowledgement, about 40 ms on Linux's loopback, before
109
+ it leaves. (Python's asyncio turns it off by itself.) Here each frame is
110
+ four bytes of length and the message's CBOR:
111
+
112
+ ```js
113
+ import { connect, createServer } from 'node:net';
114
+ import { decode, encode, Host } from '@tinyactors/node';
115
+
116
+ /** Calls `receive` with each message the frames on `socket` hold. */
117
+ function frames(socket, receive) {
118
+ let buffered = Buffer.alloc(0);
119
+ socket.on('data', (chunk) => {
120
+ buffered = Buffer.concat([buffered, chunk]);
121
+ while (buffered.length >= 4 && buffered.length >= 4 + buffered.readUInt32BE(0)) {
122
+ const length = buffered.readUInt32BE(0);
123
+ receive(decode(buffered.subarray(4, 4 + length)));
124
+ buffered = buffered.subarray(4 + length);
125
+ }
126
+ });
127
+ }
128
+ const frame = (message) => {
129
+ const body = encode(message);
130
+ const head = Buffer.alloc(4);
131
+ head.writeUInt32BE(body.length);
132
+ return Buffer.concat([head, body]);
133
+ };
134
+
135
+ let toBank;
136
+ let toShop;
137
+ const log = (host, entry) => console.log(entry.text);
138
+ const shop = new Host({ systemID: 'shop' }, { log, transport: (host, send) => toBank.write(frame(send.message)) });
139
+ const bank = new Host({ systemID: 'bank' }, { log, transport: (host, send) => toShop.write(frame(send.message)) });
140
+ shop.addCharts({ 'checkout.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="checkout">
141
+ <state id="paying">
142
+ <onentry><send event="charge" target="tinyactors://bank/@teller"/></onentry>
143
+ <transition event="approved" target="done"><log expr="'approved'"/></transition>
144
+ </state>
145
+ <final id="done"/>
146
+ </scxml>` });
147
+ bank.addCharts({ 'teller.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="teller">
148
+ <state id="s"><transition event="charge"><log expr="'charging ' + _event.origin"/><send event="approved" targetexpr="_event.origin"/></transition></state>
149
+ </scxml>` });
150
+
151
+ // The bank listens on a port of the system's choosing; the shop connects.
152
+ const server = createServer((socket) => {
153
+ socket.setNoDelay(true);
154
+ toShop = socket;
155
+ frames(socket, (message) => bank.send(message));
156
+ });
157
+ await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
158
+ toBank = connect(server.address().port, '127.0.0.1');
159
+ toBank.setNoDelay(true);
160
+ frames(toBank, (message) => shop.send(message));
161
+ await new Promise((resolve) => toBank.once('connect', resolve));
162
+ await new Promise((resolve) => setImmediate(resolve)); // the server's side of the connection
163
+
164
+ bank.spawnChart('teller', { name: 'teller' });
165
+ const order = shop.spawnChart('checkout', { name: 'order' });
166
+ while (shop.actorByName('order') !== undefined) await new Promise((resolve) => setTimeout(resolve, 5));
167
+ console.log('order', order, 'ended');
168
+ toBank.end();
169
+ server.close();
170
+ shop.close();
171
+ bank.close();
172
+ ```
173
+
174
+ ```output
175
+ charging tinyactors://shop/#_scxml_1
176
+ approved
177
+ order 1n ended
178
+ ```
179
+
180
+ A frame that cannot be written, or a peer that is gone, is the transport's
181
+ to report: `send.fail()` while its handler runs, `host.fail(origin,
182
+ sendid)` after.
183
+
184
+ ## Addresses
185
+
186
+ `new Address(text)` reads an address; its `system`, `session` (a
187
+ `bigint`) and `name` are its parts, `undefined` for a part the text
188
+ lacks. `Address.fromSession(system, session)` and `Address.fromName(system,
189
+ name)` make one, and `toString()` gives the text:
190
+
191
+ ```js
192
+ import { Address } from '@tinyactors/node';
193
+
194
+ const bySession = Address.fromSession('shop', 42n);
195
+ const byName = Address.fromName('shop', 'front desk');
196
+ console.log(bySession.text, bySession.system, bySession.session);
197
+ console.log(byName.text, byName.name);
198
+ console.log(new Address('not an address').system);
199
+ ```
200
+
201
+ ```output
202
+ tinyactors://shop/#_scxml_42 shop 42n
203
+ tinyactors://shop/@front%20desk front desk
204
+ undefined
205
+ ```
206
+
207
+ `JSON.stringify` writes an address as its text (`address.toJSON()`), and
208
+ `new Address(text)` reads it back, so a transport's `send.message` goes
209
+ through JSON and into the other side's `host.send` as it is:
210
+
211
+ ```js
212
+ import { Address, Host } from '@tinyactors/node';
213
+
214
+ let wire;
215
+ const shop = new Host({ systemID: 'shop' }, { transport: (host, send) => { wire = JSON.stringify(send.message); } });
216
+ const bank = new Host({ systemID: 'bank' }, { log: (host, entry) => console.log(entry.text) });
217
+ shop.addCharts({ 'checkout.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="checkout">
218
+ <state id="s"><onentry><send event="charge" target="tinyactors://bank/@teller"><param name="amount" expr="12"/></send></onentry></state>
219
+ </scxml>` });
220
+ bank.addCharts({ 'teller.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="teller">
221
+ <state id="s"><transition event="charge"><log expr="'charge ' + _event.data.amount + ' from ' + _event.origin"/></transition></state>
222
+ </scxml>` });
223
+ bank.spawnChart('teller', { name: 'teller' });
224
+ shop.spawnChart('checkout');
225
+ await shop.idle();
226
+
227
+ const message = JSON.parse(wire); // its addresses are strings
228
+ console.log(typeof message.target, message.target);
229
+ bank.send(message);
230
+ await bank.idle();
231
+ console.log(new Address(message.origin).session);
232
+ shop.close();
233
+ bank.close();
234
+ ```
235
+
236
+ ```output
237
+ string tinyactors://bank/@teller
238
+ charge 12 from tinyactors://shop/#_scxml_1
239
+ 1n
240
+ ```
241
+
242
+ Inside event data an address is plain text: values have no address type.
243
+
244
+ ## SCXML's BasicHTTP
245
+
246
+ SCXML defines an HTTP processor, BasicHTTP, whose events travel as form
247
+ posts. The package has its codec, for an I/O processor or a server of
248
+ your own: `encodeHTTPPost({ url, event, fields, body })` writes the
249
+ request a send makes, as bytes for a socket, and
250
+ `parseHTTPRequest(bytes)` reads an incoming request's event (its
251
+ `_scxmleventname` field, or `HTTP.<METHOD>`) and its form fields.
252
+
253
+ ```js
254
+ import { encodeHTTPPost, parseHTTPRequest } from '@tinyactors/node';
255
+
256
+ const request = encodeHTTPPost({
257
+ url: 'http://localhost:8080/scxml',
258
+ event: 'order.placed',
259
+ fields: [{ name: 'sku', value: 'tea' }, { name: 'qty', value: '2' }],
260
+ });
261
+ console.log(new TextDecoder().decode(request).split('\r\n')[0]);
262
+
263
+ const incoming = parseHTTPRequest(request);
264
+ console.log(incoming.method, incoming.target, incoming.event);
265
+ console.log(incoming.fields.map(({ name, value }) => `${name}=${value}`).join(' '));
266
+ ```
267
+
268
+ ```output
269
+ POST /scxml HTTP/1.1
270
+ POST /scxml order.placed
271
+ sku=tea qty=2
272
+ ```
273
+
274
+ The host does no HTTP itself: sending the bytes and serving the port are
275
+ your program's.
@@ -0,0 +1,135 @@
1
+ # The quickjs sandbox
2
+
3
+ A host runs its charts' JavaScript on one of two datamodels. They take
4
+ the same charts, and a host uses one of them for all its charts:
5
+
6
+ - **`native`** (the default) runs chart code in `node:vm` contexts of
7
+ your own engine, V8 under Node.js and JavaScriptCore under Bun. It is
8
+ fast and its values are your engine's, but a `vm` context is not a
9
+ security boundary: a chart can reach the process it runs in.
10
+ - **`quickjs`** runs chart code in QuickJS, a separate JavaScript engine
11
+ compiled into the package, with no I/O at all (no modules, no timers,
12
+ no files, no network) and limits on how long an evaluation runs and how
13
+ much memory the engine takes.
14
+
15
+ Choose quickjs for charts you did not write or do not trust: charts your
16
+ users upload, charts from another team's service, charts generated by a
17
+ program. Chart code on the native datamodel is trusted code.
18
+
19
+ ```js
20
+ import { compileCharts, Host } from '@tinyactors/node';
21
+
22
+ const compiled = compileCharts([{ name: 'uploaded.scxml', text: `
23
+ <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
24
+ datamodel="ecmascript" name="uploaded" initial="s">
25
+ <state id="s">
26
+ <transition event="spin"><script>while (true) {}</script></transition>
27
+ <transition event="hog"><script>const hoard = []; for (;;) hoard.push(new Array(1000).fill(1));</script></transition>
28
+ <transition event="peek"><log expr="typeof process + ' ' + typeof require + ' ' + typeof setTimeout"/></transition>
29
+ <transition event="error.execution"><log expr="'stopped: error.execution'"/></transition>
30
+ </state>
31
+ </scxml>` }]);
32
+
33
+ const host = new Host({ systemID: 'sandbox' }, {
34
+ datamodel: 'quickjs',
35
+ quickjs: { maxOps: 1000, memoryLimit: 16 * 1024 * 1024 },
36
+ log: (host, entry) => console.log(entry.text),
37
+ });
38
+ host.addImage(compiled.image);
39
+ compiled.close();
40
+
41
+ const actor = host.spawn(host.chart('uploaded'));
42
+ host.send(actor, 'spin');
43
+ host.send(actor, 'hog');
44
+ host.send(actor, 'peek');
45
+ await host.idle();
46
+ host.close();
47
+ ```
48
+
49
+ ```output
50
+ stopped: error.execution
51
+ stopped: error.execution
52
+ undefined undefined undefined
53
+ ```
54
+
55
+ An evaluation that runs too long or asks for too much memory is stopped,
56
+ and the actor gets `error.execution`, as for any expression that throws;
57
+ it goes on with its next event.
58
+
59
+ ## The limits
60
+
61
+ `options.quickjs`, with `datamodel: 'quickjs'` only (with the native
62
+ datamodel it is a `TypeError`):
63
+
64
+ | Option | Default | What it bounds |
65
+ |---|---|---|
66
+ | `maxOps` | 1,000,000 | the engine's interrupt checks one evaluation may make before it is stopped |
67
+ | `memoryLimit` | 1 GiB (`2 ** 30`) | bytes for the whole engine, every actor of the host together |
68
+ | `stackLimit` | the engine's | bytes of native stack for JavaScript |
69
+ | `realm` | `'auto'` | `'isolated'` gives every actor a context of its own (below) |
70
+
71
+ The default `memoryLimit` keeps a runaway allocation from taking the
72
+ process: a loop that allocates ends in `error.execution` once the engine
73
+ holds 1 GiB, where without a limit it would grow until the system killed
74
+ the process. It is sized for a host of tens of thousands of resident
75
+ actors (40,000 take about 112 MB of engine heap); a host meant to keep
76
+ more resident sets a larger one, and `Number.MAX_SAFE_INTEGER` is as
77
+ good as none. For untrusted charts set both `maxOps` and a
78
+ `memoryLimit` of your own, as small as their real work allows. `maxOps` is
79
+ not time: it counts the engine's interrupt checks, one for every 10,000
80
+ jumps and calls QuickJS counts down, and how long a check takes depends
81
+ on the code between them. The time a looping evaluation holds
82
+ the host (and every host of the thread, since they share it), measured
83
+ on x86_64 Linux, Intel Xeon @ 2.10GHz, node 22 and bun 1.4.1 alike
84
+ (2026-10-18):
85
+
86
+ | Loop | `maxOps: 200` | `1000` | `10_000` | the default, 1,000,000 |
87
+ |---|---|---|---|---|
88
+ | `while (true) {}` | 6 ms | 27 to 39 ms | 260 ms | 26 s |
89
+ | `while (_event.data.value !== null) {}` | 50 ms | 240 to 250 ms | 2.5 to 2.7 s | about 256 s |
90
+
91
+ So a check costs 26 to 250 microseconds here, and the default lets one
92
+ runaway evaluation stop the process's hosts for minutes. Choose `maxOps`
93
+ by the longest stall your other actors can take: a few hundred (5 to 50
94
+ ms) for a service that answers requests, 1000 (about 25 to 250 ms) for
95
+ background work, and measure your own charts' real work against it,
96
+ since an evaluation that needs more checks than `maxOps` fails every
97
+ time. `maxOps` does not bound memory: a loop that allocates can take
98
+ gigabytes in fewer checks, which `memoryLimit` stops. An evaluation
99
+ stopped by `maxOps` gets `error.execution` with `_event.data.reason`
100
+ `'fuel'`, one stopped by `memoryLimit` `'memory'`.
101
+
102
+ ## Realms
103
+
104
+ By default (`realm: 'auto'`) the actors of a chart that declares no
105
+ top-level names share one context, each a small scope object, as on the
106
+ native datamodel; a chart whose scripts declare top-level names gives
107
+ each of its actors a context of its own. The shared context's global object is frozen, so a chart
108
+ cannot add globals, but the builtins (`Math`, `Array.prototype`, ...)
109
+ are shared by every actor of the host: a chart that changes one changes
110
+ it for the others. With `realm: 'isolated'` every actor gets a context of
111
+ its own, at the cost of its memory, so no chart sees another's changes.
112
+
113
+ ## What differs from the native datamodel
114
+
115
+ The same chart runs on both, and what a chart can observe is the same
116
+ SCXML. Around the edges:
117
+
118
+ - **Hibernation stores more.** QuickJS writes its own values into a blob:
119
+ `Date`, `Map`, `Set`, typed arrays and object graphs with cycles come
120
+ back, and a class's instance comes back as a plain object. A function
121
+ in a variable still keeps the actor in memory
122
+ ([Hibernation](hibernation.md)).
123
+ - **Values cross by encoding.** Event data and spawn params are converted
124
+ to the engine's values and back, through the same value table
125
+ ([README](../../README.md#values)). What a chart sends follows
126
+ JavaScript's rules for a value sent elsewhere: a key holding
127
+ `undefined` is dropped and an array's `undefined` is `null`, where the
128
+ native datamodel keeps both.
129
+ - **Its costs differ.** In the repository's measurements most operations
130
+ cost less on quickjs, and an idle actor takes less memory
131
+ ([Capacity and memory](capacity.md)).
132
+
133
+ `host.quickjsHeapBytes` is the engine's heap in bytes, every actor's
134
+ together, for an operator watching it against `memoryLimit`; it is
135
+ `undefined` on a native host and once the host is closed.