@mostra/runtime 0.0.0-stage → 0.2.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 (115) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +39 -2
  3. package/dist/bin.d.ts +1 -0
  4. package/dist/bin.js +236 -0
  5. package/dist/bin.js.map +1 -0
  6. package/dist/builder/child/main.d.ts +1 -0
  7. package/dist/builder/child/main.js +1408 -0
  8. package/dist/builder/child/main.js.map +1 -0
  9. package/dist/child-xrHmytks.js +49 -0
  10. package/dist/child-xrHmytks.js.map +1 -0
  11. package/dist/deps/child/install.d.ts +1 -0
  12. package/dist/deps/child/install.js +33 -0
  13. package/dist/deps/child/install.js.map +1 -0
  14. package/dist/index.d.ts +221 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +3 -0
  17. package/dist/instance-CzBkUyHu.js +15920 -0
  18. package/dist/instance-CzBkUyHu.js.map +1 -0
  19. package/dist/types-NjNy7gXX.js +57 -0
  20. package/dist/types-NjNy7gXX.js.map +1 -0
  21. package/package.json +87 -3
  22. package/src/actions/index.ts +622 -0
  23. package/src/addressing/index.ts +281 -0
  24. package/src/bin.ts +240 -0
  25. package/src/builder/child/dev.ts +383 -0
  26. package/src/builder/child/fields.ts +363 -0
  27. package/src/builder/child/main.ts +47 -0
  28. package/src/builder/child/plugins.ts +195 -0
  29. package/src/builder/child/scan.ts +459 -0
  30. package/src/builder/child/spa.ts +348 -0
  31. package/src/builder/coverage.ts +72 -0
  32. package/src/builder/index.ts +406 -0
  33. package/src/builder/types.ts +180 -0
  34. package/src/deps/child/install.ts +30 -0
  35. package/src/deps/index.ts +918 -0
  36. package/src/deps/installer.ts +321 -0
  37. package/src/deps/lock.ts +82 -0
  38. package/src/deps/scan.ts +266 -0
  39. package/src/deps/specifier.ts +64 -0
  40. package/src/deps/warm.ts +57 -0
  41. package/src/dev/index.ts +518 -0
  42. package/src/faults.ts +65 -0
  43. package/src/gate.ts +55 -0
  44. package/src/gateway/actions.ts +268 -0
  45. package/src/gateway/browser.ts +650 -0
  46. package/src/gateway/capabilities.ts +760 -0
  47. package/src/gateway/controls.ts +91 -0
  48. package/src/gateway/dev.ts +119 -0
  49. package/src/gateway/http.ts +229 -0
  50. package/src/gateway/identity.ts +101 -0
  51. package/src/gateway/index.ts +1299 -0
  52. package/src/gateway/integrity.ts +117 -0
  53. package/src/gateway/listener.ts +217 -0
  54. package/src/gateway/routes.ts +197 -0
  55. package/src/gateway/serve.ts +138 -0
  56. package/src/gc/index.ts +451 -0
  57. package/src/home/acquire.ts +276 -0
  58. package/src/home/index.ts +16 -0
  59. package/src/home/paths.ts +192 -0
  60. package/src/home/platform.ts +34 -0
  61. package/src/home/record.ts +76 -0
  62. package/src/home/settings.ts +113 -0
  63. package/src/index.ts +30 -0
  64. package/src/instance/index.ts +979 -0
  65. package/src/interaction/ephemeral.ts +300 -0
  66. package/src/interaction/events.ts +355 -0
  67. package/src/interaction/fields.ts +392 -0
  68. package/src/interaction/index.ts +1013 -0
  69. package/src/interaction/outbox.ts +493 -0
  70. package/src/interaction/policy.ts +26 -0
  71. package/src/interaction/results.ts +341 -0
  72. package/src/interaction/runs.ts +313 -0
  73. package/src/interaction/signals.ts +120 -0
  74. package/src/interaction/submissions.ts +585 -0
  75. package/src/interaction/subscriptions.ts +258 -0
  76. package/src/interaction/viewers.ts +187 -0
  77. package/src/interaction/wait.ts +201 -0
  78. package/src/ledger/index.ts +442 -0
  79. package/src/ledger/migrations.ts +596 -0
  80. package/src/ledger/requests.ts +105 -0
  81. package/src/ledger/types.ts +28 -0
  82. package/src/live/index.ts +573 -0
  83. package/src/log.ts +316 -0
  84. package/src/processes/child.ts +67 -0
  85. package/src/processes/environment.ts +64 -0
  86. package/src/processes/identity.ts +191 -0
  87. package/src/processes/index.ts +19 -0
  88. package/src/processes/manager.ts +543 -0
  89. package/src/protocol-server/client.ts +94 -0
  90. package/src/protocol-server/index.ts +91 -0
  91. package/src/protocol-server/server.ts +518 -0
  92. package/src/protocol-server/streams.ts +81 -0
  93. package/src/publish/checks.ts +92 -0
  94. package/src/publish/digest.ts +87 -0
  95. package/src/publish/index.ts +23 -0
  96. package/src/publish/manifest.ts +409 -0
  97. package/src/publish/methods.ts +96 -0
  98. package/src/publish/publisher.ts +913 -0
  99. package/src/publish/source.ts +272 -0
  100. package/src/publish/tar.ts +110 -0
  101. package/src/registry/index.ts +481 -0
  102. package/src/registry/store.ts +136 -0
  103. package/src/secrets/index.ts +223 -0
  104. package/src/service/idle.ts +64 -0
  105. package/src/service/index.ts +3 -0
  106. package/src/service/unit.ts +250 -0
  107. package/src/verify/fields.ts +125 -0
  108. package/src/verify/index.ts +913 -0
  109. package/src/verify/regression.ts +157 -0
  110. package/src/verify/runner.ts +230 -0
  111. package/src/verify/sandbox.ts +407 -0
  112. package/src/verify/typecheck.ts +371 -0
  113. package/src/workers/index.ts +17 -0
  114. package/src/workers/launcher.ts +260 -0
  115. package/src/workers/pool.ts +708 -0
