@nimbus-sh/worker 0.2.3 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/dist/_shared/session-router.d.ts +8 -0
  2. package/dist/_shared/session-router.d.ts.map +1 -1
  3. package/dist/_shared/session-router.js +8 -0
  4. package/dist/facets/cirrus-real.js +1 -1
  5. package/dist/facets/manager.d.ts +40 -126
  6. package/dist/facets/manager.d.ts.map +1 -1
  7. package/dist/facets/manager.js +97 -313
  8. package/dist/facets/opencode-staging.d.ts +1 -1
  9. package/dist/facets/opencode-staging.d.ts.map +1 -1
  10. package/dist/facets/opencode-staging.js +4 -0
  11. package/dist/facets/vite-dev-server.d.ts +2 -2
  12. package/dist/facets/vite-dev-server.js +4 -4
  13. package/dist/git/commands.d.ts +8 -0
  14. package/dist/git/commands.d.ts.map +1 -1
  15. package/dist/git/commands.js +41 -9
  16. package/dist/git/network-facet.d.ts +1 -1
  17. package/dist/git/network-facet.d.ts.map +1 -1
  18. package/dist/git/network-facet.js +35 -12
  19. package/dist/git-bundle.generated.d.ts +2 -2
  20. package/dist/git-bundle.generated.d.ts.map +1 -1
  21. package/dist/git-bundle.generated.js +3 -3
  22. package/dist/index.js +1 -1
  23. package/dist/loaders/child-process/spawn-facet.js +1 -1
  24. package/dist/loaders/child-process/spawn-pool.d.ts.map +1 -1
  25. package/dist/loaders/child-process/spawn-pool.js +2 -2
  26. package/dist/loaders/generated-workers.d.ts +1 -1
  27. package/dist/loaders/generated-workers.d.ts.map +1 -1
  28. package/dist/loaders/generated-workers.js +2 -2
  29. package/dist/loaders/npm-resolve-preamble.d.ts +3 -3
  30. package/dist/loaders/npm-resolve-preamble.js +3 -3
  31. package/dist/loaders/pre-bundle-preamble.d.ts +5 -5
  32. package/dist/loaders/pre-bundle-preamble.js +6 -6
  33. package/dist/loaders/process-host.d.ts +6 -107
  34. package/dist/loaders/process-host.d.ts.map +1 -1
  35. package/dist/loaders/process-host.js +6 -405
  36. package/dist/npm/install-batch-facet.js +1 -1
  37. package/dist/npm/installer.d.ts +4 -4
  38. package/dist/npm/installer.js +18 -18
  39. package/dist/npm/pre-bundle-facet.d.ts +2 -2
  40. package/dist/npm/pre-bundle-facet.js +5 -5
  41. package/dist/npm/resolve-facet.d.ts +1 -1
  42. package/dist/npm/resolve-facet.js +1 -1
  43. package/dist/npm/resolve-one-facet.d.ts +5 -5
  44. package/dist/npm/resolve-one-facet.js +5 -5
  45. package/dist/router/index.js +1 -1
  46. package/dist/router/remote-api.js +8 -0
  47. package/dist/runtime/bun-repl.d.ts +1 -1
  48. package/dist/runtime/bun-repl.js +3 -3
  49. package/dist/runtime/facet-loader-host.d.ts +5 -8
  50. package/dist/runtime/facet-loader-host.d.ts.map +1 -1
  51. package/dist/runtime/facet-loader-host.js +7 -11
  52. package/dist/runtime/node-repl.js +2 -2
  53. package/dist/runtime/python-repl.js +3 -3
  54. package/dist/runtime/ruby-repl.js +2 -2
  55. package/dist/runtime/ruby-resident.js +1 -1
  56. package/dist/session/hibernation.d.ts +18 -51
  57. package/dist/session/hibernation.d.ts.map +1 -1
  58. package/dist/session/hibernation.js +49 -186
  59. package/dist/session/init-phases.d.ts +2 -2
  60. package/dist/session/init-phases.d.ts.map +1 -1
  61. package/dist/session/init-phases.js +1 -1
  62. package/dist/session/init.d.ts.map +1 -1
  63. package/dist/session/init.js +6 -3
  64. package/dist/session/keys.d.ts +14 -37
  65. package/dist/session/keys.d.ts.map +1 -1
  66. package/dist/session/keys.js +17 -37
  67. package/dist/session/nimbus-session.d.ts +10 -4
  68. package/dist/session/nimbus-session.d.ts.map +1 -1
  69. package/dist/session/nimbus-session.js +20 -11
  70. package/dist/session/port-capability.d.ts +43 -0
  71. package/dist/session/port-capability.d.ts.map +1 -0
  72. package/dist/session/port-capability.js +49 -0
  73. package/dist/session/programmatic.d.ts +41 -5
  74. package/dist/session/programmatic.d.ts.map +1 -1
  75. package/dist/session/programmatic.js +147 -15
  76. package/dist/session/routes.d.ts +2 -0
  77. package/dist/session/routes.d.ts.map +1 -1
  78. package/dist/session/routes.js +91 -16
  79. package/dist/session/rpc.d.ts +35 -8
  80. package/dist/session/rpc.d.ts.map +1 -1
  81. package/dist/session/rpc.js +73 -14
  82. package/dist/session/start-real-vite.d.ts.map +1 -1
  83. package/dist/session/start-real-vite.js +2 -0
  84. package/dist/session/state-store.d.ts +3 -2
  85. package/dist/session/state-store.d.ts.map +1 -1
  86. package/dist/session/state-store.js +3 -2
  87. package/dist/session/supervisor-rpc.d.ts.map +1 -1
  88. package/dist/session/supervisor-rpc.js +5 -0
  89. package/dist/session/ws.d.ts +2 -2
  90. package/dist/session/ws.d.ts.map +1 -1
  91. package/dist/session/ws.js +2 -2
  92. package/dist/wrangler/nimbus-wrangler.js +1 -1
  93. package/package.json +3 -2
  94. package/dist/facets/inner-do-registry.d.ts +0 -41
  95. package/dist/facets/inner-do-registry.d.ts.map +0 -1
  96. package/dist/facets/inner-do-registry.js +0 -51
  97. package/dist/facets/launch-pacer.d.ts +0 -111
  98. package/dist/facets/launch-pacer.d.ts.map +0 -1
  99. package/dist/facets/launch-pacer.js +0 -130
  100. package/dist/loaders/fanout-pool.d.ts +0 -207
  101. package/dist/loaders/fanout-pool.d.ts.map +0 -1
  102. package/dist/loaders/fanout-pool.js +0 -363
  103. package/dist/loaders/loader-pool.d.ts +0 -294
  104. package/dist/loaders/loader-pool.d.ts.map +0 -1
  105. package/dist/loaders/loader-pool.js +0 -642
  106. package/dist/loaders/process-fabric.d.ts +0 -509
  107. package/dist/loaders/process-fabric.d.ts.map +0 -1
  108. package/dist/loaders/process-fabric.js +0 -360
  109. package/dist/loaders/vendor/errors.d.ts +0 -24
  110. package/dist/loaders/vendor/errors.d.ts.map +0 -1
  111. package/dist/loaders/vendor/errors.js +0 -46
  112. package/dist/loaders/vendor/serialize.d.ts +0 -3
  113. package/dist/loaders/vendor/serialize.d.ts.map +0 -1
  114. package/dist/loaders/vendor/serialize.js +0 -25
  115. package/dist/loaders/vendor/types.d.ts +0 -69
  116. package/dist/loaders/vendor/types.d.ts.map +0 -1
  117. package/dist/loaders/vendor/types.js +0 -4
  118. package/dist/loaders/workerd-facet-host.d.ts +0 -141
  119. package/dist/loaders/workerd-facet-host.d.ts.map +0 -1
  120. package/dist/loaders/workerd-facet-host.js +0 -284
  121. package/dist/session/bindings.d.ts +0 -209
  122. package/dist/session/bindings.d.ts.map +0 -1
  123. package/dist/session/bindings.js +0 -680
  124. package/dist/session/ctx-exports.d.ts +0 -16
  125. package/dist/session/ctx-exports.d.ts.map +0 -1
  126. package/dist/session/ctx-exports.js +0 -22
  127. package/dist/session/ws-hibernation-config.d.ts +0 -64
  128. package/dist/session/ws-hibernation-config.d.ts.map +0 -1
  129. package/dist/session/ws-hibernation-config.js +0 -89
