webevm 0.5.0 → 0.7.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 +52 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/node.d.ts.map +1 -1
- package/dist/node.js +242 -13
- package/dist/node.js.map +1 -1
- package/dist/types.d.ts +47 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/worker-client.d.ts.map +1 -1
- package/dist/worker-client.js +19 -1
- package/dist/worker-client.js.map +1 -1
- package/dist/worker-host.d.ts.map +1 -1
- package/dist/worker-host.js +5 -0
- package/dist/worker-host.js.map +1 -1
- package/package.json +2 -1
- package/src/index.ts +1 -0
- package/src/node.ts +244 -13
- package/src/types.ts +48 -2
- package/src/worker-client.ts +22 -1
- package/src/worker-host.ts +5 -0
package/src/node.ts
CHANGED
|
@@ -21,6 +21,17 @@
|
|
|
21
21
|
*
|
|
22
22
|
* Transport-agnostic: just `request()` (async) + mine/dump/load. Knows nothing
|
|
23
23
|
* about Workers — see ./worker-entry.ts for the optional comlink wrapper.
|
|
24
|
+
*
|
|
25
|
+
* ONE THING AT A TIME. Every public entry point on the returned node —
|
|
26
|
+
* `request`, `mine`, `dumpState`, `loadState`, `getStateRoot` — runs through
|
|
27
|
+
* {@link SlimNode}'s serialisation point, so this node executes exactly one
|
|
28
|
+
* request at a time no matter how many are in flight. It is not an optimisation
|
|
29
|
+
* and it is not politeness: the node's state manager is a STACK of checkpoints
|
|
30
|
+
* shared by reads and transactions alike, `commit()` merges downward and
|
|
31
|
+
* `revert()` discards without either knowing who opened the level it acts on, so
|
|
32
|
+
* two overlapping executions destroy each other's writes. See the comment at
|
|
33
|
+
* `serialise` below and
|
|
34
|
+
* `docs/adr/0012-one-request-at-a-time-the-node-serialises-its-whole-public-surface.md`.
|
|
24
35
|
*/
|
|
25
36
|
import {createVM, type VM} from '@ethereumjs/vm';
|
|
26
37
|
import {MerkleStateManager} from '@ethereumjs/statemanager';
|
|
@@ -53,6 +64,12 @@ import {connectEngine, createEthereumjsEngine} from './engine.js';
|
|
|
53
64
|
// Sender derivation stays the node's on every engine; what an engine may lend it
|
|
54
65
|
// is the CURVE step. See ./sender-recovery.ts.
|
|
55
66
|
import {recoverSender} from './sender-recovery.js';
|
|
67
|
+
// `serveOn(port)`: EIP-1193 `request` over a MessagePort, in the wire format the
|
|
68
|
+
// consumer's `providerOverPort` speaks. Imported HERE, the one place the node's
|
|
69
|
+
// public surface is built, so every node (main-thread or worker-hosted) serves a
|
|
70
|
+
// port the same way; see `serveOn` at the bottom of this file for why this is a
|
|
71
|
+
// dependency of the core rather than of `webevm/worker-host` alone.
|
|
72
|
+
import {serveProvider, type ServedProvider} from '@eip-1193/over-port';
|
|
56
73
|
// The engine reports EXECUTION gas for a read and the node adds intrinsic gas on top;
|
|
57
74
|
// an engine that charges intrinsic gas itself (revm) subtracts the SAME formula,
|
|
58
75
|
// so it has exactly one home. See ./intrinsic-gas.ts.
|
|
@@ -236,6 +253,17 @@ interface StoredBlock {
|
|
|
236
253
|
logs: SerializedLog[];
|
|
237
254
|
}
|
|
238
255
|
|
|
256
|
+
/**
|
|
257
|
+
* The no-op the node's serialisation chain passes in BOTH handler positions
|
|
258
|
+
* (`run.then(swallow, swallow)`), which is what keeps the chain alive across a
|
|
259
|
+
* FAILED request: `tail` must always be a promise that FULFILS, since a rejection
|
|
260
|
+
* left on it would reject every request queued behind the one that failed and turn
|
|
261
|
+
* one bad transaction into a dead node. It takes no arguments because it uses
|
|
262
|
+
* neither the value nor the reason; both are the caller's, and both have already
|
|
263
|
+
* been delivered to whoever awaited that request.
|
|
264
|
+
*/
|
|
265
|
+
function swallow(): void {}
|
|
266
|
+
|
|
239
267
|
/**
|
|
240
268
|
* ONE SUBMITTED TRANSACTION, as the node carries it from `eth_sendRawTransaction*`
|
|
241
269
|
* (or the `evm_*As` cheats) to the block it is mined in: the parsed transaction,
|
|
@@ -283,6 +311,116 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
|
|
|
283
311
|
? new MerkleStateManager()
|
|
284
312
|
: new OverlayStorageStateManager();
|
|
285
313
|
|
|
314
|
+
/**
|
|
315
|
+
* THE SERIALISATION POINT: the tail of a promise chain that every public entry
|
|
316
|
+
* point queues its work onto, so this node runs exactly ONE piece of work at a
|
|
317
|
+
* time. It is declared HERE, beside `sm`, because the thing it protects is that
|
|
318
|
+
* object and nothing else.
|
|
319
|
+
*
|
|
320
|
+
* ## What was shared, and why it corrupts
|
|
321
|
+
*
|
|
322
|
+
* A state manager is a STACK of checkpoint levels. `checkpoint()` pushes a
|
|
323
|
+
* level, a write lands in the TOP one, `commit()` merges the top level into the
|
|
324
|
+
* one below and pops it, `revert()` pops it and throws it away. Neither
|
|
325
|
+
* `commit` nor `revert` knows WHO opened the level it is acting on — there is no
|
|
326
|
+
* handle, no owner and no identity — so the stack is only meaningful while a
|
|
327
|
+
* single execution owns it.
|
|
328
|
+
*
|
|
329
|
+
* Both halves of the node open levels on THIS one stack. `engine.transact`
|
|
330
|
+
* (`runTx`) checkpoints, executes and commits; the default engine's
|
|
331
|
+
* `engine.call` checkpoints and reverts, which is what makes an `eth_call` PURE
|
|
332
|
+
* and is a requirement of that EVM, not an option (see ./engine.ts). Both are
|
|
333
|
+
* `async` and `@ethereumjs/evm` yields to the microtask queue while it
|
|
334
|
+
* interprets, so before this existed a read arriving mid-transaction produced:
|
|
335
|
+
*
|
|
336
|
+
* ```
|
|
337
|
+
* tx checkpoint [base, tx]
|
|
338
|
+
* call checkpoint [base, tx, call] <- the read arrives mid-execution
|
|
339
|
+
* tx write -> lands in the TOP level, which is the CALL's
|
|
340
|
+
* tx commit -> merges that level down and pops it
|
|
341
|
+
* call revert -> pops the merged level: the transaction's write is GONE
|
|
342
|
+
* ```
|
|
343
|
+
*
|
|
344
|
+
* Measured through this node's own RPC surface: a whole transaction lost (a
|
|
345
|
+
* plain transfer loses the sender's NONCE, so every later transaction from that
|
|
346
|
+
* account is refused as "nonce too high"), state TORN at a message-frame
|
|
347
|
+
* boundary (the EVM checkpoints per frame, so the read's level can land between
|
|
348
|
+
* an inner frame's checkpoint and its commit, leaving a state no execution could
|
|
349
|
+
* produce), an `eth_call`'s OWN write committed rather than reverted, and —
|
|
350
|
+
* because this is not about reads — two overlapping TRANSACTIONS losing a write
|
|
351
|
+
* the same way, both reporting success and both holding a receipt.
|
|
352
|
+
*
|
|
353
|
+
* ## Why the lock is HERE rather than around `engine.call`
|
|
354
|
+
*
|
|
355
|
+
* Because write-versus-write interleaves too, so a lock inside the read path
|
|
356
|
+
* would fix half of it. And because it must be INSIDE the node: the Worker
|
|
357
|
+
* transport forwards straight to `node.request` and comlink delivers
|
|
358
|
+
* concurrently, so a lock in a transport protects only consumers who use that
|
|
359
|
+
* transport. It is per NODE, which is per STATE MANAGER by construction —
|
|
360
|
+
* `createNode` builds its own `sm` and takes no state manager option, and an
|
|
361
|
+
* injected engine binds to the first node it is given to and refuses a second.
|
|
362
|
+
*
|
|
363
|
+
* ## Why EVERY request and not only the executing ones
|
|
364
|
+
*
|
|
365
|
+
* A read that never touches the EVM never checkpoints and so can never corrupt
|
|
366
|
+
* anything — but it reads the live stack INCLUDING uncommitted levels, so it
|
|
367
|
+
* reports a state no block contains. Measured, with a single transfer in flight:
|
|
368
|
+
* `eth_getBalance` saw the sender DEBITED from tick 5 and
|
|
369
|
+
* `eth_getTransactionCount` saw the nonce ADVANCED from tick 6, while
|
|
370
|
+
* `eth_blockNumber` still said 0 — and that reading is exactly what an
|
|
371
|
+
* overlapping `eth_call` could then destroy. The node's own block/receipt maps
|
|
372
|
+
* are written per-transaction inside the mining loop too, so a mid-execution
|
|
373
|
+
* `eth_getTransactionReceipt` can name a `blockHash` no lookup resolves yet.
|
|
374
|
+
* The cost is real and is stated in the ADR: a cheap read issued during a
|
|
375
|
+
* 209 ms `eth_estimateGas` search used to answer in 0.1 ms and now waits for it.
|
|
376
|
+
* A per-method exemption list was rejected because it is a promise that has to
|
|
377
|
+
* be re-proven every time a method is added, by somebody who will not know that
|
|
378
|
+
* is what they are doing.
|
|
379
|
+
*
|
|
380
|
+
* ## The shape
|
|
381
|
+
*
|
|
382
|
+
* `tail` is ALWAYS a promise that fulfils — the assignment below swallows both
|
|
383
|
+
* outcomes — so a failing request cannot poison the chain and cannot stop the
|
|
384
|
+
* queue behind it. Nothing inside the node re-enters a serialised entry point
|
|
385
|
+
* (the internal `request`, `mineBlock`, `dumpState`, `loadState` and
|
|
386
|
+
* `currentStateRoot` are all called directly, and only the returned object's
|
|
387
|
+
* members are wrapped), so a single chain cannot deadlock against itself.
|
|
388
|
+
*
|
|
389
|
+
* ## The one way a CONSUMER can deadlock it, and why it is NOT detected
|
|
390
|
+
*
|
|
391
|
+
* Control leaves the node twice while the chain is held, and both times into a
|
|
392
|
+
* consumer's code. They are not the same risk:
|
|
393
|
+
*
|
|
394
|
+
* - an `onNewHead` callback is emitted WITHOUT being awaited, so a request it
|
|
395
|
+
* issues queues behind the current one and runs when the chain drains. That
|
|
396
|
+
* is the game-loop pattern (refetch on every head) and it is ALLOWED.
|
|
397
|
+
* - a `persistence.save()` hook IS awaited — so that the dump it is handed is a
|
|
398
|
+
* snapshot of a settled state and so that the request does not resolve before
|
|
399
|
+
* the write is durable — which means a hook that AWAITS a call back into the
|
|
400
|
+
* node waits for itself forever. That rule is documented, on
|
|
401
|
+
* `PersistenceAdapter.save` where an adapter is written, and enforced nowhere.
|
|
402
|
+
*
|
|
403
|
+
* IT IS DELIBERATELY NOT ENFORCED, and this is the interesting part. The obvious
|
|
404
|
+
* guard — a flag raised around the awaited hook, with `serialise` refusing while
|
|
405
|
+
* it is set — WAS BUILT AND REMOVED, because it cannot work. The flag is held
|
|
406
|
+
* across the hook's I/O, the `await` yields the event loop for that whole
|
|
407
|
+
* duration, and JavaScript offers no way (no `AsyncLocalStorage` in a browser) to
|
|
408
|
+
* tell a request issued by the hook's own stack from one issued by anybody else
|
|
409
|
+
* in that window. Measured on a 20 ms save: a plain `setInterval` poller that had
|
|
410
|
+
* never heard of persistence got four rejections, each telling it that IT had
|
|
411
|
+
* caused a deadlock. A false refusal with a confident wrong diagnosis is worse
|
|
412
|
+
* than the hang it replaces, and it fires for every consumer who has persistence
|
|
413
|
+
* and a poller, which is this package's main use. So the honest arrangement is
|
|
414
|
+
* the one below: everyone queues, and the one pathological hook is a documented
|
|
415
|
+
* rule rather than a guess dressed as a check. See ADR 0012.
|
|
416
|
+
*/
|
|
417
|
+
let tail: Promise<void> = Promise.resolve();
|
|
418
|
+
function serialise<T>(job: () => Promise<T>): Promise<T> {
|
|
419
|
+
const run = tail.then(job);
|
|
420
|
+
tail = run.then(swallow, swallow);
|
|
421
|
+
return run;
|
|
422
|
+
}
|
|
423
|
+
|
|
286
424
|
// Touched-account set for the trie-mode dump (storage is read back via the
|
|
287
425
|
// trie's own dumpStorage). We record the addresses each tx touches at the NODE
|
|
288
426
|
// level (sender / to / created) rather than monkeypatching the state manager —
|
|
@@ -484,13 +622,18 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
|
|
|
484
622
|
|
|
485
623
|
// newHeads subscribers.
|
|
486
624
|
const headSubs = new Set<(h: {number: number; hash: string}) => void>();
|
|
487
|
-
|
|
625
|
+
// Ports `serveOn` is serving, so `dispose` can stop them all.
|
|
626
|
+
const servedPorts = new Set<ServedProvider>();
|
|
627
|
+
|
|
628
|
+
// THE INTERVAL TIMER IS ARMED AT THE BOTTOM OF THIS FUNCTION, not here, at the
|
|
629
|
+
// `miningConfig.type === 'interval'` block just above the `return`. The reason
|
|
630
|
+
// is ordering: a timer armed at this point can fire while the
|
|
631
|
+
// REST OF CONSTRUCTION is still running, and the construction-time
|
|
632
|
+
// `loadState(saved)` that the persistence option performs is deliberately not
|
|
633
|
+
// serialised (nothing can reach the node yet, because it has not been returned).
|
|
634
|
+
// Those two together are the one interleaving the serialisation point does not
|
|
635
|
+
// cover, so the timer starts after the node is fully built instead.
|
|
488
636
|
let intervalTimer: ReturnType<typeof setInterval> | undefined;
|
|
489
|
-
if (miningConfig.type === 'interval') {
|
|
490
|
-
intervalTimer = setInterval(() => {
|
|
491
|
-
void mineBlock();
|
|
492
|
-
}, miningConfig.intervalMs);
|
|
493
|
-
}
|
|
494
637
|
|
|
495
638
|
/**
|
|
496
639
|
* THE BLOCK'S LOGS BLOOM: the OR of its receipts' own blooms, which is what a
|
|
@@ -1901,12 +2044,48 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
|
|
|
1901
2044
|
if (saved && saved.chainId === chainId) await loadState(saved);
|
|
1902
2045
|
}
|
|
1903
2046
|
|
|
2047
|
+
// The dump is taken inside the chain, so it is a snapshot of a settled state,
|
|
2048
|
+
// and the hook is AWAITED inside it too, so a request does not resolve before
|
|
2049
|
+
// its state is durable (`test/persistence-reload.spec.ts` reloads the page on
|
|
2050
|
+
// the strength of that). A request arriving while the hook runs simply queues.
|
|
1904
2051
|
async function persistIfNeeded() {
|
|
1905
|
-
if (options.persistence)
|
|
2052
|
+
if (!options.persistence) return;
|
|
2053
|
+
await options.persistence.save(await dumpState());
|
|
2054
|
+
}
|
|
2055
|
+
|
|
2056
|
+
/**
|
|
2057
|
+
* ARM INTERVAL MINING, once the node is otherwise built.
|
|
2058
|
+
*
|
|
2059
|
+
* COALESCED, which a plain `setInterval` is not. The timer keeps firing while
|
|
2060
|
+
* the chain is busy, so without this a period shorter than the work in flight
|
|
2061
|
+
* (say `intervalMs: 50` against the 209 ms `eth_estimateGas` search ADR 0012
|
|
2062
|
+
* measures) appends a mine per tick and they drain afterwards as a burst of
|
|
2063
|
+
* empty blocks — and if mining outruns the period the queue never stops growing.
|
|
2064
|
+
* At most ONE tick is ever waiting: the flag is cleared when the job STARTS, so
|
|
2065
|
+
* a tick that arrives during a mine still schedules the next one.
|
|
2066
|
+
*
|
|
2067
|
+
* It goes THROUGH the serialisation point like every other way a block gets
|
|
2068
|
+
* mined, because a timer is a concurrency source the consumer never sees: it
|
|
2069
|
+
* fires whenever the event loop reaches it, which before this meant in the
|
|
2070
|
+
* middle of whatever `eth_call` happened to be executing.
|
|
2071
|
+
*/
|
|
2072
|
+
let minePending = false;
|
|
2073
|
+
if (miningConfig.type === 'interval') {
|
|
2074
|
+
intervalTimer = setInterval(() => {
|
|
2075
|
+
if (minePending) return;
|
|
2076
|
+
minePending = true;
|
|
2077
|
+
// The flag is cleared as the job STARTS rather than when it finishes, so a
|
|
2078
|
+
// tick arriving during a mine still schedules the next one, and a mine that
|
|
2079
|
+
// THROWS cannot strand the flag and silently stop interval mining.
|
|
2080
|
+
void serialise(() => {
|
|
2081
|
+
minePending = false;
|
|
2082
|
+
return mineBlock();
|
|
2083
|
+
});
|
|
2084
|
+
}, miningConfig.intervalMs);
|
|
1906
2085
|
}
|
|
1907
2086
|
|
|
1908
2087
|
// wrap mine() to persist
|
|
1909
|
-
async function
|
|
2088
|
+
async function mineAndPersist() {
|
|
1910
2089
|
const r = await mineBlock();
|
|
1911
2090
|
await persistIfNeeded();
|
|
1912
2091
|
return r;
|
|
@@ -1928,11 +2107,32 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
|
|
|
1928
2107
|
return out;
|
|
1929
2108
|
}
|
|
1930
2109
|
|
|
2110
|
+
// THE PUBLIC SURFACE, AND THE ONLY PLACE THE LOCK IS TAKEN. Everything above
|
|
2111
|
+
// this line calls the node's internals DIRECTLY and never through here, which is
|
|
2112
|
+
// what makes one promise chain safe: `persistingRequest` reaches `baseRequest`,
|
|
2113
|
+
// `mineAndPersist` reaches `mineBlock` and `persistIfNeeded` reaches `dumpState`,
|
|
2114
|
+
// none of them re-entering a wrapper. Add an entry point below and it must be
|
|
2115
|
+
// serialised too; call one of these wrappers from inside the node and it will
|
|
2116
|
+
// wait for itself forever.
|
|
2117
|
+
//
|
|
2118
|
+
// `dispose` is deliberately NOT serialised: it stops the interval timer and drops
|
|
2119
|
+
// the newHeads subscribers, touches no state, and would be useless at the back of
|
|
2120
|
+
// a queue it is meant to wind down. Note what that does NOT mean: it does not
|
|
2121
|
+
// CANCEL anything already queued. Work accepted before `dispose` still runs to
|
|
2122
|
+
// completion, including a `persistence.save()`, and only the timer stops adding
|
|
2123
|
+
// more. A caller that needs the node quiet should stop issuing requests and await
|
|
2124
|
+
// the ones it holds.
|
|
2125
|
+
//
|
|
2126
|
+
// `serveOn` is not serialised either, for the reason `dispose` is not: it
|
|
2127
|
+
// touches no state. It only relays `request`, which IS serialised, so a request
|
|
2128
|
+
// arriving over a served port queues exactly like one made directly.
|
|
2129
|
+
const publicRequest = (args: RequestArguments) =>
|
|
2130
|
+
serialise(() => persistingRequest(args));
|
|
1931
2131
|
return {
|
|
1932
|
-
request:
|
|
1933
|
-
mine,
|
|
1934
|
-
dumpState,
|
|
1935
|
-
loadState,
|
|
2132
|
+
request: publicRequest,
|
|
2133
|
+
mine: () => serialise(mineAndPersist),
|
|
2134
|
+
dumpState: () => serialise(dumpState),
|
|
2135
|
+
loadState: (state: SerializedState) => serialise(() => loadState(state)),
|
|
1936
2136
|
stateMode,
|
|
1937
2137
|
senderMode,
|
|
1938
2138
|
// Identity only: the engine object itself stays internal, so the reading is a
|
|
@@ -1945,15 +2145,46 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
|
|
|
1945
2145
|
"no state root in 'none' mode — create the node with stateMode:'trie' for a real Merkle-Patricia root",
|
|
1946
2146
|
);
|
|
1947
2147
|
}
|
|
1948
|
-
|
|
2148
|
+
// SERIALISED like the rest, because this one READS BY WRITING: in trie mode
|
|
2149
|
+
// `currentStateRoot` flushes the state manager's cache into the trie, so a
|
|
2150
|
+
// root taken mid-transaction would both report an uncommitted state and
|
|
2151
|
+
// push it into the trie on the way.
|
|
2152
|
+
return serialise(currentStateRoot);
|
|
1949
2153
|
},
|
|
1950
2154
|
onNewHead(cb) {
|
|
1951
2155
|
headSubs.add(cb);
|
|
1952
2156
|
return () => headSubs.delete(cb);
|
|
1953
2157
|
},
|
|
2158
|
+
// SERVE `request` ON A HANDED PORT, via `@eip-1193/over-port`, so a consumer
|
|
2159
|
+
// on another thread uses this node through `providerOverPort(otherEnd)`.
|
|
2160
|
+
//
|
|
2161
|
+
// IT LIVES ON THE CORE NODE, NOT ONLY IN `webevm/worker-host`, so the two
|
|
2162
|
+
// kinds of node stay interchangeable: `SlimNode` carries it, the one worker
|
|
2163
|
+
// proxy forwards it (its `Required<SlimNode>` annotation demands that), and a
|
|
2164
|
+
// main-thread node answers the same call in place. The price is that the
|
|
2165
|
+
// core imports `@eip-1193/over-port` (about 6 kB of unminified JS, no
|
|
2166
|
+
// runtime dependency of its own), which `webevm/worker-client` and
|
|
2167
|
+
// `webevm/revm` still do not: the client only TRANSFERS the port, and
|
|
2168
|
+
// the consumer brings its own `providerOverPort`.
|
|
2169
|
+
//
|
|
2170
|
+
// Only `request` is served, bound to the SERIALISED entry point above.
|
|
2171
|
+
async serveOn(port: MessagePort) {
|
|
2172
|
+
const server = serveProvider({request: publicRequest}, port);
|
|
2173
|
+
servedPorts.add(server);
|
|
2174
|
+
return {
|
|
2175
|
+
async close() {
|
|
2176
|
+
server.close();
|
|
2177
|
+
servedPorts.delete(server);
|
|
2178
|
+
},
|
|
2179
|
+
};
|
|
2180
|
+
},
|
|
1954
2181
|
async dispose() {
|
|
1955
2182
|
if (intervalTimer) clearInterval(intervalTimer);
|
|
1956
2183
|
headSubs.clear();
|
|
2184
|
+
// A disposed node stops answering on every port it was serving, so a
|
|
2185
|
+
// consumer is not left talking to a node its owner has let go of.
|
|
2186
|
+
for (const server of servedPorts) server.close();
|
|
2187
|
+
servedPorts.clear();
|
|
1957
2188
|
},
|
|
1958
2189
|
};
|
|
1959
2190
|
}
|
package/src/types.ts
CHANGED
|
@@ -41,7 +41,23 @@ export type MiningConfig =
|
|
|
41
41
|
export interface PersistenceAdapter {
|
|
42
42
|
/** Load the single serialized state record (or null on first run). */
|
|
43
43
|
load(): Promise<SerializedState | null>;
|
|
44
|
-
/**
|
|
44
|
+
/**
|
|
45
|
+
* Persist the single serialized state record.
|
|
46
|
+
*
|
|
47
|
+
* DO NOT CALL BACK INTO THE NODE FROM HERE. A node serves one request at a
|
|
48
|
+
* time, and this hook is AWAITED inside the request that triggered it — that
|
|
49
|
+
* is what makes `state` a snapshot of a settled chain rather than one caught
|
|
50
|
+
* mid-transaction, and what stops a request resolving before its state is
|
|
51
|
+
* durable. A `node.request(...)` awaited from inside this function therefore
|
|
52
|
+
* waits for a queue that is waiting for this function, and the node stops.
|
|
53
|
+
* Everything you could ask it for is already in `state`; if you need the node
|
|
54
|
+
* itself, do that work after `save()` resolves.
|
|
55
|
+
*
|
|
56
|
+
* It is a rule rather than a check because the two cases cannot be told apart:
|
|
57
|
+
* see `docs/adr/0012-one-request-at-a-time-the-node-serialises-its-whole-public-surface.md`.
|
|
58
|
+
* Other callers are unaffected — a request issued elsewhere while this hook is
|
|
59
|
+
* running simply queues behind it.
|
|
60
|
+
*/
|
|
45
61
|
save(state: SerializedState): Promise<void>;
|
|
46
62
|
}
|
|
47
63
|
|
|
@@ -585,10 +601,40 @@ export interface SlimNode {
|
|
|
585
601
|
* a receipt from this node can be attributed to this id.
|
|
586
602
|
*/
|
|
587
603
|
readonly engine: EngineInfo;
|
|
588
|
-
/**
|
|
604
|
+
/**
|
|
605
|
+
* SERVE this node's EIP-1193 `request` on `port`, for whoever holds the other
|
|
606
|
+
* end of its `MessageChannel`: that side calls `providerOverPort(port)` from
|
|
607
|
+
* `@eip-1193/over-port` and gets a provider. The concrete case is a consumer in
|
|
608
|
+
* ANOTHER worker (an indexer, say) talking to a worker-hosted node directly,
|
|
609
|
+
* with the page that made the channel relaying nothing once the ports are
|
|
610
|
+
* handed over.
|
|
611
|
+
*
|
|
612
|
+
* On a worker-hosted node the port is TRANSFERRED into the node's worker (it
|
|
613
|
+
* is unusable on the calling thread afterwards); on a main-thread node it is
|
|
614
|
+
* served in place. Only `request` crosses: `onNewHead` and the other controls
|
|
615
|
+
* stay on the node. Every request served this way goes through the same
|
|
616
|
+
* serialisation point as any other, and an error the node raises arrives with
|
|
617
|
+
* its `code`, `message` and `data`.
|
|
618
|
+
*
|
|
619
|
+
* Call it once per consumer; each call serves one port. `dispose()` stops all
|
|
620
|
+
* of them. Resolves once the port is being served.
|
|
621
|
+
*/
|
|
622
|
+
serveOn(port: MessagePort): Promise<ServedPort>;
|
|
623
|
+
/** Stop timers / release resources, and stop serving every {@link serveOn} port. */
|
|
589
624
|
dispose(): Promise<void>;
|
|
590
625
|
}
|
|
591
626
|
|
|
627
|
+
/** A port {@link SlimNode.serveOn} is serving. */
|
|
628
|
+
export interface ServedPort {
|
|
629
|
+
/**
|
|
630
|
+
* Stop answering on this port. Requests already in flight still get their
|
|
631
|
+
* answer; later ones get NONE (the consumer's `providerOverPort(...).close()` is
|
|
632
|
+
* how that side stops waiting). The port itself is not closed: it was handed
|
|
633
|
+
* over, and closing it is its holder's call.
|
|
634
|
+
*/
|
|
635
|
+
close(): Promise<void>;
|
|
636
|
+
}
|
|
637
|
+
|
|
592
638
|
/**
|
|
593
639
|
* Slim, live-set-sized serialized state. No trie, no RLP state-root walk.
|
|
594
640
|
*
|
package/src/worker-client.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* thread) and `createWorkerNode()` (Worker) are interchangeable one-liners and
|
|
6
6
|
* the consumer never hand-rolls the comlink plumbing.
|
|
7
7
|
*/
|
|
8
|
-
import {wrap, proxy} from 'comlink';
|
|
8
|
+
import {wrap, proxy, transfer, releaseProxy, type Remote} from 'comlink';
|
|
9
9
|
// The api TYPE, from the module that defines it rather than from the one that
|
|
10
10
|
// exposes it: this client drives ANY worker exposing it, including a consumer's
|
|
11
11
|
// own `exposeNode({createEngine})` module. Type-only, so nothing is imported at
|
|
@@ -16,6 +16,7 @@ import type {
|
|
|
16
16
|
SlimNode,
|
|
17
17
|
RequestArguments,
|
|
18
18
|
SerializedState,
|
|
19
|
+
ServedPort,
|
|
19
20
|
} from './types.js';
|
|
20
21
|
|
|
21
22
|
export interface WorkerNodeOptions extends NodeOptions {
|
|
@@ -104,6 +105,26 @@ export async function createWorkerNode(
|
|
|
104
105
|
void unsub?.();
|
|
105
106
|
};
|
|
106
107
|
},
|
|
108
|
+
async serveOn(port: MessagePort) {
|
|
109
|
+
// TRANSFERRED, never cloned: a MessagePort cannot be cloned at all, and the
|
|
110
|
+
// point is that the port now belongs to the node's worker, so a consumer
|
|
111
|
+
// holding the other end reaches that worker without this thread in between.
|
|
112
|
+
//
|
|
113
|
+
// The cast restores what comlink's types cannot see: the worker-host proxy
|
|
114
|
+
// hands the `ServedPort` back wrapped in `proxy()`, so what arrives is a
|
|
115
|
+
// Remote (with a proxy to release), not a clone.
|
|
116
|
+
const served = (await remote.serveOn(
|
|
117
|
+
transfer(port, [port]),
|
|
118
|
+
)) as unknown as Remote<ServedPort>;
|
|
119
|
+
return {
|
|
120
|
+
async close() {
|
|
121
|
+
await served.close();
|
|
122
|
+
served[releaseProxy]();
|
|
123
|
+
},
|
|
124
|
+
};
|
|
125
|
+
},
|
|
126
|
+
// Terminating the worker also ends every port it was serving: a consumer's
|
|
127
|
+
// requests then get no answer, as they would from a stopped port.
|
|
107
128
|
async dispose() {
|
|
108
129
|
await remote.dispose();
|
|
109
130
|
worker.terminate();
|
package/src/worker-host.ts
CHANGED
|
@@ -108,6 +108,11 @@ function nodeProxy(node: SlimNode): SlimNode {
|
|
|
108
108
|
// newHeads over comlink: the callback arrives as a comlink proxy, and the
|
|
109
109
|
// unsubscribe going back must be marked as one too, or it clones as `{}`.
|
|
110
110
|
onNewHead: (cb) => proxy(node.onNewHead(cb)),
|
|
111
|
+
// The port arrives TRANSFERRED (the client marks it so), which makes it this
|
|
112
|
+
// thread's: the node serves it right here, and a consumer holding the other
|
|
113
|
+
// end talks to this worker directly. The handle going back carries a
|
|
114
|
+
// function, so it crosses as a proxy, like the unsubscribe above.
|
|
115
|
+
serveOn: async (port) => proxy(await node.serveOn(port)),
|
|
111
116
|
dispose: () => node.dispose(),
|
|
112
117
|
};
|
|
113
118
|
return forwarded;
|