@@ -0,0 +1,407 @@
1
+ /**
2
+ * A verify run's sandbox (D138 item 1): the real interaction, actions, live and gateway code over
3
+ * a scratch ledger in `cache/verify/runs/<run>/`, with its own worker pool and two short-lived
4
+ * loopback listeners on ports the operating system assigns, so a run never touches the home's
5
+ * drafts, state, events, hosts or deliveries, and the human-facing gateway never serves an
6
+ * unpublished build.
7
+ *
8
+ * - Pages are reached only with capability links minted in the scratch ledger, through the same
9
+ * session exchange and frame tickets as a viewer's (D97, D98). Documents get the verify target
10
+ * when served (`target: "verify"`), never in the build.
11
+ * - Server code runs in workers the gated process manager starts. A function that opted into
12
+ * `dryRun()` runs with it true; any other is refused before anything is recorded (D55).
13
+ * - `secret()` reads the real secrets, as the instance resolves them; nothing else of the home is
14
+ * reached. State starts empty, like a first view.
15
+ * - Closing stops everything and deletes the run's directory; {@link recoverSandboxes} removes
16
+ * what a stopped instance left.
17
+ */
18
+ import { randomBytes } from "node:crypto";
19
+ import { readFileSync } from "node:fs";
20
+ import { mkdir, readdir, rm } from "node:fs/promises";
21
+ import { join, relative } from "node:path";
22
+ import { type ArtifactManifest, type Results, RunId } from "@mostra/protocol";
23
+ import { createActions } from "../actions/index.ts";
24
+ import { createAddressing } from "../addressing/index.ts";
25
+ import {
26
+ coverageMatcher,
27
+ readFieldCoverage,
28
+ readLiveSources,
29
+ readServerFunctions,
30
+ } from "../builder/index.ts";
31
+ import { noFaults } from "../faults.ts";
32
+ import { Capabilities, createGateway, type DevUpstream } from "../gateway/index.ts";
33
+ import { createEphemeralBus, createInteraction } from "../interaction/index.ts";
34
+ import { openLedger } from "../ledger/index.ts";
35
+ import { createLive } from "../live/index.ts";
36
+ import type { Environment, Log, Redactor } from "../log.ts";
37
+ import type { ProcessManager } from "../processes/index.ts";
38
+ import { openRegistry } from "../registry/index.ts";
39
+ import type { Secrets } from "../secrets/index.ts";
40
+ import {
41
+ createWorkerPool,
42
+ localLauncher,
43
+ type WorkerVersion,
44
+ workerLimits,
45
+ } from "../workers/index.ts";
46
+
47
+ /** One version the sandbox serves. */
48
+ export interface SandboxVersion {
49
+ readonly versionId: string;
50
+ /** Its directory: a verify build in `cache/builds/` or a published version in `versions/`. */
51
+ readonly dir: string;
52
+ readonly manifest: ArtifactManifest;
53
+ readonly sourceDigest: string;
54
+ readonly envDigest: string;
55
+ readonly outputDigest: string;
56
+ }
57
+
58
+ /** What the sandbox needs of its instance. */
59
+ export interface SandboxOptions {
60
+ /** The home's real path. */
61
+ readonly home: string;
62
+ readonly log: Log;
63
+ readonly redactor: Redactor;
64
+ readonly processes: ProcessManager;
65
+ readonly runtimeVersion: string;
66
+ /** The worker's entry and Node arguments (`locateWorker`). */
67
+ readonly worker: { readonly entry: string; readonly nodeArgs: readonly string[] };
68
+ /** A version's packages for its server code (`Dependencies.runtimeModules`, D135). */
69
+ readonly modules: (target: {
70
+ readonly artifactId: string;
71
+ readonly versionDir: string;
72
+ readonly sourceDir?: string;
73
+ }) => Promise<string>;
74
+ /** The real secrets, read-only from server code (D138 item 1). */
75
+ readonly secrets: Secrets;
76
+ /** The artifact allowlist environment every worker gets (D95). */
77
+ readonly env: Environment;
78
+ /** The shell's built files. */
79
+ readonly shellDir: string | undefined;
80
+ readonly revisions: readonly string[];
81
+ /** The render mode's server bundle of a version directory (D19 seam 5). */
82
+ readonly serverEntry: (dir: string) => string | undefined;
83
+ /** What is wrong with a version directory's files, or `undefined`. */
84
+ readonly damage: (dir: string) => Promise<string | undefined>;
85
+ }
86
+
87
+ /** A running sandbox. */
88
+ export interface Sandbox {
89
+ /** A fresh capability link to a version the sandbox serves: one per render, like a viewer's. */
90
+ link(versionId: string): string;
91
+ /** The shell's origin, for the health check. */
92
+ readonly shellOrigin: string;
93
+ /** The server functions it refused, in order (D55). */
94
+ readonly skipped: ReadonlySet<string>;
95
+ /** The live sources whose producers failed, with their messages. */
96
+ liveFailures(): { readonly key: string; readonly message: string; readonly code?: string }[];
97
+ /**
98
+ * The workers that crashed, couldn't start, ran out of memory or hung, by version: a definite
99
+ * failure of server code even when the page handled the failed call (Opus review finding 4).
100
+ */
101
+ crashes(): readonly {
102
+ readonly versionId: string;
103
+ readonly kind: string;
104
+ readonly cause: string;
105
+ }[];
106
+ /**
107
+ * `mostra dev` only (D140 item 12): the candidate's server bundle changed in place; its worker
108
+ * stops so the next call loads the new bundle.
109
+ */
110
+ replaceServer(): Promise<void>;
111
+ /** Hears every submission made in the sandbox, with its Results (D140 item 12). */
112
+ onSubmission(listener: (results: Results) => void): () => void;
113
+ /** Stops everything and deletes the run's directory. */
114
+ close(): Promise<void>;
115
+ }
116
+
117
+ /** The directory every run's sandbox lives in. */
118
+ export const sandboxRoot = (home: string): string => join(home, "cache", "verify", "runs");
119
+
120
+ /** Removes the sandboxes a stopped instance left (D138 item 1); call it before any run starts. */
121
+ export async function recoverSandboxes(home: string, log: Log): Promise<void> {
122
+ const root = sandboxRoot(home);
123
+ let left: string[];
124
+ try {
125
+ left = await readdir(root);
126
+ } catch {
127
+ return;
128
+ }
129
+ for (const name of left) await rm(join(root, name), { recursive: true, force: true });
130
+ if (left.length > 0) log.info("verify.sandboxes_removed", { count: left.length });
131
+ }
132
+
133
+ /** The server functions of a version that check `dryRun()` (`registry.json`, D55). */
134
+ export function dryRunFunctions(dir: string): ReadonlySet<string> {
135
+ try {
136
+ const registry = JSON.parse(readFileSync(join(dir, "registry.json"), "utf8")) as {
137
+ readonly actions?: readonly { readonly id?: unknown; readonly dryRun?: unknown }[];
138
+ };
139
+ return new Set(
140
+ (registry.actions ?? [])
141
+ .filter((entry) => entry.dryRun === true && typeof entry.id === "string")
142
+ .map((entry) => entry.id as string),
143
+ );
144
+ } catch {
145
+ return new Set();
146
+ }
147
+ }
148
+
149
+ /**
150
+ * Starts a sandbox serving `versions` of `artifactId` (the baseline first, if any, then the
151
+ * candidate), whose server code runs from `sourceDir` when it exists.
152
+ */
153
+ export async function startSandbox(
154
+ options: SandboxOptions,
155
+ input: {
156
+ readonly artifactId: string;
157
+ readonly versions: readonly SandboxVersion[];
158
+ readonly sourceDir?: string;
159
+ /** The run's directory; default a new one in {@link sandboxRoot}. */
160
+ readonly runDir?: string;
161
+ /**
162
+ * A `mostra dev` session's sandbox (D140 item 12) instead of a verify run's: the artifact
163
+ * origin serves the session's Vite server (`upstream`), pages run as live pages, and actions
164
+ * run for real with the real secrets. Nothing is delivered to hosts or ports either way.
165
+ */
166
+ readonly dev?: { readonly upstream: () => DevUpstream | undefined };
167
+ /** The shell's port, instead of one the operating system assigns (`mostra dev --port`). */
168
+ readonly shellPort?: number;
169
+ },
170
+ ): Promise<Sandbox> {
171
+ const { log } = options;
172
+ const runDir = input.runDir ?? join(sandboxRoot(options.home), RunId.create());
173
+ await mkdir(runDir, { recursive: true, mode: 0o700 });
174
+ const opening = openLedger({
175
+ storeDir: join(runDir, "store"),
176
+ runtimeVersion: options.runtimeVersion,
177
+ owner: { pid: process.pid, startTime: `verify-${Date.now()}` },
178
+ log,
179
+ });
180
+ if (!opening.ok) throw new Error("A verify sandbox's scratch ledger was locked.");
181
+ const ledger = opening.ledger;
182
+ // Stops run last-pushed first: everything else, then the ledger, then the directory, so the
183
+ // scratch ledger closes (and checkpoints) before its files are removed.
184
+ const stops: (() => Promise<void> | void)[] = [
185
+ () => rm(runDir, { recursive: true, force: true }),
186
+ () => ledger.close(),
187
+ ];
188
+ const close = async (): Promise<void> => {
189
+ for (const stop of stops.splice(0).reverse()) {
190
+ try {
191
+ await stop();
192
+ } catch (error) {
193
+ log.warn("verify.sandbox_stop_failed", { error });
194
+ }
195
+ }
196
+ };
197
+ try {
198
+ const registry = await openRegistry({ home: runDir, ledger });
199
+ const dirs = new Map<string, string>();
200
+ const numbers = new Map<string, number>();
201
+ for (const version of input.versions) {
202
+ dirs.set(version.versionId, version.dir);
203
+ const committed = registry.commit({
204
+ artifactId: input.artifactId,
205
+ bindingPath: `verify:${input.artifactId}`,
206
+ manifestId: undefined,
207
+ versionId: version.versionId,
208
+ sourceDigest: version.sourceDigest,
209
+ envDigest: version.envDigest,
210
+ outputDigest: version.outputDigest,
211
+ manifest: version.manifest,
212
+ policy: undefined,
213
+ forcedCodes: [],
214
+ stillClaims: () => false,
215
+ });
216
+ numbers.set(version.versionId, committed.version);
217
+ }
218
+ const dirOf = (versionId: string): string => {
219
+ const dir = dirs.get(versionId);
220
+ if (!dir) throw new Error(`The verify sandbox serves no version ${versionId}.`);
221
+ return dir;
222
+ };
223
+ const candidate = input.versions.at(-1);
224
+ if (!candidate) throw new Error("A verify sandbox needs a version.");
225
+
226
+ const addressing = createAddressing({
227
+ ledger,
228
+ log,
229
+ bind: { address: "127.0.0.1" },
230
+ ephemeral: true,
231
+ ...(input.shellPort !== undefined ? { shellPort: input.shellPort } : {}),
232
+ });
233
+ const capabilities = new Capabilities({
234
+ ledger,
235
+ log,
236
+ key: randomBytes(32),
237
+ now: () => Date.now(),
238
+ shellOrigin: () => gateway.shellOrigin(),
239
+ });
240
+ const interaction = createInteraction({
241
+ ledger,
242
+ log,
243
+ faults: noFaults,
244
+ // No host is reached from a sandbox: nothing is delivered, mirrored or asked (D138 item 1).
245
+ hosts: {
246
+ registrants: () => [],
247
+ call: () => Promise.reject(new Error("A verify sandbox calls no host.")),
248
+ notify: () => false,
249
+ drained: () => undefined,
250
+ },
251
+ expectedHosts: () => [],
252
+ artifacts: { resolve: (ref) => registry.get(ref).id },
253
+ coverage: (versionId) => coverageMatcher(readFieldCoverage(dirOf(versionId))),
254
+ });
255
+ stops.push(() => interaction.stop());
256
+ const bus = createEphemeralBus();
257
+ stops.push(() => bus.close());
258
+
259
+ const optIns = new Map<string, ReadonlySet<string>>();
260
+ const skipped = new Set<string>();
261
+ const crashes: { versionId: string; kind: string; cause: string }[] = [];
262
+ const workerVersion = (versionId: string): WorkerVersion | undefined => {
263
+ const dir = dirs.get(versionId);
264
+ const version = input.versions.find((entry) => entry.versionId === versionId);
265
+ const served = dir ? options.serverEntry(dir) : undefined;
266
+ if (!dir || !version || served === undefined) return undefined;
267
+ return {
268
+ artifactId: input.artifactId,
269
+ ref: {
270
+ versionId,
271
+ outputDigest: version.outputDigest,
272
+ locator: `home:${relative(options.home, dir)}`,
273
+ },
274
+ entry: relative(dir, served),
275
+ limits: workerLimits(version.manifest),
276
+ functions: readServerFunctions(dir),
277
+ ...(input.sourceDir ? { sourceDir: input.sourceDir } : {}),
278
+ };
279
+ };
280
+ const pool = createWorkerPool({
281
+ launcher: localLauncher({
282
+ processes: options.processes,
283
+ home: options.home,
284
+ workerEntry: options.worker.entry,
285
+ nodeArgs: options.worker.nodeArgs,
286
+ modules: options.modules,
287
+ }),
288
+ log,
289
+ env: options.env,
290
+ bridge: {
291
+ request: (worker, method, params, call) =>
292
+ actions.bridge.request(worker, method, params, call),
293
+ log: (worker, line) => actions.bridge.log(worker, line),
294
+ liveValue: (worker, params) => live.produced(worker, params),
295
+ },
296
+ onCrash: (crash) => {
297
+ if (crashes.length < 20)
298
+ crashes.push({ versionId: crash.versionId, kind: crash.kind, cause: crash.cause });
299
+ actions.crashed(crash);
300
+ live.crashed(crash);
301
+ interaction.workerCrashed(crash);
302
+ },
303
+ });
304
+ stops.push(() => pool.stopAll());
305
+ const actions = createActions({
306
+ interaction,
307
+ pool,
308
+ bus,
309
+ secrets: options.secrets,
310
+ redactor: options.redactor,
311
+ log,
312
+ version: workerVersion,
313
+ // In dev, the developer's own code runs for real on their own machine, as any dev server's
314
+ // does (D140 item 12); in verify, only what opted into dryRun() runs (D55).
315
+ ...(input.dev
316
+ ? {}
317
+ : {
318
+ dryRun: {
319
+ optedIn: (versionId: string, fnId: string) => {
320
+ let opted = optIns.get(versionId);
321
+ if (!opted) {
322
+ opted = dryRunFunctions(dirOf(versionId));
323
+ optIns.set(versionId, opted);
324
+ }
325
+ return opted.has(fnId);
326
+ },
327
+ skipped: (fnId: string) => {
328
+ skipped.add(fnId);
329
+ },
330
+ },
331
+ }),
332
+ });
333
+ // A dev session's server code builds again, and its sources with it (D140 item 12).
334
+ let sources = readLiveSources(candidate.dir);
335
+ const live = createLive({
336
+ ledger,
337
+ log,
338
+ bus,
339
+ pool,
340
+ interaction,
341
+ // Every render of the run reads the candidate's producers, so the baseline and the
342
+ // candidate show the same data (D138 item 4).
343
+ latest: (artifactId) =>
344
+ artifactId === input.artifactId && sources.length > 0
345
+ ? { versionId: candidate.versionId, sources }
346
+ : undefined,
347
+ artifactsWithLive: () => (sources.length > 0 ? [input.artifactId] : []),
348
+ version: workerVersion,
349
+ redactor: options.redactor,
350
+ });
351
+ stops.push(() => live.stop());
352
+
353
+ const gateway = createGateway({
354
+ ledger,
355
+ log,
356
+ addressing,
357
+ capabilities,
358
+ artifacts: {
359
+ get: (ref) => registry.get(ref),
360
+ versionDir: dirOf,
361
+ damage: (versionId) => options.damage(dirOf(versionId)),
362
+ },
363
+ shellDir: options.shellDir,
364
+ interaction,
365
+ // Both channels, every control: the page behaves as it would for a viewer of the standalone
366
+ // host, and the artifact's own Submit is exercised in the sandbox.
367
+ controls: async () => ({ submitChannels: ["shell", "artifact"] }),
368
+ activated: () => undefined,
369
+ revisions: options.revisions,
370
+ actions,
371
+ live,
372
+ bus,
373
+ parked: () => false,
374
+ ...(input.dev ? { target: "live" as const, dev: input.dev } : { target: "verify" as const }),
375
+ });
376
+ await gateway.start();
377
+ stops.push(() => gateway.close());
378
+
379
+ return {
380
+ shellOrigin: gateway.shellOrigin(),
381
+ link: (versionId) =>
382
+ gateway.link({
383
+ artifactId: input.artifactId,
384
+ version: numbers.get(versionId) as number,
385
+ }),
386
+ skipped,
387
+ crashes: () => [...crashes],
388
+ replaceServer: async () => {
389
+ const version = workerVersion(candidate.versionId);
390
+ if (version) await pool.replace(version);
391
+ sources = readLiveSources(candidate.dir);
392
+ live.replaced(candidate.versionId);
393
+ },
394
+ onSubmission: (listener) => interaction.onSubmission(listener),
395
+ liveFailures: () =>
396
+ live.failures(input.artifactId).map(({ key, error }) => ({
397
+ key,
398
+ message: error.message,
399
+ ...(error.code !== undefined ? { code: error.code } : {}),
400
+ })),
401
+ close,
402
+ };
403
+ } catch (error) {
404
+ await close();
405
+ throw error;
406
+ }
407
+ }