@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.
- package/README.md +648 -154
- package/docs/guide/browser.md +494 -0
- package/docs/guide/capacity.md +202 -0
- package/docs/guide/charts.md +578 -0
- package/docs/guide/hibernation.md +201 -0
- package/docs/guide/inspection.md +381 -0
- package/docs/guide/io-processors.md +269 -0
- package/docs/guide/migration.md +323 -0
- package/docs/guide/other-systems.md +275 -0
- package/docs/guide/quickjs.md +135 -0
- package/docs/guide/services.md +317 -0
- package/docs/guide/snapshots.md +186 -0
- package/docs/guide/telemetry.md +265 -0
- package/docs/guide/testing.md +272 -0
- package/docs/values.md +107 -0
- package/index.d.ts +1166 -1820
- package/index.mjs +6 -0
- package/lib/convenience.mjs +162 -0
- package/lib/direct.mjs +65 -0
- package/package.json +29 -16
- package/index.js +0 -34
- package/lib/actor.js +0 -85
- package/lib/debug/breakpoints.js +0 -349
- package/lib/debug/console.js +0 -149
- package/lib/debug/expressions.js +0 -133
- package/lib/debug/frames.js +0 -119
- package/lib/debug/labels.js +0 -142
- package/lib/debug/macrosteps.js +0 -207
- package/lib/debug/protocol.js +0 -186
- package/lib/debug/sources.js +0 -218
- package/lib/debug/variables.js +0 -265
- package/lib/debug.js +0 -1434
- package/lib/definition.js +0 -139
- package/lib/errors.js +0 -24
- package/lib/events.js +0 -56
- package/lib/image.js +0 -90
- package/lib/loader.js +0 -68
- package/lib/metrics.js +0 -333
- package/lib/native.js +0 -8
- package/lib/otlp.js +0 -332
- package/lib/statechart.js +0 -768
- package/lib/system.js +0 -2183
- package/lib/tracing.js +0 -164
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
# Invoked services
|
|
2
|
+
|
|
3
|
+
An I/O processor answers one send at a time. Some things a chart works
|
|
4
|
+
with live longer than one send: a connection, a subprocess, a long
|
|
5
|
+
computation, a subscription. SCXML has `<invoke>` for them: entering a
|
|
6
|
+
state starts the service, the chart and the service exchange events while
|
|
7
|
+
the state is active, and leaving the state stops it. When the invoked
|
|
8
|
+
thing is another chart, the host runs it as a child actor
|
|
9
|
+
([Writing charts](charts.md#a-chart-that-starts-another)). When it is
|
|
10
|
+
something your program runs, it is a **service**, and this guide is about
|
|
11
|
+
those.
|
|
12
|
+
|
|
13
|
+
## A service
|
|
14
|
+
|
|
15
|
+
Register a handler per `<invoke type>` in the host's options:
|
|
16
|
+
`services: { [type]: handler }`. When an invocation starts, the handler
|
|
17
|
+
gets the host and an **invocation**, and returns the **service**, any
|
|
18
|
+
object. The host keeps the service until the invocation ends and calls
|
|
19
|
+
its methods:
|
|
20
|
+
|
|
21
|
+
- `receive(host, send)` gets each `<send target="#_<invokeid>">` of the
|
|
22
|
+
invoker (and each event it forwards, with `autoforward="true"`);
|
|
23
|
+
- `stop(host)` is called when the invoker leaves the state, which cancels
|
|
24
|
+
the invocation.
|
|
25
|
+
|
|
26
|
+
Both are optional. The invocation is how the service talks back:
|
|
27
|
+
`invocation.sendBack(event, data)` sends the invoker an event (its
|
|
28
|
+
`_event.invokeid` is the invoke's id), and `invocation.done(data)` ends
|
|
29
|
+
the service, giving the invoker `done.invoke.<invokeid>` with `data`.
|
|
30
|
+
|
|
31
|
+
```js
|
|
32
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
33
|
+
|
|
34
|
+
const chart = `
|
|
35
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
36
|
+
datamodel="ecmascript" name="player" initial="playing">
|
|
37
|
+
<state id="playing">
|
|
38
|
+
<invoke id="counter" type="urn:example:counter" src="counter://local">
|
|
39
|
+
<param name="start" expr="10"/>
|
|
40
|
+
</invoke>
|
|
41
|
+
<transition event="go"><send target="#_counter" event="ping"/></transition>
|
|
42
|
+
<transition event="finish"><send target="#_counter" event="finish"/></transition>
|
|
43
|
+
<transition event="pong"><log expr="'pong ' + _event.data.n + ' from ' + _event.invokeid"/></transition>
|
|
44
|
+
<transition event="done.invoke.counter" target="finished">
|
|
45
|
+
<log expr="'done, total ' + _event.data.total"/>
|
|
46
|
+
</transition>
|
|
47
|
+
</state>
|
|
48
|
+
<final id="finished"/>
|
|
49
|
+
</scxml>`;
|
|
50
|
+
|
|
51
|
+
class Counter {
|
|
52
|
+
constructor(invocation) {
|
|
53
|
+
this.invocation = invocation;
|
|
54
|
+
this.count = invocation.data.start;
|
|
55
|
+
console.log(`started ${invocation.type} ${invocation.src} for session ${invocation.session}`);
|
|
56
|
+
}
|
|
57
|
+
receive(host, send) {
|
|
58
|
+
this.count++;
|
|
59
|
+
if (send.event === 'finish') this.invocation.done({ total: this.count });
|
|
60
|
+
else this.invocation.sendBack('pong', { n: this.count });
|
|
61
|
+
}
|
|
62
|
+
stop(host) {
|
|
63
|
+
console.log('stopped');
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
const compiled = compileCharts([{ name: 'player.scxml', text: chart }]);
|
|
68
|
+
const host = new Host({ systemID: 'demo' }, {
|
|
69
|
+
services: { 'urn:example:counter': (host, invocation) => new Counter(invocation) },
|
|
70
|
+
log: (host, entry) => console.log(entry.text),
|
|
71
|
+
});
|
|
72
|
+
host.addImage(compiled.image);
|
|
73
|
+
compiled.close();
|
|
74
|
+
|
|
75
|
+
const player = host.spawn(host.chart('player'));
|
|
76
|
+
host.send(player, 'go');
|
|
77
|
+
host.send(player, 'go');
|
|
78
|
+
host.send(player, 'finish');
|
|
79
|
+
await host.idle();
|
|
80
|
+
host.close();
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
```output
|
|
84
|
+
started urn:example:counter counter://local for session 1
|
|
85
|
+
pong 11 from counter
|
|
86
|
+
pong 12 from counter
|
|
87
|
+
done, total 13
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
A service that ended with `done` is not stopped: `stop` runs only for a
|
|
91
|
+
cancel.
|
|
92
|
+
|
|
93
|
+
An invocation starts at the end of the macrostep that entered its state,
|
|
94
|
+
as a child chart does ([Writing charts](charts.md#a-chart-that-starts-another)).
|
|
95
|
+
So a `<send target="#_counter">` in that state's own `<onentry>`, or in
|
|
96
|
+
anything else that macrostep runs (a raised event's transition, an
|
|
97
|
+
eventless one), comes before the service exists, and the chart gets
|
|
98
|
+
`error.communication` for it; send from a later event, as `go` does here.
|
|
99
|
+
|
|
100
|
+
**The invocation** holds `session` (the invoker, a `bigint`), `invokeid`,
|
|
101
|
+
`type`, `src`, `data` (the `<param>`s as an object, or the `<content>`),
|
|
102
|
+
`traceparent`, and two flags: `running`, false once it ended, and
|
|
103
|
+
`restored` ([Snapshots](snapshots.md)). It is a record, so you may keep it
|
|
104
|
+
and call `sendBack` from a timer or a promise while the service runs.
|
|
105
|
+
`sendBack` and `done` take `{ traceparent }` as a third argument (a
|
|
106
|
+
second for `done`); without it they continue the invoke's trace, and
|
|
107
|
+
`null` starts a new one. After `done`, a cancel or `host.close()`, both
|
|
108
|
+
throw a `TinyactorsError` with `TA_ERROR_STALE`.
|
|
109
|
+
|
|
110
|
+
**The send `receive` gets** is a view, as an I/O processor's is: read it
|
|
111
|
+
during the call. A `receive` that returns a promise has its send filled
|
|
112
|
+
before the host moves on, so it may read it after an `await`.
|
|
113
|
+
|
|
114
|
+
## A service that starts asynchronously
|
|
115
|
+
|
|
116
|
+
Starting a service often means waiting: a connection to open, a process to
|
|
117
|
+
spawn. **The handler may return a promise of the service** (an `async`
|
|
118
|
+
handler). Until it settles, the invocation is starting: the sends to it
|
|
119
|
+
wait, and reach `receive` in order once the promise resolves. The
|
|
120
|
+
invocation may `sendBack` meanwhile.
|
|
121
|
+
|
|
122
|
+
```js
|
|
123
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
124
|
+
|
|
125
|
+
// A stand-in for a client library: a connection that opens after 20 ms.
|
|
126
|
+
const connect = (url) => new Promise((resolve) => setTimeout(() => resolve({
|
|
127
|
+
ask: async (question) => `${url} says yes to ${question}`,
|
|
128
|
+
}), 20));
|
|
129
|
+
|
|
130
|
+
const chart = `
|
|
131
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
132
|
+
datamodel="ecmascript" name="client" initial="connected">
|
|
133
|
+
<state id="connected">
|
|
134
|
+
<invoke id="db" type="urn:example:db" src="db://primary"/>
|
|
135
|
+
<transition event="query"><send target="#_db" event="query"><content expr="_event.data"/></send></transition>
|
|
136
|
+
<transition event="status"><log expr="'status ' + _event.data"/></transition>
|
|
137
|
+
<transition event="answer"><log expr="_event.data"/></transition>
|
|
138
|
+
</state>
|
|
139
|
+
</scxml>`;
|
|
140
|
+
|
|
141
|
+
const compiled = compileCharts([{ name: 'client.scxml', text: chart }]);
|
|
142
|
+
const host = new Host({ systemID: 'demo' }, {
|
|
143
|
+
services: {
|
|
144
|
+
'urn:example:db': async (host, invocation) => {
|
|
145
|
+
invocation.sendBack('status', 'connecting');
|
|
146
|
+
const connection = await connect(invocation.src);
|
|
147
|
+
return {
|
|
148
|
+
async receive(host, send) {
|
|
149
|
+
invocation.sendBack('answer', await connection.ask(send.data));
|
|
150
|
+
},
|
|
151
|
+
};
|
|
152
|
+
},
|
|
153
|
+
},
|
|
154
|
+
log: (host, entry) => console.log(entry.text),
|
|
155
|
+
});
|
|
156
|
+
host.addImage(compiled.image);
|
|
157
|
+
compiled.close();
|
|
158
|
+
|
|
159
|
+
const client = host.spawn(host.chart('client'));
|
|
160
|
+
host.send(client, 'query', 'first'); // both reach the service once it is connected
|
|
161
|
+
host.send(client, 'query', 'second');
|
|
162
|
+
await new Promise((resolve) => setTimeout(resolve, 100));
|
|
163
|
+
await host.idle();
|
|
164
|
+
host.close();
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
```output
|
|
168
|
+
status connecting
|
|
169
|
+
db://primary says yes to first
|
|
170
|
+
db://primary says yes to second
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
A cancel that comes before the promise settles stops the service as soon
|
|
174
|
+
as it resolves, and the sends that waited are dropped, since the invoker
|
|
175
|
+
has left and nothing could answer them. A rejection is a failed start:
|
|
176
|
+
the invoker gets `error.communication`, once and once more for each send
|
|
177
|
+
that waited, and the rejection stays unhandled, as any handler's promise's
|
|
178
|
+
does (see "A handler's error ends the process by default" in the
|
|
179
|
+
[README](../../README.md#before-you-use-it)). After `host.close()` a
|
|
180
|
+
promise that settles is ignored.
|
|
181
|
+
|
|
182
|
+
**Or return the service at once** and let its own methods await its
|
|
183
|
+
start, when the service should take sends before it is ready, or decide
|
|
184
|
+
itself what a send does while it connects:
|
|
185
|
+
|
|
186
|
+
```js
|
|
187
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
188
|
+
|
|
189
|
+
const connect = (url) => new Promise((resolve) => setTimeout(() => resolve({
|
|
190
|
+
ask: async (question) => `${url} answers ${question}`,
|
|
191
|
+
}), 20));
|
|
192
|
+
|
|
193
|
+
class Connection {
|
|
194
|
+
constructor(invocation) {
|
|
195
|
+
this.invocation = invocation;
|
|
196
|
+
this.ready = connect(invocation.src); // a promise, started now
|
|
197
|
+
this.ready.catch(() => {}); // its failure is answered in receive
|
|
198
|
+
}
|
|
199
|
+
async receive(host, send) { // send was filled before the host moved on
|
|
200
|
+
const connection = await this.ready;
|
|
201
|
+
this.invocation.sendBack('answer', await connection.ask(send.data));
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
const compiled = compileCharts([{ name: 'client.scxml', text: `
|
|
206
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
207
|
+
datamodel="ecmascript" name="client" initial="s">
|
|
208
|
+
<state id="s">
|
|
209
|
+
<invoke id="db" type="urn:example:db" src="db://replica"/>
|
|
210
|
+
<transition event="query"><send target="#_db" event="query"><content expr="_event.data"/></send></transition>
|
|
211
|
+
<transition event="answer"><log expr="_event.data"/></transition>
|
|
212
|
+
</state>
|
|
213
|
+
</scxml>` }]);
|
|
214
|
+
const host = new Host({ systemID: 'demo' }, {
|
|
215
|
+
services: { 'urn:example:db': (host, invocation) => new Connection(invocation) },
|
|
216
|
+
log: (host, entry) => console.log(entry.text),
|
|
217
|
+
});
|
|
218
|
+
host.addImage(compiled.image);
|
|
219
|
+
compiled.close();
|
|
220
|
+
|
|
221
|
+
host.send(host.spawn(host.chart('client')), 'query', 'ping');
|
|
222
|
+
await new Promise((resolve) => setTimeout(resolve, 100));
|
|
223
|
+
await host.idle();
|
|
224
|
+
host.close();
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
```output
|
|
228
|
+
db://replica answers ping
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
`await host.idle()` waits for the host and for the promises your
|
|
232
|
+
handlers return (a service handler's, a `receive`'s), not for one a
|
|
233
|
+
service starts on its own: these examples open the connection in the
|
|
234
|
+
background, so they wait on a timer first. A handler that returns a
|
|
235
|
+
promise of the service is waited for.
|
|
236
|
+
|
|
237
|
+
## Failures
|
|
238
|
+
|
|
239
|
+
A failure of any kind gives the invoker `error.communication`: no handler
|
|
240
|
+
for the type, a handler that throws or whose promise rejects, a `receive`
|
|
241
|
+
that throws or whose promise rejects (the service crashed, and is dropped
|
|
242
|
+
without `stop`), or no handler for a restored invocation. Each later send
|
|
243
|
+
to that invocation gets one too, until the invoker leaves the state. The
|
|
244
|
+
invoker gets none when it cancelled the invocation in the same step that
|
|
245
|
+
started it. A handler's error is reported after the turn, as any
|
|
246
|
+
handler's. A type with no handler throws nothing: the chart chose the
|
|
247
|
+
type, and a chart (an untrusted one on quickjs, say) must not be able to
|
|
248
|
+
end your process by naming one you do not serve.
|
|
249
|
+
|
|
250
|
+
```js
|
|
251
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
252
|
+
|
|
253
|
+
const compiled = compileCharts([{ name: 'c.scxml', text: `
|
|
254
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
255
|
+
datamodel="ecmascript" name="c" initial="s">
|
|
256
|
+
<state id="s">
|
|
257
|
+
<invoke id="mail" type="urn:example:mail" src="smtp://localhost"/>
|
|
258
|
+
<transition event="error.communication"><log expr="'the mail service failed'"/></transition>
|
|
259
|
+
</state>
|
|
260
|
+
</scxml>` }]);
|
|
261
|
+
const host = new Host({ systemID: 'demo' }, {
|
|
262
|
+
services: { 'urn:example:mail': () => { throw new Error('no SMTP server'); } },
|
|
263
|
+
log: (host, entry) => console.log(entry.text),
|
|
264
|
+
});
|
|
265
|
+
host.addImage(compiled.image);
|
|
266
|
+
compiled.close();
|
|
267
|
+
|
|
268
|
+
host.spawn(host.chart('c'));
|
|
269
|
+
try {
|
|
270
|
+
await host.idle();
|
|
271
|
+
} catch (error) {
|
|
272
|
+
console.log('idle() rejected:', error.message);
|
|
273
|
+
}
|
|
274
|
+
await host.idle();
|
|
275
|
+
host.close();
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
```output
|
|
279
|
+
idle() rejected: no SMTP server
|
|
280
|
+
the mail service failed
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
`host.close()` drops the running services without calling `stop`. The
|
|
284
|
+
host keeps them on its own object, so a host you drop without closing,
|
|
285
|
+
whose services refer back to it, is still collected.
|
|
286
|
+
|
|
287
|
+
An invocation uses one of the host's requests; `system.maxRequests` is
|
|
288
|
+
where the pool starts, and a segment grows it when it runs out
|
|
289
|
+
([Capacity and memory](capacity.md)).
|
|
290
|
+
|
|
291
|
+
## At scale
|
|
292
|
+
|
|
293
|
+
`tools/services.mjs` (`mise run services` in the repository) runs a
|
|
294
|
+
population of actors that each invoke a counter service. It sends pings
|
|
295
|
+
and pongs to actors drawn at random. Then a third finish with done data,
|
|
296
|
+
a third leave the invoking state (the service is stopped), and the rest
|
|
297
|
+
keep theirs. It checks that every pong is counted once, every done datum
|
|
298
|
+
is right, every cancelled service was stopped once and no other, and the
|
|
299
|
+
ended services are collected.
|
|
300
|
+
|
|
301
|
+
One run of it (2026-10-16, x86_64 Linux 6.18, Intel Xeon @ 2.10GHz, 4
|
|
302
|
+
CPUs, 16 GiB; node 22.23.3, bun 1.4.1). 200,000 actors, each with a
|
|
303
|
+
counter service, made 1,000,000 round trips (actor, service, actor); then
|
|
304
|
+
a third finished with done data and a third were cancelled. In every run
|
|
305
|
+
every pong and done datum was right, every cancelled service was stopped
|
|
306
|
+
exactly once and no other, and the host held only the 66,666 services
|
|
307
|
+
still running.
|
|
308
|
+
|
|
309
|
+
| runtime, datamodel | start 200,000 invocations | 1,000,000 round trips | end (done, cancel) | peak resident | core's region |
|
|
310
|
+
|---|---|---|---|---|---|
|
|
311
|
+
| node, native | 5.0 s (40,000 a second) | 27.2 s (37,000 a second) | 2.1 s | 575 MB (2875 B per actor and service) | 50.3 MB (251 B per actor) |
|
|
312
|
+
| node, quickjs | 4.0 s (50,000 a second) | 22.4 s (45,000 a second) | 2.3 s | 698 MB (3491 B per actor and service) | 61.8 MB (309 B per actor) |
|
|
313
|
+
| bun, native | 3.9 s (52,000 a second) | 20.7 s (48,000 a second) | 1.9 s | 843 MB (4214 B per actor and service) | 50.3 MB (251 B per actor) |
|
|
314
|
+
| bun, quickjs | 3.1 s (64,000 a second) | 19.0 s (53,000 a second) | 1.6 s | 766 MB (3830 B per actor and service) | 61.8 MB (309 B per actor) |
|
|
315
|
+
|
|
316
|
+
A round trip costs about what it costs with 10,000 actors: a run's work
|
|
317
|
+
does not grow with the number of running invocations.
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Snapshots
|
|
2
|
+
|
|
3
|
+
`host.snapshot()` copies the whole host into one `Buffer`: every
|
|
4
|
+
segment's memory (actors, queues, timers, the hibernated actors'
|
|
5
|
+
records), the datamodel's sessions and values, the images, the system id
|
|
6
|
+
and the host's time, read when you call it. `Host.restore(snapshot, config, options)` makes a
|
|
7
|
+
new host running it, in this process or another.
|
|
8
|
+
|
|
9
|
+
Uses: rehearse a deploy on a copy (add the new image, migrate, run the
|
|
10
|
+
clock ahead, look); capture a host when something goes wrong and step
|
|
11
|
+
through it; start every test from one prepared world; or take a host out
|
|
12
|
+
of the process for a while.
|
|
13
|
+
|
|
14
|
+
```js
|
|
15
|
+
import { compileCharts, Host, SimulatedClock } from '@tinyactors/node';
|
|
16
|
+
|
|
17
|
+
const compiled = compileCharts([{ name: 'reminder.scxml', text: `
|
|
18
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
19
|
+
datamodel="ecmascript" name="reminder" initial="waiting">
|
|
20
|
+
<datamodel><data id="note" expr="''"/></datamodel>
|
|
21
|
+
<state id="waiting">
|
|
22
|
+
<transition event="set">
|
|
23
|
+
<assign location="note" expr="_event.data"/>
|
|
24
|
+
<send event="ring" delay="3600s"/>
|
|
25
|
+
</transition>
|
|
26
|
+
<transition event="ring" target="done"/>
|
|
27
|
+
</state>
|
|
28
|
+
<final id="done"><onentry><log expr="'reminder: ' + note"/></onentry></final>
|
|
29
|
+
</scxml>` }]);
|
|
30
|
+
|
|
31
|
+
const config = { systemID: 'demo' };
|
|
32
|
+
const log = (host, entry) => console.log(entry.text);
|
|
33
|
+
|
|
34
|
+
const clock = new SimulatedClock();
|
|
35
|
+
const host = new Host(config, { clock, log });
|
|
36
|
+
host.addImage(compiled.image);
|
|
37
|
+
compiled.close();
|
|
38
|
+
|
|
39
|
+
const reminder = host.spawn(host.chart('reminder'), { name: 'plants' });
|
|
40
|
+
host.send(reminder, 'set', 'water the plants');
|
|
41
|
+
await host.idle();
|
|
42
|
+
clock.increment(30 * 60_000); // half an hour passes
|
|
43
|
+
await host.idle();
|
|
44
|
+
|
|
45
|
+
const snapshot = host.snapshot(); // bytes: write them to a file, send them elsewhere
|
|
46
|
+
host.close();
|
|
47
|
+
|
|
48
|
+
const later = new SimulatedClock(); // a clock that reads 0
|
|
49
|
+
const copy = Host.restore(snapshot, config, { clock: later, log });
|
|
50
|
+
console.log('same session:', copy.actorByName('plants') === reminder);
|
|
51
|
+
await copy.idle();
|
|
52
|
+
console.log('due in', copy.nextDeadline / 60_000, 'minutes');
|
|
53
|
+
later.increment(30 * 60_000);
|
|
54
|
+
await copy.idle();
|
|
55
|
+
copy.close();
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```output
|
|
59
|
+
same session: true
|
|
60
|
+
due in 30 minutes
|
|
61
|
+
reminder: water the plants
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Every session id stays the same, and the host's clock goes on from the
|
|
65
|
+
snapshot's time, whatever clock reads it: a new `SimulatedClock`, as
|
|
66
|
+
here, or the runtime's clock in another process or on another machine.
|
|
67
|
+
The snapshot's time is the time of the `snapshot()` call, so a timer
|
|
68
|
+
with 6 seconds left then has 6 seconds left after the restore, however
|
|
69
|
+
long the host was idle before. `host.now()` reads that clock: a journal of
|
|
70
|
+
the inputs that came after a snapshot records it with each, and a replay
|
|
71
|
+
on a restored host on a `SimulatedClock` moves the clock to each reading
|
|
72
|
+
(`clock.increment(entry.at - host.now())`) before it gives the input.
|
|
73
|
+
|
|
74
|
+
## Restoring
|
|
75
|
+
|
|
76
|
+
Pass `Host.restore` the config the snapshot was taken with (its
|
|
77
|
+
`systemID` is checked, and the I/O processors and the tick rate are not
|
|
78
|
+
in the snapshot), the snapshot's `datamodel` (`'quickjs'` for a quickjs
|
|
79
|
+
host), and the handlers `new Host` takes. The host's handlers are not in
|
|
80
|
+
the snapshot either: give the restored host its own.
|
|
81
|
+
|
|
82
|
+
- **A snapshot is valid only for the same build of the package.** It
|
|
83
|
+
holds raw memory, with a version of its layout: a snapshot of a build
|
|
84
|
+
whose layout differs is refused by `Host.restore` with
|
|
85
|
+
`TA_ERROR_INVALID`, and you take a new one with the new build. It is
|
|
86
|
+
not a backup: durability is your database's
|
|
87
|
+
job, and [hibernation](hibernation.md) is how a running process keeps
|
|
88
|
+
actors out of memory. A snapshot is a copy of the whole application,
|
|
89
|
+
every chart version at once.
|
|
90
|
+
- **Invoked services are started again.** The services you run are not
|
|
91
|
+
in the snapshot. The restored host's first turn announces each
|
|
92
|
+
invocation that was running to the `services` handler you pass to
|
|
93
|
+
`Host.restore`, with `invocation.restored` true and the same
|
|
94
|
+
`invokeid`, `src` and params. Pass your real handlers to go on, or
|
|
95
|
+
stand-ins for a copy that must not reach the real services. A type with
|
|
96
|
+
no handler gives its invokers `error.communication`, and nothing is
|
|
97
|
+
thrown.
|
|
98
|
+
- **Hibernated actors stay in your store.** The snapshot holds their
|
|
99
|
+
records, not their blobs, and the restored host asks for them through
|
|
100
|
+
`wake` as before. A copy that hibernates actors needs its own copy of
|
|
101
|
+
the store, since it writes blobs too.
|
|
102
|
+
- **Values are written through the value table**, so two variables of
|
|
103
|
+
one actor that shared one object no longer share it after a restore.
|
|
104
|
+
|
|
105
|
+
## When a snapshot is refused
|
|
106
|
+
|
|
107
|
+
The host must be quiescent. `snapshot()` throws a `TinyactorsError` with
|
|
108
|
+
`TA_ERROR_STATE` when it is called from a handler, while an effect or a
|
|
109
|
+
typed method's reply has not been handled yet (`await host.idle()`
|
|
110
|
+
first), and while a migration runs. It throws `TA_ERROR_UNSUPPORTED` when
|
|
111
|
+
an actor holds what hibernation cannot store (on the native datamodel a
|
|
112
|
+
function, a `Map`, a `Date`, ..., or an actor of a chart whose scripts
|
|
113
|
+
declare with `let`, `const` or `class`); the message names the variable.
|
|
114
|
+
The host goes on either way.
|
|
115
|
+
|
|
116
|
+
```js
|
|
117
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
118
|
+
|
|
119
|
+
const compiled = compileCharts([{ name: 'c.scxml', text: `
|
|
120
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
121
|
+
datamodel="ecmascript" name="c" initial="s">
|
|
122
|
+
<state id="s"><onentry><log expr="'hello'"/></onentry></state>
|
|
123
|
+
</scxml>` }]);
|
|
124
|
+
const host = new Host({ systemID: 'demo' }, {
|
|
125
|
+
log: (host, entry) => {
|
|
126
|
+
try {
|
|
127
|
+
host.snapshot();
|
|
128
|
+
} catch (error) {
|
|
129
|
+
console.log('from a handler:', error.status);
|
|
130
|
+
}
|
|
131
|
+
},
|
|
132
|
+
});
|
|
133
|
+
host.addImage(compiled.image);
|
|
134
|
+
compiled.close();
|
|
135
|
+
|
|
136
|
+
host.spawn(host.chart('c'));
|
|
137
|
+
await host.idle();
|
|
138
|
+
console.log('after idle():', host.snapshot().length > 0);
|
|
139
|
+
host.close();
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
```output
|
|
143
|
+
from a handler: TA_ERROR_STATE
|
|
144
|
+
after idle(): true
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## At scale
|
|
148
|
+
|
|
149
|
+
`tools/snapshot.mjs` (`mise run snapshot` in the repository) rehearses a
|
|
150
|
+
deploy on a copy. The live host has two million actors, at most 1000
|
|
151
|
+
resident and the rest in SQLite. Each resident actor has a delayed send
|
|
152
|
+
pending, and half of them are paying through an invoked payment service
|
|
153
|
+
that has not answered. The tool writes the host's snapshot to a file and
|
|
154
|
+
copies the store. It restores the copy with its own store and clock and
|
|
155
|
+
a stand-in payment service, which gets every payment in flight again
|
|
156
|
+
(`restored`, with its amount) and declines it; the copy's own snapshot
|
|
157
|
+
must be the same bytes. Then it migrates the copy to a new version while
|
|
158
|
+
events come and runs its clock past the delayed sends, while the live
|
|
159
|
+
host goes on with events of its own and its payments still in flight. The
|
|
160
|
+
copy never reaches the real service.
|
|
161
|
+
|
|
162
|
+
One run of it (2026-10-16, x86_64 Linux 6.18, Intel Xeon @ 2.10GHz, 4
|
|
163
|
+
CPUs, 16 GiB; node 22.23.3, bun 1.4.1), with two million actors, at most
|
|
164
|
+
1000 resident, 200,000 events before the snapshot and 200,000 more on
|
|
165
|
+
each host after it; then 100,000 actors all resident, so the datamodel's
|
|
166
|
+
own state is most of the snapshot. Every run passed its checks: the
|
|
167
|
+
copy's snapshot was the same bytes, and the copy migrated every actor to
|
|
168
|
+
version 2 (2,018,400 wakes from its store at two million). All 25,000
|
|
169
|
+
sampled actors had their counts, delayed sends and versions on both
|
|
170
|
+
hosts, the live store held only the live host's blobs, and after every
|
|
171
|
+
eviction at most R actors were resident.
|
|
172
|
+
|
|
173
|
+
| runtime, datamodel | actors, resident | snapshot | taken | restored | migrate on the copy | peak resident (both hosts) |
|
|
174
|
+
|---|---|---|---|---|---|---|
|
|
175
|
+
| node, native | 2,000,000, 1000 | 116.2 MB (58 B per actor) | 0.11 s | 0.55 s | 172.4 s | 934 MB |
|
|
176
|
+
| node, quickjs | 2,000,000, 1000 | 116.1 MB (58 B per actor) | 0.09 s | 0.09 s | 125.7 s | 851 MB |
|
|
177
|
+
| bun, native | 2,000,000, 1000 | 116.2 MB (58 B per actor) | 0.10 s | 0.08 s | 144.9 s | 1018 MB |
|
|
178
|
+
| bun, quickjs | 2,000,000, 1000 | 116.1 MB (58 B per actor) | 0.09 s | 0.07 s | 111.8 s | 937 MB |
|
|
179
|
+
| node, native | 100,000, 100,000 | 65.9 MB (659 B per actor) | 0.76 s | 3.42 s | 5.0 s | 817 MB |
|
|
180
|
+
| node, quickjs | 100,000, 100,000 | 60.9 MB (609 B per actor) | 0.90 s | 0.74 s | 3.6 s | 638 MB |
|
|
181
|
+
| bun, native | 100,000, 100,000 | 65.9 MB (659 B per actor) | 0.62 s | 1.13 s | 4.6 s | 1106 MB |
|
|
182
|
+
| bun, quickjs | 100,000, 100,000 | 60.9 MB (609 B per actor) | 0.86 s | 0.61 s | 3.3 s | 742 MB |
|
|
183
|
+
|
|
184
|
+
Core's region is 58 B an actor with most of them hibernated and 469 B
|
|
185
|
+
all resident; the native datamodel's rows take about 50 B an actor more
|
|
186
|
+
than quickjs's state in a snapshot of resident actors.
|