@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,269 @@
|
|
|
1
|
+
# I/O processors
|
|
2
|
+
|
|
3
|
+
An actor cannot reach the network, a file or a database itself: the host
|
|
4
|
+
does no I/O. When a chart needs something from outside, it sends an event
|
|
5
|
+
to an **I/O processor**. Your handler for that processor does the work
|
|
6
|
+
and, if there is an answer, sends it back as an event. The chart
|
|
7
|
+
stays a description of what happens; your code decides how.
|
|
8
|
+
|
|
9
|
+
## Declaring a processor
|
|
10
|
+
|
|
11
|
+
The config lists the processors the host's charts may send to, each a
|
|
12
|
+
`type` (any URI you choose) and an optional `location`. The options give
|
|
13
|
+
the handler of each type:
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
17
|
+
|
|
18
|
+
const compiled = compileCharts([{ name: 'quote.scxml', text: `
|
|
19
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
20
|
+
datamodel="ecmascript" name="quote" initial="asking">
|
|
21
|
+
<state id="asking">
|
|
22
|
+
<onentry>
|
|
23
|
+
<send type="urn:example:prices" event="lookup" target="tea" id="ask-1">
|
|
24
|
+
<param name="currency" expr="'EUR'"/>
|
|
25
|
+
</send>
|
|
26
|
+
</onentry>
|
|
27
|
+
<transition event="price" target="known">
|
|
28
|
+
<log expr="'tea costs ' + _event.data.amount + ' ' + _event.data.currency + ' (answer to ' + _event.sendid + ')'"/>
|
|
29
|
+
</transition>
|
|
30
|
+
</state>
|
|
31
|
+
<final id="known"/>
|
|
32
|
+
</scxml>` }]);
|
|
33
|
+
|
|
34
|
+
const prices = { tea: 4 };
|
|
35
|
+
const host = new Host({ systemID: 'shop', ioProcessors: [{ type: 'urn:example:prices' }] }, {
|
|
36
|
+
ioProcessors: {
|
|
37
|
+
'urn:example:prices': (host, send) => {
|
|
38
|
+
console.log(`${send.type}: ${send.event} ${send.target} for session ${send.session}`);
|
|
39
|
+
send.answer('price', { amount: prices[send.target], currency: send.data.currency });
|
|
40
|
+
},
|
|
41
|
+
},
|
|
42
|
+
log: (host, entry) => console.log(entry.text),
|
|
43
|
+
});
|
|
44
|
+
host.addImage(compiled.image);
|
|
45
|
+
compiled.close();
|
|
46
|
+
host.spawn(host.chart('quote'));
|
|
47
|
+
await host.idle();
|
|
48
|
+
host.close();
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```output
|
|
52
|
+
urn:example:prices: lookup tea for session 1
|
|
53
|
+
tea costs 4 EUR (answer to ask-1)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
A chart that sends to a type the config does not list gets
|
|
57
|
+
`error.execution`. A handler for a type the config does not list is a
|
|
58
|
+
`TypeError` at `new Host`. A listed type with no handler fails each send
|
|
59
|
+
to it, so the sender gets `error.communication`.
|
|
60
|
+
|
|
61
|
+
## The send
|
|
62
|
+
|
|
63
|
+
The handler's second argument describes one `<send>`:
|
|
64
|
+
|
|
65
|
+
| Field | What it holds |
|
|
66
|
+
|---|---|
|
|
67
|
+
| `session` | the sender's session, a `bigint` |
|
|
68
|
+
| `event` | the event's name (`<send event>`) |
|
|
69
|
+
| `target` | `<send target>` as a string, `undefined` when it has none |
|
|
70
|
+
| `sendid` | `<send id>`, or the id the host generated; `undefined` when it has none. A generated id is unique in the sender's session only (each session's first is `send.1`), so key what you keep by both: `` `${send.session}:${send.sendid}` `` |
|
|
71
|
+
| `data` | the `<param>`s as an object, or the `<content>`'s value |
|
|
72
|
+
| `type` | the processor's type |
|
|
73
|
+
| `origin` | the sender's address, an `Address` |
|
|
74
|
+
| `traceparent` | the sending step's trace as W3C text, `undefined` when untraced ([Telemetry](telemetry.md)) |
|
|
75
|
+
| `message` | the outgoing half, for a transport ([Other systems](other-systems.md)) |
|
|
76
|
+
|
|
77
|
+
Then two methods, of which a handler calls at most one:
|
|
78
|
+
|
|
79
|
+
- **`send.answer(event, data, options)`** sends `event` back to the
|
|
80
|
+
sender, with this send's `sendid` as its `_event.sendid`. The options
|
|
81
|
+
are `traceparent` (the answer continues the send's trace unless you give
|
|
82
|
+
another, or `null` for a new one), `origin` (the answer's
|
|
83
|
+
`_event.origin`) and `raw` (the message as you read it, for a chart
|
|
84
|
+
that wants it).
|
|
85
|
+
- **`send.fail()`** gives the sender `error.communication` with this
|
|
86
|
+
send's `sendid`, for a request that could not be done.
|
|
87
|
+
|
|
88
|
+
A second answer, or an answer after `fail()`, throws `TA_ERROR_STATE`. A
|
|
89
|
+
handler may also answer nothing: the send was a notification, or the chart
|
|
90
|
+
waits for a timeout of its own.
|
|
91
|
+
|
|
92
|
+
The send is a view of the host's memory, read on first access, and it is
|
|
93
|
+
valid while the handler runs. Reading it after the handler returned
|
|
94
|
+
throws `TA_ERROR_STALE`, so copy what you keep for later.
|
|
95
|
+
|
|
96
|
+
## Answering later
|
|
97
|
+
|
|
98
|
+
A handler that returns a promise (an `async` function, or any function
|
|
99
|
+
that returns a thenable) has its send filled with every field before the
|
|
100
|
+
host moves on. Its `answer()` and `fail()` then work whenever the promise
|
|
101
|
+
gets there, as long as the host is open. Until then the actor goes on with
|
|
102
|
+
its other events; the answer arrives as an event like any other.
|
|
103
|
+
|
|
104
|
+
The sender may end while your promise is pending (a session that logged
|
|
105
|
+
out, an actor terminated). Then `answer()` and `fail()` deliver nothing
|
|
106
|
+
and return `false`; they return `true` when the sender gets the event.
|
|
107
|
+
Any other refusal still throws: an answer after another, a closed host
|
|
108
|
+
(`TA_ERROR_STATE`), data the value table cannot hold.
|
|
109
|
+
|
|
110
|
+
```js
|
|
111
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
112
|
+
|
|
113
|
+
const compiled = compileCharts([{ name: 'mailer.scxml', text: `
|
|
114
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
115
|
+
datamodel="ecmascript" name="mailer" initial="sending">
|
|
116
|
+
<state id="sending">
|
|
117
|
+
<onentry>
|
|
118
|
+
<send type="urn:example:mail" event="deliver" target="ada@example.com"><content expr="'hello'"/></send>
|
|
119
|
+
<send event="timeout" delay="5s"/>
|
|
120
|
+
</onentry>
|
|
121
|
+
<transition event="delivered" target="sent"><log expr="'delivered after ' + _event.data.ms + ' ms'"/></transition>
|
|
122
|
+
<transition event="error.communication" target="failed"/>
|
|
123
|
+
<transition event="timeout" target="failed"/>
|
|
124
|
+
</state>
|
|
125
|
+
<final id="sent"/>
|
|
126
|
+
<final id="failed"><onentry><log expr="'not delivered'"/></onentry></final>
|
|
127
|
+
</scxml>` }]);
|
|
128
|
+
|
|
129
|
+
// A stand-in for an SMTP client.
|
|
130
|
+
const deliver = (to, body) => new Promise((resolve) => setTimeout(() => resolve(20), 20));
|
|
131
|
+
|
|
132
|
+
const host = new Host({ systemID: 'demo', ioProcessors: [{ type: 'urn:example:mail' }] }, {
|
|
133
|
+
ioProcessors: {
|
|
134
|
+
'urn:example:mail': async (host, send) => {
|
|
135
|
+
try {
|
|
136
|
+
const ms = await deliver(send.target, send.data); // send is still readable here
|
|
137
|
+
send.answer('delivered', { ms });
|
|
138
|
+
} catch {
|
|
139
|
+
send.fail();
|
|
140
|
+
}
|
|
141
|
+
},
|
|
142
|
+
},
|
|
143
|
+
log: (host, entry) => console.log(entry.text),
|
|
144
|
+
});
|
|
145
|
+
host.addImage(compiled.image);
|
|
146
|
+
compiled.close();
|
|
147
|
+
|
|
148
|
+
host.spawn(host.chart('mailer'));
|
|
149
|
+
await host.idle();
|
|
150
|
+
host.close();
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
```output
|
|
154
|
+
delivered after 20 ms
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`await host.idle()` waits for the host and for the promise your handler
|
|
158
|
+
returned: it resolves once the answer ran. A promise the handler starts
|
|
159
|
+
and does not return is not waited for. The pending `timeout` keeps the
|
|
160
|
+
process alive until `host.close()`.
|
|
161
|
+
|
|
162
|
+
## When the sender ends
|
|
163
|
+
|
|
164
|
+
An actor that reaches a top-level `<final>` ends at once, and the events
|
|
165
|
+
still in its queue are dropped (SCXML ends the session there). So a
|
|
166
|
+
request your program sent with `host.send`, and holds a promise for, is
|
|
167
|
+
lost when an event before it ends the actor: no handler is called, and
|
|
168
|
+
`host.send` had already returned. Let the chart tell you first: its
|
|
169
|
+
`<final>`'s `<onentry>` sends to your I/O processor, and the handler
|
|
170
|
+
settles everything it still holds for that session.
|
|
171
|
+
|
|
172
|
+
```js
|
|
173
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
174
|
+
|
|
175
|
+
const compiled = compileCharts([{ name: 'login.scxml', text: `
|
|
176
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
177
|
+
datamodel="ecmascript" name="login" initial="in">
|
|
178
|
+
<state id="in">
|
|
179
|
+
<transition event="request"><send type="urn:example:http" event="response"><content expr="'200 ' + _event.data"/></send></transition>
|
|
180
|
+
<transition event="logout" target="out"/>
|
|
181
|
+
</state>
|
|
182
|
+
<final id="out"><onentry><send type="urn:example:http" event="closed"/></onentry></final>
|
|
183
|
+
</scxml>` }]);
|
|
184
|
+
|
|
185
|
+
const pending = new Map(); // String(session) -> the resolvers of its requests, in order
|
|
186
|
+
const host = new Host({ systemID: 'web', ioProcessors: [{ type: 'urn:example:http' }] }, {
|
|
187
|
+
ioProcessors: {
|
|
188
|
+
'urn:example:http': (host, send) => {
|
|
189
|
+
const waiting = pending.get(String(send.session)) ?? [];
|
|
190
|
+
if (send.event === 'response') waiting.shift()?.(send.data);
|
|
191
|
+
if (send.event === 'closed') {
|
|
192
|
+
for (const resolve of waiting.splice(0)) resolve('401 logged out');
|
|
193
|
+
pending.delete(String(send.session));
|
|
194
|
+
}
|
|
195
|
+
},
|
|
196
|
+
},
|
|
197
|
+
});
|
|
198
|
+
host.addImage(compiled.image);
|
|
199
|
+
compiled.close();
|
|
200
|
+
|
|
201
|
+
/** Sends `path` to the session's actor; resolves with its answer. */
|
|
202
|
+
const request = (session, path) => new Promise((resolve) => {
|
|
203
|
+
const key = String(session);
|
|
204
|
+
pending.set(key, [...(pending.get(key) ?? []), resolve]);
|
|
205
|
+
host.send(session, 'request', path);
|
|
206
|
+
});
|
|
207
|
+
|
|
208
|
+
const session = host.spawn(host.chart('login'));
|
|
209
|
+
const first = request(session, '/home');
|
|
210
|
+
host.send(session, 'logout');
|
|
211
|
+
const second = request(session, '/account'); // queued behind the logout: dropped
|
|
212
|
+
console.log(await first);
|
|
213
|
+
console.log(await second);
|
|
214
|
+
host.close();
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
```output
|
|
218
|
+
200 /home
|
|
219
|
+
401 logged out
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## When a handler fails
|
|
223
|
+
|
|
224
|
+
A handler that throws before it answered, or whose promise rejects before
|
|
225
|
+
it answered, has its send failed: the sender gets `error.communication`.
|
|
226
|
+
The error itself is reported after the turn: it rejects a waiting
|
|
227
|
+
`host.idle()`, or else is thrown as an uncaught exception, and a promise
|
|
228
|
+
that rejects stays an unhandled rejection. An error after the answer
|
|
229
|
+
fails nothing, and the answer stands.
|
|
230
|
+
|
|
231
|
+
```js
|
|
232
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
233
|
+
|
|
234
|
+
const compiled = compileCharts([{ name: 'c.scxml', text: `
|
|
235
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
236
|
+
datamodel="ecmascript" name="c" initial="s">
|
|
237
|
+
<state id="s">
|
|
238
|
+
<onentry><send type="urn:example:flaky" event="go" id="g1"/></onentry>
|
|
239
|
+
<transition event="error.communication"><log expr="'the chart got error.communication for ' + _event.sendid"/></transition>
|
|
240
|
+
</state>
|
|
241
|
+
</scxml>` }]);
|
|
242
|
+
const host = new Host({ systemID: 'demo', ioProcessors: [{ type: 'urn:example:flaky' }] }, {
|
|
243
|
+
ioProcessors: { 'urn:example:flaky': () => { throw new Error('connection refused'); } },
|
|
244
|
+
log: (host, entry) => console.log(entry.text),
|
|
245
|
+
});
|
|
246
|
+
host.addImage(compiled.image);
|
|
247
|
+
compiled.close();
|
|
248
|
+
|
|
249
|
+
host.spawn(host.chart('c'));
|
|
250
|
+
await host.idle().catch((error) => console.log('idle() rejected:', error.message));
|
|
251
|
+
await host.idle();
|
|
252
|
+
host.close();
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
```output
|
|
256
|
+
the chart got error.communication for g1
|
|
257
|
+
idle() rejected: connection refused
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
The chart handled `error.communication` in the same turn; the error came
|
|
261
|
+
out of `idle()` at its end.
|
|
262
|
+
|
|
263
|
+
## Inputs from a handler
|
|
264
|
+
|
|
265
|
+
A handler may call the host: `host.send` an event to any actor,
|
|
266
|
+
`host.spawn` one, `host.terminate` one. The input applies at once, and
|
|
267
|
+
the actors it concerns run in the same or a later turn. It may not take
|
|
268
|
+
the host's effects itself, so there is nothing to drain or acknowledge:
|
|
269
|
+
when the handler returns, the host goes on.
|
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
# Migration
|
|
2
|
+
|
|
3
|
+
Charts change. A long-lived actor (an order that waits a week for its
|
|
4
|
+
delivery) is still running when you deploy the chart's next version, and
|
|
5
|
+
stopping it would lose its state. A migration moves running actors to the
|
|
6
|
+
new version instead, each at a moment when it is at rest, while the host
|
|
7
|
+
goes on working.
|
|
8
|
+
|
|
9
|
+
## Versions and segments
|
|
10
|
+
|
|
11
|
+
Each `addImage` makes a new **segment** of the host. When an image holds a
|
|
12
|
+
chart whose `name` is already in the host, that chart has a new version:
|
|
13
|
+
`host.chart(name)` returns the newest, so the actors spawned from then on
|
|
14
|
+
are of the new version, and the running ones stay on theirs.
|
|
15
|
+
|
|
16
|
+
`host.migrate()` moves the running actors to the newest version of their
|
|
17
|
+
chart, during the next turns. A moved actor keeps its session, its active
|
|
18
|
+
states (matched by id; [below](#states-the-new-version-enters) for those
|
|
19
|
+
that changed), its queue and its delayed sends with their data.
|
|
20
|
+
Its variables do not carry over by themselves, since the new version may
|
|
21
|
+
name them differently: the actor first gets the event
|
|
22
|
+
`error.platform.upgrade`, whose data holds the old version's variables,
|
|
23
|
+
and the new version takes what it keeps from there.
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
27
|
+
|
|
28
|
+
const image = (name, text) => {
|
|
29
|
+
const compiled = compileCharts([{ name, text }]);
|
|
30
|
+
const bytes = compiled.image;
|
|
31
|
+
compiled.close();
|
|
32
|
+
return bytes;
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
const v1 = image('counter-v1.scxml', `
|
|
36
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
37
|
+
datamodel="ecmascript" name="counter" initial="counting">
|
|
38
|
+
<datamodel><data id="n" expr="0"/></datamodel>
|
|
39
|
+
<state id="counting">
|
|
40
|
+
<transition event="add"><assign location="n" expr="n + 1"/><log expr="'v1 counts ' + n"/></transition>
|
|
41
|
+
</state>
|
|
42
|
+
</scxml>`);
|
|
43
|
+
|
|
44
|
+
// Version 2 renames n to count and counts by ten.
|
|
45
|
+
const v2 = image('counter-v2.scxml', `
|
|
46
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
47
|
+
datamodel="ecmascript" name="counter" initial="counting">
|
|
48
|
+
<datamodel><data id="count" expr="0"/></datamodel>
|
|
49
|
+
<state id="counting">
|
|
50
|
+
<transition event="error.platform.upgrade">
|
|
51
|
+
<assign location="count" expr="_event.data.n"/>
|
|
52
|
+
<log expr="'upgraded, the old variables were ' + JSON.stringify(_event.data)"/>
|
|
53
|
+
</transition>
|
|
54
|
+
<transition event="add"><assign location="count" expr="count + 10"/><log expr="'v2 counts ' + count"/></transition>
|
|
55
|
+
</state>
|
|
56
|
+
</scxml>`);
|
|
57
|
+
|
|
58
|
+
const host = new Host({ systemID: 'demo' }, {
|
|
59
|
+
log: (host, entry) => console.log(entry.text),
|
|
60
|
+
migrated: (host, moved) => console.log(`session ${moved.session} moved to segment ${moved.segment}`),
|
|
61
|
+
migrationDone: (host, result) => console.log(`migration ${result.migration}: ${result.migrated} moved, ${result.failed.length} failed`),
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
host.addImage(v1);
|
|
65
|
+
const counter = host.spawn(host.chart('counter'));
|
|
66
|
+
host.send(counter, 'add');
|
|
67
|
+
host.send(counter, 'add');
|
|
68
|
+
await host.idle();
|
|
69
|
+
|
|
70
|
+
host.addImage(v2); // the deploy
|
|
71
|
+
const id = host.migrate({ chart: 'counter' });
|
|
72
|
+
console.log(`started migration ${id}`);
|
|
73
|
+
await host.idle();
|
|
74
|
+
|
|
75
|
+
host.send(counter, 'add');
|
|
76
|
+
await host.idle();
|
|
77
|
+
host.close();
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```output
|
|
81
|
+
v1 counts 1
|
|
82
|
+
v1 counts 2
|
|
83
|
+
started migration 1
|
|
84
|
+
session 1 moved to segment 1
|
|
85
|
+
migration 1: 1 moved, 0 failed
|
|
86
|
+
upgraded, the old variables were {"n":2}
|
|
87
|
+
v2 counts 12
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Once no actor runs on an old segment, the host retires it and frees its
|
|
91
|
+
memory; `host.hostStats` counts the retired segments
|
|
92
|
+
([Inspecting a host](inspection.md)).
|
|
93
|
+
|
|
94
|
+
## States the new version enters
|
|
95
|
+
|
|
96
|
+
A migration puts the actor in the new version's states without running
|
|
97
|
+
any of their `<onentry>`, as it takes it out of the old ones without
|
|
98
|
+
their `<onexit>`: it is not a transition. The states are matched by id,
|
|
99
|
+
and the configuration is completed to a legal one:
|
|
100
|
+
|
|
101
|
+
- a state that is compound in the new version, and had no children in
|
|
102
|
+
the old, is entered at its `initial` child (or its first);
|
|
103
|
+
- a state the new version does not have at all is replaced by its
|
|
104
|
+
parent's initial state (the chart's `initial` at the top);
|
|
105
|
+
- a `<parallel>` gets all its regions, and an `<invoke>` of a state the
|
|
106
|
+
migration enters is started.
|
|
107
|
+
|
|
108
|
+
So what an `<onentry>` would have done (arm a timer, tell your program)
|
|
109
|
+
is the `error.platform.upgrade` transition's job, with `In()` to see
|
|
110
|
+
where the actor landed:
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
import { compileCharts, Host, SimulatedClock } from '@tinyactors/node';
|
|
114
|
+
|
|
115
|
+
const image = (name, text) => {
|
|
116
|
+
const compiled = compileCharts([{ name, text }]);
|
|
117
|
+
const bytes = compiled.image;
|
|
118
|
+
compiled.close();
|
|
119
|
+
return bytes;
|
|
120
|
+
};
|
|
121
|
+
|
|
122
|
+
const v1 = image('sub-v1.scxml', `
|
|
123
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
124
|
+
datamodel="ecmascript" name="subscription" initial="active">
|
|
125
|
+
<state id="active"><transition event="miss" target="pastDue"/><transition event="pause" target="paused"/></state>
|
|
126
|
+
<state id="pastDue"/>
|
|
127
|
+
<state id="paused"/>
|
|
128
|
+
</scxml>`);
|
|
129
|
+
|
|
130
|
+
// Version 2: pastDue starts a grace period, and paused is gone.
|
|
131
|
+
const v2 = image('sub-v2.scxml', `
|
|
132
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
133
|
+
datamodel="ecmascript" name="subscription" initial="active">
|
|
134
|
+
<state id="active">
|
|
135
|
+
<transition event="error.platform.upgrade"><log expr="_sessionid + ' upgraded into active'"/></transition>
|
|
136
|
+
</state>
|
|
137
|
+
<state id="pastDue" initial="grace">
|
|
138
|
+
<transition event="error.platform.upgrade" cond="In('grace')">
|
|
139
|
+
<log expr="_sessionid + ' upgraded into grace: arming its timer'"/>
|
|
140
|
+
<send event="graceOver" delay="7s"/>
|
|
141
|
+
</transition>
|
|
142
|
+
<state id="grace">
|
|
143
|
+
<onentry><log expr="'grace onentry'"/><send event="graceOver" delay="7s"/></onentry>
|
|
144
|
+
</state>
|
|
145
|
+
</state>
|
|
146
|
+
</scxml>`);
|
|
147
|
+
|
|
148
|
+
const host = new Host({ systemID: 'demo' }, { clock: new SimulatedClock(), log: (host, entry) => console.log(entry.text) });
|
|
149
|
+
host.addImage(v1);
|
|
150
|
+
const late = host.spawn(host.chart('subscription'));
|
|
151
|
+
const paused = host.spawn(host.chart('subscription'));
|
|
152
|
+
host.send(late, 'miss');
|
|
153
|
+
host.send(paused, 'pause');
|
|
154
|
+
await host.idle();
|
|
155
|
+
|
|
156
|
+
host.addImage(v2);
|
|
157
|
+
host.migrate();
|
|
158
|
+
await host.idle();
|
|
159
|
+
for (const session of [late, paused]) console.log(session, JSON.stringify((await host.actorState({ session })).value));
|
|
160
|
+
console.log('next deadline', host.nextDeadline);
|
|
161
|
+
host.close();
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
```output
|
|
165
|
+
1 upgraded into grace: arming its timer
|
|
166
|
+
2 upgraded into active
|
|
167
|
+
1n {"pastDue":"grace"}
|
|
168
|
+
2n "active"
|
|
169
|
+
next deadline 7000
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
`grace onentry` is never logged: without the upgrade transition's
|
|
173
|
+
`<send>`, actor 1 would wait in `grace` for ever.
|
|
174
|
+
|
|
175
|
+
## The calls
|
|
176
|
+
|
|
177
|
+
- **`host.migrate({ chart, session, wake, timeout })`** starts a
|
|
178
|
+
migration and returns its id, a number. With no options it moves the
|
|
179
|
+
actors of every chart; `chart` names one chart, `session` one actor.
|
|
180
|
+
`wake: true` asks for the hibernated actors (below). `timeout` is in
|
|
181
|
+
milliseconds of the host's clock, rounded up to its next tick; 0 or none
|
|
182
|
+
means none. A `chart` the host does not have throws `TA_ERROR_INVALID`
|
|
183
|
+
and a `session` that ended `TA_ERROR_STALE`: a migration that could
|
|
184
|
+
move nothing is refused rather than reported done.
|
|
185
|
+
- **`migrationDone: (host, result) => ...`**, in the host's options, gets
|
|
186
|
+
the end of each migration: `{ migration, migrated, failed, pending }`,
|
|
187
|
+
`failed` the actors it could not move, each `{ session, reason }`
|
|
188
|
+
(`reason` core's status, below), and `pending` the sessions
|
|
189
|
+
(`bigint`s) its timeout left behind. It is a
|
|
190
|
+
handler of the host, so a migration started by a host that was later
|
|
191
|
+
[restored](snapshots.md) reports to the restored host's handler.
|
|
192
|
+
- **`migrated: (host, moved) => ...`** gets each actor moved, a view of
|
|
193
|
+
`session`, `segment`, `chart` (its name) and `migration`, valid while
|
|
194
|
+
the handler runs.
|
|
195
|
+
|
|
196
|
+
## When a migration ends
|
|
197
|
+
|
|
198
|
+
A migration ends when every actor it looks at has moved, or at its
|
|
199
|
+
`timeout`. An actor that is running an invocation (an invoked chart or
|
|
200
|
+
a service) moves once the invocation ends: a migration with a `timeout`
|
|
201
|
+
waits for that until the timeout, and one without fails the actor at
|
|
202
|
+
once with `'TA_ERROR_STATE'`, since an invocation may never end. A hibernated actor moves once it is woken: with `wake:
|
|
203
|
+
true` the migration asks for it through your `wake` handler, with the
|
|
204
|
+
migration's id as the third argument, and asks again if it finds the
|
|
205
|
+
actor hibernated after a wake. Without `wake`, a hibernated actor that
|
|
206
|
+
nobody wakes holds the migration until its timeout, or forever without
|
|
207
|
+
one, and `migrationDone` is never called: give such a migration a
|
|
208
|
+
`timeout`. A migration still running when the host is closed never
|
|
209
|
+
reaches `migrationDone`.
|
|
210
|
+
|
|
211
|
+
## Actors that do not move
|
|
212
|
+
|
|
213
|
+
An actor that cannot be written out stays on its version and is in
|
|
214
|
+
the result's `failed`, with its session and the reason,
|
|
215
|
+
`'TA_ERROR_UNSUPPORTED'` for a state that cannot be written out (`host.hibernate`
|
|
216
|
+
of the actor names the variable). On the native datamodel that is one whose variables hold a value
|
|
217
|
+
outside the value table (a function, a `Map`, a `Date`, ...), or whose
|
|
218
|
+
chart's scripts declare with `let`, `const` or `class`, the same actors
|
|
219
|
+
[hibernation](hibernation.md) refuses.
|
|
220
|
+
|
|
221
|
+
On the native datamodel the upgrade event's data holds exactly the old
|
|
222
|
+
version's variables. A chart whose scripts declare top-level names gets
|
|
223
|
+
its new version's declarations (its scripts are instantiated, not run),
|
|
224
|
+
and the old names the new version does not declare are gone.
|
|
225
|
+
|
|
226
|
+
## Most actors hibernated: wake a batch at a time
|
|
227
|
+
|
|
228
|
+
A migration with `wake: true` asks for every hibernated actor early. Wake
|
|
229
|
+
them all at once and they are all in memory at once. Instead, queue the
|
|
230
|
+
migration's requests and wake a batch per round: the migration takes each
|
|
231
|
+
woken actor in its next runs. An event's request (`migration` is
|
|
232
|
+
`undefined`) still wakes its actor at once, and the migration takes that
|
|
233
|
+
one too. Put actors back to sleep once they have moved; one put back
|
|
234
|
+
before it moved is asked for again, which costs work but does not stall
|
|
235
|
+
the migration.
|
|
236
|
+
|
|
237
|
+
```js
|
|
238
|
+
import { compileCharts, Host, TinyactorsError } from '@tinyactors/node';
|
|
239
|
+
|
|
240
|
+
const image = (version) => {
|
|
241
|
+
const compiled = compileCharts([{ name: `v${version}.scxml`, text: `
|
|
242
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
243
|
+
datamodel="ecmascript" name="counter" initial="s">
|
|
244
|
+
<datamodel><data id="version" expr="${version}"/></datamodel>
|
|
245
|
+
<state id="s"><transition event="error.platform.upgrade"/></state>
|
|
246
|
+
</scxml>` }]);
|
|
247
|
+
const bytes = compiled.image;
|
|
248
|
+
compiled.close();
|
|
249
|
+
return bytes;
|
|
250
|
+
};
|
|
251
|
+
|
|
252
|
+
const store = new Map();
|
|
253
|
+
const asked = [];
|
|
254
|
+
/** @type {import('@tinyactors/node').MigrationResult | undefined} */
|
|
255
|
+
let done;
|
|
256
|
+
let mostResident = 0;
|
|
257
|
+
|
|
258
|
+
const host = new Host({ systemID: 'demo' }, {
|
|
259
|
+
wake: (host, session, migration) => {
|
|
260
|
+
if (migration !== undefined) asked.push(session); // the migration's: a batch at a time
|
|
261
|
+
else host.wake(session, store.get(session)); // an event's: now
|
|
262
|
+
},
|
|
263
|
+
migrationDone: (host, result) => (done = result),
|
|
264
|
+
});
|
|
265
|
+
|
|
266
|
+
function evict() {
|
|
267
|
+
for (const session of host.sweep(1 << 20, 1 << 20)) {
|
|
268
|
+
try {
|
|
269
|
+
store.set(session, host.hibernate(session));
|
|
270
|
+
} catch (error) {
|
|
271
|
+
if (!(error instanceof TinyactorsError)) throw error;
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
host.addImage(image(1));
|
|
277
|
+
for (let i = 0; i < 100; i++) host.spawn(host.chart('counter'));
|
|
278
|
+
await host.idle();
|
|
279
|
+
evict();
|
|
280
|
+
evict();
|
|
281
|
+
console.log(`${store.size} hibernated`);
|
|
282
|
+
|
|
283
|
+
host.addImage(image(2));
|
|
284
|
+
host.migrate({ wake: true });
|
|
285
|
+
while (done === undefined) {
|
|
286
|
+
for (const session of asked.splice(0, 10)) host.wake(session, store.get(session));
|
|
287
|
+
await host.idle();
|
|
288
|
+
const stats = await host.hostStats();
|
|
289
|
+
mostResident = Math.max(mostResident, stats.host.actors - stats.host.hibernated);
|
|
290
|
+
evict();
|
|
291
|
+
evict();
|
|
292
|
+
}
|
|
293
|
+
console.log(`${done.migrated} moved, ${done.failed.length} failed, at most ${mostResident} in memory at once`);
|
|
294
|
+
host.close();
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
```output
|
|
298
|
+
100 hibernated
|
|
299
|
+
100 moved, 0 failed, at most 10 in memory at once
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
## At scale
|
|
303
|
+
|
|
304
|
+
`tools/migration.mjs` (`mise run migration` in the repository) is this
|
|
305
|
+
pattern at scale: two million actors, at most 1000 resident, the rest in
|
|
306
|
+
SQLite.
|
|
307
|
+
|
|
308
|
+
One run of it (2026-10-16, x86_64 Linux 6.18, Intel Xeon @ 2.10GHz, 4
|
|
309
|
+
CPUs, 16 GiB; node 22.23.3, bun 1.4.1): two million actors of version 1
|
|
310
|
+
of a counter, at most 1000 resident, 200,000 events before the migration
|
|
311
|
+
and 200,000 more during it, every actor moved to version 2 with `wake:
|
|
312
|
+
true` (2,218,265 wakes from the store in each run). The migration ended
|
|
313
|
+
with every actor migrated, none failed and none left; all 25,000 sampled
|
|
314
|
+
actors had their count and version 2; version 1's segment was retired;
|
|
315
|
+
and after every eviction at most 1000 actors were resident (plus two
|
|
316
|
+
batches while the migration moved them).
|
|
317
|
+
|
|
318
|
+
| runtime, datamodel | populate (2,000,000 and 200,000 events) | migrate (2,000,000 moved, 200,000 events) | peak resident | core's region, both versions / after | SQLite file |
|
|
319
|
+
|---|---|---|---|---|---|
|
|
320
|
+
| node, native | 54.5 s | 154.2 s (12,970 a second) | 656 MB (328 B per actor) | 231 MB / 115 MB (58 B per actor) | 576 MB |
|
|
321
|
+
| node, quickjs | 42.0 s | 108.7 s (18,390 a second) | 657 MB (329 B per actor) | 231 MB / 115 MB (58 B per actor) | 756 MB |
|
|
322
|
+
| bun, native | 50.5 s | 131.2 s (15,240 a second) | 680 MB (340 B per actor) | 231 MB / 115 MB (58 B per actor) | 576 MB |
|
|
323
|
+
| bun, quickjs | 41.0 s | 109.5 s (18,270 a second) | 605 MB (303 B per actor) | 231 MB / 115 MB (58 B per actor) | 756 MB |
|