@tinyactors/node 0.2.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.
@@ -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 |