@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
package/src/faults.ts ADDED
@@ -0,0 +1,65 @@
1
+ /**
2
+ * Fault injection for tests (FAILURE_MODEL §3, VR-02, issue #7). A test that runs real Mostra
3
+ * processes sets `MOSTRA_TEST_FAULTS` to a comma-separated list of `<point>:<action>` entries, and
4
+ * the instance stops at those points: `throw` fails the operation there, `crash` kills the
5
+ * supervisor with SIGKILL there, as a power cut or `kill -9` would, and `hang` makes the child the
6
+ * point names hang (the module asks {@link Faults.hangs}; a builder told never to answer, so a test
7
+ * of the build limit never races a fast build, issue #18). Without the variable every point
8
+ * is a no-op. The points are named in the modules that call {@link Faults.at}.
9
+ *
10
+ * ```ts
11
+ * faults.at("publish:after-promote"); // a crash here leaves a version directory with no row
12
+ * ```
13
+ */
14
+ import type { Environment } from "./log.ts";
15
+
16
+ /** What a fault point does. */
17
+ export type FaultAction = "throw" | "crash" | "hang";
18
+
19
+ /** The test fault points of one instance. */
20
+ export interface Faults {
21
+ /** Runs the fault configured for `point`, if any (`hang` is the caller's to act on). */
22
+ at(point: string): void;
23
+ /** Whether `point` is configured to `hang`. */
24
+ hangs(point: string): boolean;
25
+ }
26
+
27
+ /** The variable tests set. It carries no secrets and changes nothing when unset. */
28
+ export const FAULTS_VARIABLE = "MOSTRA_TEST_FAULTS";
29
+
30
+ /** No faults: every point is a no-op. */
31
+ export const noFaults: Faults = { at() {}, hangs: () => false };
32
+
33
+ /** The error a `throw` fault raises. */
34
+ export class InjectedFault extends Error {
35
+ constructor(point: string) {
36
+ super(`Injected fault at ${point} (${FAULTS_VARIABLE}).`);
37
+ this.name = "InjectedFault";
38
+ }
39
+ }
40
+
41
+ /** Reads the faults configured in `env`. Unknown actions are ignored. */
42
+ export function faultsFrom(env: Environment): Faults {
43
+ const spec = env[FAULTS_VARIABLE];
44
+ if (!spec) return noFaults;
45
+ const configured = new Map<string, FaultAction>();
46
+ for (const entry of spec.split(",")) {
47
+ const separator = entry.lastIndexOf(":");
48
+ const point = entry.slice(0, separator).trim();
49
+ const action = entry.slice(separator + 1).trim();
50
+ if (point && (action === "throw" || action === "crash" || action === "hang"))
51
+ configured.set(point, action);
52
+ }
53
+ return {
54
+ hangs: (point) => configured.get(point) === "hang",
55
+ at(point) {
56
+ const action = configured.get(point);
57
+ if (action === "throw") throw new InjectedFault(point);
58
+ if (action === "crash") {
59
+ process.kill(process.pid, "SIGKILL");
60
+ // The signal is delivered at once; block until it lands so no later step runs.
61
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10_000);
62
+ }
63
+ },
64
+ };
65
+ }
package/src/gate.ts ADDED
@@ -0,0 +1,55 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+
3
+ /**
4
+ * One gate per instance between `gc` and the work whose files it would remove (D140 item 14):
5
+ * publishes, verify runs, dependency additions and layout installs hold it shared, so they run
6
+ * side by side as before; a gc run holds it alone. Writers are preferred: once a gc waits, new
7
+ * shared work waits behind it, so a busy home can't keep gc out forever. Shared work started
8
+ * inside shared work (a verify run starting a worker whose layout installs) joins its caller's
9
+ * hold rather than waiting, so a waiting gc never deadlocks it.
10
+ */
11
+ export class Gate {
12
+ readonly #holding = new AsyncLocalStorage<true>();
13
+ #shared = 0;
14
+ #exclusive = false;
15
+ #waitingExclusive = 0;
16
+ readonly #wakers: (() => void)[] = [];
17
+
18
+ /** Runs `fn` beside other shared work, never during a gc run. */
19
+ async shared<T>(fn: () => Promise<T>): Promise<T> {
20
+ if (this.#holding.getStore() === true) return fn();
21
+ while (this.#exclusive || this.#waitingExclusive > 0) await this.#wait();
22
+ this.#shared += 1;
23
+ try {
24
+ return await this.#holding.run(true, fn);
25
+ } finally {
26
+ this.#shared -= 1;
27
+ this.#wake();
28
+ }
29
+ }
30
+
31
+ /** Runs `fn` alone: after shared work in flight ends, and before any that arrives meanwhile. */
32
+ async exclusive<T>(fn: () => Promise<T>): Promise<T> {
33
+ this.#waitingExclusive += 1;
34
+ try {
35
+ while (this.#exclusive || this.#shared > 0) await this.#wait();
36
+ } finally {
37
+ this.#waitingExclusive -= 1;
38
+ }
39
+ this.#exclusive = true;
40
+ try {
41
+ return await this.#holding.run(true, fn);
42
+ } finally {
43
+ this.#exclusive = false;
44
+ this.#wake();
45
+ }
46
+ }
47
+
48
+ #wait(): Promise<void> {
49
+ return new Promise((resolve) => this.#wakers.push(resolve));
50
+ }
51
+
52
+ #wake(): void {
53
+ for (const wake of this.#wakers.splice(0)) wake();
54
+ }
55
+ }
@@ -0,0 +1,268 @@
1
+ /**
2
+ * The browser protocol's action and live routes (INTERFACES §4, WP-08): `call/{fnId}` (a plain
3
+ * server-function call, its result streamed as NDJSON), `runs` (start or join a durable run),
4
+ * `runs/attach` (read runs and follow them), `runs/{id}/cancel`, and `live` (read live sources
5
+ * and keep them produced). They run behind the route table's checks (session, CSRF, Origin, scope;
6
+ * D96, D97 item 4), and each function a request names is checked against the link's
7
+ * `action:<name>` scopes. Mostra's cookies never reach a worker: only the call's arguments and its
8
+ * context (viewer, view, run) do (D38).
9
+ */
10
+ import {
11
+ CallRequest,
12
+ type CapabilityScope,
13
+ type Diagnostic,
14
+ LiveRequest,
15
+ RpcError,
16
+ RunAttachRequest,
17
+ RunCancelRequest,
18
+ RunRequest,
19
+ refusal,
20
+ scopeAllows,
21
+ } from "@mostra/protocol";
22
+ import type * as z from "zod";
23
+ import type { Actions } from "../actions/index.ts";
24
+ import type { Interaction, PageIdentity } from "../interaction/index.ts";
25
+ import type { Live } from "../live/index.ts";
26
+ import type { Log } from "../log.ts";
27
+ import { BASE_HEADERS, isRefusal, jsonResponse, readJsonObject } from "./http.ts";
28
+ import type { RouteContext } from "./routes.ts";
29
+
30
+ /** The largest request body: 16 MiB of arguments and the envelope. */
31
+ const ACTION_BODY_MAX: number = 17 * 1024 * 1024;
32
+
33
+ /** The HTTP status of each diagnostic these routes answer. */
34
+ const STATUS: Readonly<Record<string, number>> = {
35
+ MOSTRA_HOST_INVALID_PARAMS: 400,
36
+ MOSTRA_ACTION_UNKNOWN_FUNCTION: 404,
37
+ MOSTRA_ACTION_RUN_NOT_FOUND: 404,
38
+ MOSTRA_ACTION_TOO_LARGE: 413,
39
+ MOSTRA_ACTION_UNSERIALIZABLE: 400,
40
+ MOSTRA_SUBMIT_VIEW_INVALID: 403,
41
+ MOSTRA_HYGIENE_SCOPE_DENIED: 403,
42
+ MOSTRA_RUNTIME_WORKER_PARKED: 503,
43
+ MOSTRA_RUNTIME_WORKER_CRASHED: 503,
44
+ // A verify run's sandbox refuses an action that didn't opt into `dryRun()` (D55, D138).
45
+ MOSTRA_VERIFY_ACTION_SKIPPED: 409,
46
+ MOSTRA_HOME_DISK_FULL: 507,
47
+ MOSTRA_HOME_GONE: 503,
48
+ };
49
+
50
+ type Handler = (context: RouteContext) => Response | Promise<Response>;
51
+
52
+ /** The handlers. */
53
+ export interface ActionRoutes {
54
+ readonly call: Handler;
55
+ readonly runs: Handler;
56
+ readonly attach: Handler;
57
+ readonly cancel: Handler;
58
+ readonly live: Handler;
59
+ }
60
+
61
+ /** Options for {@link actionRoutes}. */
62
+ export interface ActionRoutesOptions {
63
+ readonly interaction: Interaction;
64
+ readonly actions: Actions;
65
+ readonly live: Live;
66
+ readonly log: Log;
67
+ /** The browser-protocol revisions served. */
68
+ readonly revisions: readonly string[];
69
+ }
70
+
71
+ function answer(diagnostic: Diagnostic, status: number): Response {
72
+ return jsonResponse({ ...diagnostic }, { status });
73
+ }
74
+
75
+ function failure(error: unknown): Response {
76
+ if (error instanceof RpcError)
77
+ return answer(error.diagnostic, STATUS[error.diagnostic.code] ?? 500);
78
+ throw error;
79
+ }
80
+
81
+ function denied(fnId: string): Response {
82
+ return answer(
83
+ refusal(
84
+ "MOSTRA_HYGIENE_SCOPE_DENIED",
85
+ `This link may not run the server function ${fnId.slice(0, 200)}.`,
86
+ 403,
87
+ ).diagnostic,
88
+ 403,
89
+ );
90
+ }
91
+
92
+ async function body<T>(context: RouteContext, schema: z.ZodType<T>): Promise<T | Response> {
93
+ const raw = await readJsonObject(context.request, ACTION_BODY_MAX);
94
+ if (isRefusal(raw)) return answer(raw.diagnostic, raw.status);
95
+ const parsed = schema.safeParse(raw);
96
+ if (parsed.success) return parsed.data;
97
+ const [issue] = parsed.error.issues;
98
+ return answer(
99
+ refusal(
100
+ "MOSTRA_HYGIENE_REQUEST_MALFORMED",
101
+ `The request body doesn't match the browser protocol at ${issue?.path.join(".") || "(root)"}: ${issue?.message ?? "invalid"}.`,
102
+ ).diagnostic,
103
+ 400,
104
+ );
105
+ }
106
+
107
+ /** The routes' handlers. */
108
+ export function actionRoutes(options: ActionRoutesOptions): ActionRoutes {
109
+ const { interaction, actions, live, log } = options;
110
+
111
+ const served = (context: RouteContext): Response | undefined => {
112
+ const rev = context.params["rev"];
113
+ if (rev !== undefined && options.revisions.includes(rev)) return undefined;
114
+ return answer(
115
+ refusal(
116
+ "MOSTRA_HYGIENE_NOT_SERVED",
117
+ `This gateway serves browser-protocol revisions ${options.revisions.join(", ")}, not ${String(rev)}.`,
118
+ 404,
119
+ ).diagnostic,
120
+ 404,
121
+ );
122
+ };
123
+
124
+ const pageOf = (context: RouteContext): PageIdentity => {
125
+ const session = context.session;
126
+ const artifactId = context.artifactId;
127
+ if (!session || artifactId === undefined) throw new Error("session route without a session");
128
+ return {
129
+ artifactId,
130
+ viewerId: interaction.viewerOf(session.viewerId),
131
+ tokenId: session.grant.tokenId,
132
+ scopes: session.grant.scopes,
133
+ };
134
+ };
135
+
136
+ const may = (page: PageIdentity, fnId: string): boolean =>
137
+ scopeAllows(page.scopes ?? [], `action:${fnId}` as CapabilityScope);
138
+
139
+ return {
140
+ async call(context) {
141
+ const refused = served(context);
142
+ if (refused) return refused;
143
+ const fnId = context.params["fn"] ?? "";
144
+ const request = await body(context, CallRequest);
145
+ if (request instanceof Response) return request;
146
+ const page = pageOf(context);
147
+ // The route checked `action:<fnId>` already (D97 item 4); this keeps the rule in one place.
148
+ if (!may(page, fnId)) return denied(fnId);
149
+ let lines: AsyncIterable<unknown>;
150
+ const abort = new AbortController();
151
+ context.request.signal.addEventListener("abort", () => abort.abort(), { once: true });
152
+ try {
153
+ lines = await actions.call(
154
+ page,
155
+ { viewId: request.viewId, fnId, args: request.args },
156
+ abort.signal,
157
+ );
158
+ } catch (error) {
159
+ return failure(error);
160
+ }
161
+ const encoder = new TextEncoder();
162
+ const iterator = lines[Symbol.asyncIterator]();
163
+ const stream = new ReadableStream<Uint8Array>(
164
+ {
165
+ async pull(controller) {
166
+ try {
167
+ const next = await iterator.next();
168
+ if (next.done) {
169
+ controller.close();
170
+ return;
171
+ }
172
+ controller.enqueue(encoder.encode(`${JSON.stringify(next.value)}\n`));
173
+ } catch (error) {
174
+ log.error("gateway.call_failed", { error });
175
+ controller.error(error);
176
+ }
177
+ },
178
+ cancel() {
179
+ abort.abort();
180
+ void iterator.return?.();
181
+ },
182
+ },
183
+ new CountQueuingStrategy({ highWaterMark: 1 }),
184
+ );
185
+ return new Response(stream, {
186
+ headers: {
187
+ ...BASE_HEADERS,
188
+ "content-type": "application/x-ndjson; charset=utf-8",
189
+ "cache-control": "no-store",
190
+ "x-accel-buffering": "no",
191
+ },
192
+ });
193
+ },
194
+
195
+ async runs(context) {
196
+ const refused = served(context);
197
+ if (refused) return refused;
198
+ const request = await body(context, RunRequest);
199
+ if (request instanceof Response) return request;
200
+ const page = pageOf(context);
201
+ if (!may(page, request.fnId)) return denied(request.fnId);
202
+ try {
203
+ return jsonResponse(
204
+ actions.startRun(page, {
205
+ viewId: request.viewId,
206
+ fnId: request.fnId,
207
+ args: request.args,
208
+ ...(request.key !== undefined ? { key: request.key } : {}),
209
+ clientKey: request.clientKey,
210
+ }),
211
+ );
212
+ } catch (error) {
213
+ return failure(error);
214
+ }
215
+ },
216
+
217
+ async attach(context) {
218
+ const refused = served(context);
219
+ if (refused) return refused;
220
+ const request = await body(context, RunAttachRequest);
221
+ if (request instanceof Response) return request;
222
+ const page = pageOf(context);
223
+ for (const entry of request.keyed ?? [])
224
+ if (!may(page, entry.fnId)) return denied(entry.fnId);
225
+ try {
226
+ const runs = actions
227
+ .attach(page, {
228
+ viewId: request.viewId,
229
+ ...(request.runIds ? { runIds: request.runIds } : {}),
230
+ ...(request.keyed ? { keyed: request.keyed } : {}),
231
+ })
232
+ // A link sees only the runs of functions it may run.
233
+ .filter((run) => may(page, run.fnId));
234
+ return jsonResponse({ runs });
235
+ } catch (error) {
236
+ return failure(error);
237
+ }
238
+ },
239
+
240
+ async cancel(context) {
241
+ const refused = served(context);
242
+ if (refused) return refused;
243
+ const request = await body(context, RunCancelRequest);
244
+ if (request instanceof Response) return request;
245
+ const page = pageOf(context);
246
+ const runId = context.params["run"] ?? "";
247
+ try {
248
+ const row = interaction.runFor(page, request.viewId, runId);
249
+ if (!may(page, row.action)) return denied(row.action);
250
+ return jsonResponse(actions.cancel(page, request.viewId, runId));
251
+ } catch (error) {
252
+ return failure(error);
253
+ }
254
+ },
255
+
256
+ async live(context) {
257
+ const refused = served(context);
258
+ if (refused) return refused;
259
+ const request = await body(context, LiveRequest);
260
+ if (request instanceof Response) return request;
261
+ try {
262
+ return jsonResponse({ sources: live.read(pageOf(context), request) });
263
+ } catch (error) {
264
+ return failure(error);
265
+ }
266
+ },
267
+ };
268
+ }