@@ -1,509 +0,0 @@
1
- /**
2
- * process-fabric.ts — the resident-process scheduler, and the process half of
3
- * the substrate it runs on.
4
- *
5
- * Every long-lived process Nimbus runs — node servers, python/ruby socket
6
- * servers, the opencode TUI and its headless server — runs as a **DO Facet**:
7
- * a named child actor whose class comes from a dynamic worker, opened by
8
- * `openResidentFacet` in `loaders/workerd-facet-host.ts`.
9
- *
10
- * ctx.facets.get(`proc-${pid}`, () => ({
11
- * class: env.LOADER.get(workerKey, buildConfig)
12
- * .getDurableObjectClass('NimbusProcess'),
13
- * }))
14
- *
15
- * There is ONE process implementation. What varies is WHOSE `ctx` and `env`
16
- * that call runs against — the user's own session DO, or a sibling DO acting
17
- * as a host — and that choice is a single deployment-wide config value read in
18
- * `loaders/process-host.ts`. Nothing here, and nothing above here, branches on
19
- * which program is running: no spawn site picks its own substrate, and no
20
- * program name, mode or payload size reaches the selection.
21
- *
22
- * What each substrate costs, all of it measured on the production
23
- * compatibility shape (see `loaders/process-host.ts` for the operator-facing
24
- * version of this table):
25
- *
26
- * facet — spawn 8-16 ms warm. Memory independent: its OWN ~208 MiB
27
- * envelope, identical whether the coordinator holds 0 or 128 MiB,
28
- * with 1,664 MiB live across 8 facets + parent. CPU SHARED with
29
- * its siblings, because facets are separate isolates inside one
30
- * actor thread: awaiting I/O yields that thread completely (a
31
- * sibling's RPC latency while a facet parks on a socket, on stdin
32
- * or on an outbound call is indistinguishable from idle) but
33
- * sustained CPU stalls every sibling for its full duration —
34
- * a python HTTP server at 32-way saturation held siblings under
35
- * 1.06 s (p50 231 ms), the opencode attach TUI held them at the
36
- * 77 ms idle baseline, and a deliberate 9,956 ms CPU burn stalled
37
- * them for 9,966 ms.
38
- * peer — spawn 242-359 ms, because every spawn pays a DO create plus a
39
- * SQLite open. Memory AND CPU both independent: the process runs
40
- * in a different workerd process, verified per placement rather
41
- * than assumed (see `_place` in `loaders/process-host.ts`).
42
- *
43
- * Both give the process its own SQLite. Neither changes what the process is:
44
- * the runner, the boot spec, the class name, the writer handshake and the
45
- * lifecycle contract are the same code either way.
46
- *
47
- * The facet's SUPERVISOR binding is minted for the COORDINATOR's doId, so
48
- * every syscall — VFS read/write, stdout/stderr frames, stdin pump,
49
- * registerPort, loopback HTTP — lands on the user's session DO wherever the
50
- * process runs. Because that binding is minted by an actor rather than by a
51
- * stateless entrypoint, it lives as long as the process does; nothing has to
52
- * hold a call open to keep it alive.
53
- *
54
- * Boot specs
55
- * ──────────
56
- * A resident process boots from one of two specs, and in both cases the module
57
- * map is assembled LAZILY inside the loader's cache-miss callback — so the
58
- * artifact sources are materialized only when the facet actually starts, and
59
- * only for as long as the load takes:
60
- *
61
- * staged — an OpencodeStageSpec; `assembleOpencodeFacetConfig` fetches the
62
- * artifact sources from ASSETS.
63
- * code — a generated module map (node / python / ruby runners). Fixed-size
64
- * module text rides inline; anything sized by the user's disk is
65
- * named BY VFS PATH and read through the injected disk reader. A
66
- * ruby server's `ruby+stdlib.wasm` alone is 34.3 MiB and a node
67
- * facet's disk snapshot reached 44 MB for pi.
68
- *
69
- * By-path is what lets a boot spec reach EITHER substrate. Inline, pi's node
70
- * snapshot serialized to 44,252,709 bytes and died at workerd's 32 MiB RPC
71
- * ceiling the moment it had to cross to a peer; named by path it sends zero
72
- * bytes, and the host reads them off the coordinator's own disk through the
73
- * `ResidentDiskReader` it was given.
74
- */
75
- import { z } from 'zod/v4';
76
- import type { RouteableFacetTarget } from '@nimbus-sh/core/runtime/os-contracts.js';
77
- /**
78
- * The class every generated resident runner exports. One name for every
79
- * runtime: the fabric names it unconditionally, so nothing about which program
80
- * is running reaches this module.
81
- */
82
- export declare const RESIDENT_PROCESS_CLASS = "NimbusProcess";
83
- /**
84
- * Runner contract for `startProcess()`. A property of the generated runner,
85
- * not of placement:
86
- *
87
- * lifetime — the call is held open for the process's whole life and settles
88
- * only at exit (opencode attached + server, attached-TTY node).
89
- * boot — the call returns a boot payload once the process is up and the
90
- * facet stays resident as the coordinator's named child actor
91
- * (node servers, the python/ruby socket runners).
92
- */
93
- export type StartContract = 'lifetime' | 'boot';
94
- /**
95
- * A generated module map. Only bounded, fixed-size module text rides inline;
96
- * anything whose size is a function of the user's disk is named by VFS path
97
- * and read when the facet loads, so the bytes are transient rather than
98
- * resident in the coordinator's heap.
99
- */
100
- export declare const ResidentCodeSpecSchema: z.ZodObject<{
101
- compatibilityDate: z.ZodString;
102
- compatibilityFlags: z.ZodArray<z.ZodString>;
103
- mainModule: z.ZodString;
104
- modules: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
105
- wasm: z.ZodCustom<ArrayBuffer, ArrayBuffer>;
106
- }, z.core.$strip>]>>;
107
- vfsWasmModules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
108
- vfsTextModules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
109
- }, z.core.$strip>;
110
- export type ResidentCodeSpec = z.infer<typeof ResidentCodeSpecSchema>;
111
- export declare const ResidentBootSpecSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
112
- kind: z.ZodLiteral<"staged">;
113
- stage: z.ZodObject<{
114
- mode: z.ZodEnum<{
115
- oneshot: "oneshot";
116
- attached: "attached";
117
- server: "server";
118
- }>;
119
- argv: z.ZodArray<z.ZodString>;
120
- env: z.ZodRecord<z.ZodString, z.ZodString>;
121
- cred: z.ZodObject<{
122
- uid: z.ZodNumber;
123
- gid: z.ZodNumber;
124
- groups: z.ZodArray<z.ZodNumber>;
125
- umask: z.ZodNumber;
126
- }, z.core.$strip>;
127
- cwd: z.ZodString;
128
- stdin: z.ZodString;
129
- vfsBundle: z.ZodString;
130
- vfsManifest: z.ZodString;
131
- vfsMetadata: z.ZodString;
132
- vfsCursor: z.ZodString;
133
- }, z.core.$strip>;
134
- }, z.core.$strip>, z.ZodObject<{
135
- kind: z.ZodLiteral<"code">;
136
- code: z.ZodObject<{
137
- compatibilityDate: z.ZodString;
138
- compatibilityFlags: z.ZodArray<z.ZodString>;
139
- mainModule: z.ZodString;
140
- modules: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
141
- wasm: z.ZodCustom<ArrayBuffer, ArrayBuffer>;
142
- }, z.core.$strip>]>>;
143
- vfsWasmModules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
144
- vfsTextModules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
145
- }, z.core.$strip>;
146
- }, z.core.$strip>], "kind">;
147
- export type ResidentBootSpec = z.infer<typeof ResidentBootSpecSchema>;
148
- /**
149
- * Where a generated module source is materialized so a boot spec can name it.
150
- *
151
- * Outside any user working tree on purpose. The passes that build a node
152
- * facet's snapshot enumerate the process's cwd, so an image written under one
153
- * would be swept into the next snapshot — and that snapshot is what produced
154
- * the image, so each spawn would grow the thing it just wrote.
155
- *
156
- * Kernel-owned and world-readable: the generator writes as CRED_KERNEL, and
157
- * every process reads through a supervisor binding that enforces its own
158
- * credential. Mode 0644 is what makes the read succeed for any process by
159
- * construction rather than by a privilege carve-out in the permission layer,
160
- * and leaves the bytes beyond reach of the user whose program they encode.
161
- */
162
- export declare const FACET_IMAGE_DIR = "var/lib/nimbus/facet-images";
163
- /**
164
- * An image is named by the SHA-256 of its own bytes, so its name IS its
165
- * integrity check and a stale image is not something to invalidate but
166
- * something that cannot be addressed: different generated text is a different
167
- * path.
168
- *
169
- * What that actually dedups, measured on a deployed worker rather than
170
- * assumed: a RESTART resolves to the image already there, because the fabric
171
- * replays one unchanged boot spec. Two separate spawns of the same tool do
172
- * NOT, whenever the generated text carries anything per-process: an
173
- * attached-TTY spawn bakes `NIMBUS_CP_CHILD_PID` into `__NIMBUS_ARGS`, so `pi`
174
- * twice wrote two images (2c3a90ad… then c5b74f1a…). A spawn with no attached
175
- * TTY has no pid in its args and does dedup. Lifting argv/env/pid out of the
176
- * generated text into `startArgs` would make every image per-PROGRAM and
177
- * shareable across spawns and sessions; the sweep bounds the store either way.
178
- */
179
- export declare function facetImageDigest(source: string): Promise<string>;
180
- export declare function facetImagePath(digest: string): string;
181
- /**
182
- * The digest an image path claims, for the reader's verify-on-read. Content
183
- * addressing only holds if the bytes are checked against the name they were
184
- * fetched under; without that a truncated or overwritten image boots as
185
- * silently-wrong code, which in a facet surfaces as an unattributable
186
- * "Cannot find module" a long way from the corruption.
187
- */
188
- export declare function facetImagePathDigest(path: string): string | null;
189
- /**
190
- * Reads the members a boot spec named by path off the SESSION's disk — the
191
- * coordinator's, always, whichever substrate is doing the reading.
192
- *
193
- * The session supplies it, because it owns the filesystem and the credential
194
- * the kernel reads its own image store with; the fabric never learns either.
195
- * A host that runs inside the coordinator answers synchronously off the local
196
- * VFS; a host that runs elsewhere answers over the supervisor RPC. That is the
197
- * whole of the difference, and it is why the return type is widened rather
198
- * than the reader duplicated.
199
- */
200
- export interface ResidentDiskReader {
201
- readFile(path: string): Uint8Array | Promise<Uint8Array>;
202
- }
203
- /**
204
- * Complete a resident-process module map: read every member the spec named by
205
- * path, verifying each generated image against the digest its own path claims.
206
- * Runs inside the loader's cache-miss callback, so the bytes exist only for
207
- * the duration of the load.
208
- */
209
- export declare function residentLoaderConfig(spec: ResidentCodeSpec, disk: ResidentDiskReader): Promise<Record<string, unknown>>;
210
- /**
211
- * The identity a resident process's SUPERVISOR binding is minted for. Always
212
- * the COORDINATOR's — a process hosted somewhere else still reads and writes
213
- * the user's disk, and still reports to the user's process table.
214
- */
215
- export interface ResidentSupervisorProps {
216
- doId: string;
217
- pid: number;
218
- writerId: string;
219
- }
220
- /** Everything a host needs to run one process. Substrate-free by construction. */
221
- export interface ProcessHostParams {
222
- /** Supervisor-assigned pid of the process entry on the coordinator. */
223
- pid: number;
224
- /** Keyed dynamic-worker identity (`nimbus-process:${doId}:${pid}`). */
225
- workerKey: string;
226
- /** What the process boots from. */
227
- boot: ResidentBootSpec;
228
- /** Binds the facet-local append sequence to this concrete incarnation. */
229
- writerId: string;
230
- /** Forwarded verbatim to the runner's startProcess. */
231
- startArgs: unknown;
232
- }
233
- /**
234
- * One resident process, as its coordinator sees it. Identical in meaning on
235
- * every substrate — that identity IS the abstraction, so a divergence here is
236
- * a bug rather than a documented difference.
237
- */
238
- export interface HostedProcess {
239
- /**
240
- * The runner's startProcess payload. The runner is started as part of
241
- * opening the host, so this is a handle on that one boot — awaiting it twice
242
- * is safe and never re-starts anything. A `lifetime` runner settles it at
243
- * exit; a host that dies before then rejects it.
244
- */
245
- readonly started: Promise<unknown>;
246
- /**
247
- * Rejects if the HOST dies under a process that is already up — the one
248
- * failure a substrate can suffer that the process itself never reports.
249
- *
250
- * It is not symmetric, and pretending otherwise is what leaks a process. A
251
- * facet dies only with the Durable Object that owns it, which takes the
252
- * coordinator and this handle with it, so there is nothing to observe and
253
- * this never settles; its death shows up at the next use, loudly. A peer can
254
- * die on its own, the held host leg says so, and throwing that away would
255
- * leave a `boot`-contract process routing to a corpse until someone killed
256
- * it by hand.
257
- */
258
- readonly lost: Promise<never>;
259
- /** Inbound HTTP for the process's registered ports. */
260
- handleHttpRequest(request: Request): Promise<Response>;
261
- /**
262
- * Idempotent teardown. Settles only once the process is actually gone —
263
- * on a remote host that is a round trip, and the writer identity this
264
- * incarnation holds may not be retired before it completes.
265
- */
266
- release(): Promise<void>;
267
- /** Human-readable placement, for the NIMBUS_DEBUG process-log line. */
268
- describe(): string;
269
- }
270
- /**
271
- * How a whole session-filesystem image can reach a process on a substrate, and
272
- * what stops it.
273
- *
274
- * This is the one place the two substrates are NOT interchangeable, so it is
275
- * stated rather than smoothed over. Everything else about a process is the
276
- * same code either way; this is not, and an operator flipping the config is
277
- * changing it.
278
- */
279
- export interface ProcessImageDelivery {
280
- /**
281
- * Whether the hosting actor can hand a process its whole SQLite by
282
- * copy-on-write, present before the process's first instruction.
283
- *
284
- * `same-object` — possible in principle: the host and the source live in one
285
- * Durable Object, which is the only scope `ctx.facets.clone` works in.
286
- * Measured on production workerd at 18-31 ms for a 45.73 MB pi-shaped
287
- * corpus and 34-54 ms for 1 GB — flat across a 256x size range, because
288
- * nothing is copied.
289
- * `impossible` — and not for want of an implementation. Clone is
290
- * same-Durable-Object, bookmarks are same-Durable-Object, and workerd
291
- * exposes no `VACUUM INTO`, no `ATTACH` and no `sqlite3_backup` to reach
292
- * across one. A peer-hosted process can only ever receive an image
293
- * through `moduleCeilingBytes` below, or by streaming it.
294
- *
295
- * Reachable in PRODUCTION but not from a type checker or `wrangler dev`, and
296
- * the difference is worth stating precisely because inferring one from the
297
- * other is how a wrong claim gets written down. `@cloudflare/workers-types`
298
- * 4.20260605.1 declares `get`/`abort`/`delete` and no `clone`, and the pinned
299
- * workerd is 1.20260603.1 — but the deployed runtime is Cloudflare's, not the
300
- * one wrangler bundles, and there it is present and works: enumerating the
301
- * binding on a live Worker at this repo's own compatibility_date returns
302
- * `["abort","clone","constructor","delete","get"]`, and a clone into a
303
- * destination of a DIFFERENT class had all 500 seeded files readable from the
304
- * destination's CONSTRUCTOR. No compat-date gate. So calling it is a
305
- * lockfile-and-types problem, not a platform one.
306
- *
307
- * The hazard that comes with it, measured rather than assumed: ANY `src`
308
- * that does not resolve to a populated facet — a typo, a name not created
309
- * yet, not merely the obvious `''`/`'.'`/`'/'` — silently EMPTIES the
310
- * destination and reports success. Validation has to be positive on both
311
- * ends: the source exists and is populated before, the destination is
312
- * non-empty after. A blocklist of bad names would pass a typo straight
313
- * through and wipe a process's filesystem while returning ok.
314
- */
315
- readonly reflink: 'same-object' | 'impossible';
316
- /**
317
- * Bytes one process's whole module map may carry — the channel that does
318
- * work today, on both substrates, because the loader runs on whichever actor
319
- * hosts the facet. Enforced where the map is assembled, since the loader's
320
- * own refusal names no member.
321
- */
322
- readonly moduleCeilingBytes: number;
323
- /**
324
- * Whether the process's SQLite is spent out of the SESSION's storage budget
325
- * or its own. This cuts the opposite way from `reflink` and is why neither
326
- * substrate simply wins: a facet shares roughly 10 GiB with the session root
327
- * and every sibling and clone under it, with no copy-on-write credit — N
328
- * forks of an X-byte image need X*(N+1) — and crossing it does not raise an
329
- * error, it resets the object with "Internal error in Durable Object storage
330
- * caused object to be reset". A peer brings its own budget per host.
331
- */
332
- readonly storageSharedWithSession: boolean;
333
- }
334
- /**
335
- * The substrate a resident process runs on. One implementation per hosting
336
- * mechanism, one selection for the whole deployment — see
337
- * `loaders/process-host.ts`.
338
- */
339
- /**
340
- * A one-shot's module map: every member inline.
341
- *
342
- * Deliberately without {@link ResidentCodeSpec}'s by-path members. A resident
343
- * process names its large members by VFS path because the map has to reach
344
- * whichever actor ends up hosting it; a one-shot's is assembled and consumed
345
- * inside a single call, so a path buys nothing and a host that accepted one
346
- * would be promising a read it never performs.
347
- */
348
- export interface OneShotCodeSpec {
349
- compatibilityDate: string;
350
- compatibilityFlags: string[];
351
- mainModule: string;
352
- modules: Record<string, string | {
353
- wasm: ArrayBuffer;
354
- }>;
355
- }
356
- /**
357
- * Everything a host needs to run one program to completion.
358
- *
359
- * Separate from {@link ProcessHostParams} because the two differ in whether
360
- * anything survives the call, and every other difference follows from that: a
361
- * one-shot has no route target, no independent death to observe and no
362
- * residency to release. One spec carrying all of it would leave three members
363
- * meaningless for half its uses.
364
- */
365
- export interface OneShotParams {
366
- /** Supervisor-assigned pid — the identity the callback capability reports as. */
367
- pid: number;
368
- /**
369
- * Binds this run's VFS appends to this concrete incarnation. Supplied by the
370
- * caller rather than minted here so it can revoke the identity it authorised
371
- * instead of one it has to read back.
372
- */
373
- writerId: string;
374
- /**
375
- * The module map, assembled on demand.
376
- *
377
- * A thunk, and that is load-bearing rather than stylistic. The map is the
378
- * largest thing a session builds — pi's is ~23 MB — and it is dead the moment
379
- * the loader has taken it. Building it inside the load is what keeps it out
380
- * of the caller's frame, which would otherwise hold a second full copy of the
381
- * program for as long as the program runs.
382
- */
383
- code(): Promise<OneShotCodeSpec>;
384
- /** The invocation. Its body carries argv/env/cwd; its signal bounds the run. */
385
- request: Request;
386
- /**
387
- * Called before any capability able to write as `writerId` exists, and only
388
- * if this host can mint one at all. Granting append authority to an identity
389
- * nothing will ever present would leave a writer live with no writer.
390
- */
391
- onWriterActivated(writerId: string): void;
392
- /**
393
- * Called once the program is loaded and about to be entered.
394
- *
395
- * The boundary between paying for the isolate and paying for the program.
396
- * They are separate costs with separate fixes — a 12 s exec was once read as
397
- * a slow load and was a fresh isolate parsing a 23 MB map — and only the host
398
- * can see where one ends and the other begins.
399
- */
400
- onLoaded?(): void;
401
- }
402
- export interface ProcessHost {
403
- /** What this substrate can and cannot deliver, for operators and callers. */
404
- readonly imageDelivery: ProcessImageDelivery;
405
- /**
406
- * Run one program to completion and hand its response to `consume`.
407
- *
408
- * Scoped to the call rather than returned, because the isolate that produced
409
- * the response must outlive the reading of its body. A host that released its
410
- * stubs before the caller had read would sever a body still streaming, and
411
- * one that buffered instead would hold a second copy of every result — the
412
- * cost the thunk above exists to avoid. `consume` runs while the program's
413
- * resources are still held; they are released as it returns.
414
- */
415
- runOnce<T>(params: OneShotParams, consume: (response: Response) => Promise<T>): Promise<T>;
416
- open(params: ProcessHostParams): Promise<HostedProcess>;
417
- }
418
- /**
419
- * How a caller supplies the substrate a process manager will run programs on.
420
- *
421
- * A factory rather than a finished {@link ProcessHost}, because the substrate
422
- * needs the disk its processes boot from and only the manager can produce one:
423
- * that reader answers as the credential that WROTE the boot images and
424
- * deliberately uncached, since they are the largest files a session holds.
425
- * Demanding a finished host would make every caller reproduce that policy, and
426
- * a second copy of a credential rule is a second thing to keep in step.
427
- *
428
- * The parameters are exactly what a manager already holds, so the deployment's
429
- * own selector (`processHostFor`) satisfies this type as it stands — the
430
- * workerd substrate is named, not wrapped.
431
- */
432
- export type ProcessHostFactory = (ctx: DurableObjectState, env: unknown, disk: () => ResidentDiskReader) => ProcessHost;
433
- /**
434
- * Resource handle for one resident process — the whole surface the kernel
435
- * above this module sees: `booted()` for the boot payload, `done` for death,
436
- * `kill()` for teardown, `routeTarget` for inbound HTTP. Substrate-free: the
437
- * kernel cannot tell from it where the process is running, and never asks.
438
- *
439
- * `done` settles when the process ends: for a `lifetime` runner that is its
440
- * held-open startProcess settling (resolve on exit, reject on host death);
441
- * for a `boot` runner it is the kill that releases the host.
442
- *
443
- * The handle is disposable so FacetManager's existing per-pid resource
444
- * tracking tears a process down exactly the way it releases any other
445
- * per-process resource.
446
- */
447
- export declare class ResidentProcessHandle {
448
- #private;
449
- readonly done: Promise<void>;
450
- /**
451
- * Inbound-HTTP target for PortRegistry: the running facet's own stub. A
452
- * facet is a child actor, so its stub stays usable in request contexts long
453
- * after the one that created it — which is the whole reason a resident
454
- * process can serve a port at all.
455
- */
456
- readonly routeTarget: RouteableFacetTarget;
457
- constructor(init: {
458
- done: Promise<void>;
459
- booted: () => Promise<unknown>;
460
- routeTarget: RouteableFacetTarget;
461
- kill: () => void;
462
- describe: () => string;
463
- });
464
- /**
465
- * The runner's startProcess payload. The runner is started as part of the
466
- * spawn, so this is a handle on that one boot — awaiting it twice is safe
467
- * and never re-starts anything. For a `lifetime` runner it settles at exit.
468
- */
469
- booted(): Promise<unknown>;
470
- get killed(): boolean;
471
- /** Human-readable placement, for the NIMBUS_DEBUG process-log line. */
472
- describePlacement(): string;
473
- /** Idempotent: abort the facet and release its isolate. */
474
- kill(): void;
475
- }
476
- export interface ResidentProcessSpawn {
477
- /** Declared by the runner the primitive generates. */
478
- startContract: StartContract;
479
- /** Supervisor-assigned pid of the process entry on the coordinator. */
480
- pid: number;
481
- /** Keyed dynamic-worker identity (`nimbus-process:${doId}:${pid}`). */
482
- workerKey: string;
483
- /** What the facet boots from. */
484
- boot: ResidentBootSpec;
485
- /** Forwarded verbatim to the runner's startProcess. */
486
- startArgs?: unknown;
487
- /**
488
- * Called before any concrete host capability can expose this writer.
489
- * A spawn must not proceed unless the supervisor accepts the authority.
490
- */
491
- onWriterActivated: (writerId: string) => void;
492
- /** Called only after the concrete host resources for this writer are revoked. */
493
- onWriterRetired: (writerId: string) => void;
494
- }
495
- export declare class ProcessFabric {
496
- private readonly host;
497
- constructor(host: ProcessHost);
498
- /**
499
- * Boot a resident process on this deployment's substrate and return its
500
- * handle. Resolves once the process is up and its runner has been started;
501
- * rejects on boot failure.
502
- *
503
- * There is no decision in here. The substrate was chosen once, for the
504
- * deployment, and the only thing this method knows about it is the
505
- * `ProcessHost` interface.
506
- */
507
- startResidentProcess(spawn: ResidentProcessSpawn): Promise<ResidentProcessHandle>;
508
- }
509
- //# sourceMappingURL=process-fabric.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"process-fabric.d.ts","sourceRoot":"","sources":["../../src/loaders/process-fabric.ts"],"names":[],"mappings":"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"}