@mostra/runtime 0.8.0 → 0.10.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 (65) hide show
  1. package/dist/bin.js +2879 -8
  2. package/dist/bin.js.map +1 -1
  3. package/dist/builder/child/main.js +2 -2
  4. package/dist/{child-Chiavhdx.js → child-BmNZ4a70.js} +2 -2
  5. package/dist/{child-Chiavhdx.js.map → child-BmNZ4a70.js.map} +1 -1
  6. package/dist/deps/child/install.js +1 -1
  7. package/dist/{directories-mJ1qlVht.js → directories-BLJjeSPD.js} +5 -5
  8. package/dist/directories-BLJjeSPD.js.map +1 -0
  9. package/dist/{files-FygSJIzK.js → files-DGeWuE4I.js} +2 -2
  10. package/dist/{files-FygSJIzK.js.map → files-DGeWuE4I.js.map} +1 -1
  11. package/dist/index.d.ts +2 -0
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +2 -2
  14. package/dist/{instance-BRfg27Rg.js → instance-FExcyENK.js} +3346 -395
  15. package/dist/instance-FExcyENK.js.map +1 -0
  16. package/package.json +7 -5
  17. package/src/actions/index.ts +163 -10
  18. package/src/bin.ts +78 -1
  19. package/src/gateway/actions.ts +20 -4
  20. package/src/gateway/browser.ts +118 -95
  21. package/src/gateway/capabilities.ts +15 -6
  22. package/src/gateway/index.ts +112 -15
  23. package/src/gateway/routes.ts +15 -7
  24. package/src/gc/index.ts +14 -0
  25. package/src/instance/index.ts +41 -2
  26. package/src/interaction/ephemeral.ts +32 -23
  27. package/src/interaction/events.ts +21 -1
  28. package/src/interaction/imports.ts +317 -0
  29. package/src/interaction/index.ts +172 -19
  30. package/src/interaction/outbox.ts +9 -0
  31. package/src/interaction/results.ts +22 -1
  32. package/src/interaction/runs.ts +52 -2
  33. package/src/interaction/submissions.ts +17 -1
  34. package/src/interaction/tally.ts +129 -0
  35. package/src/ledger/index.ts +104 -9
  36. package/src/ledger/migrations.ts +183 -0
  37. package/src/ledger/types.ts +8 -0
  38. package/src/link/binding.ts +289 -0
  39. package/src/link/hosted.ts +65 -0
  40. package/src/link/http.ts +136 -0
  41. package/src/link/index.ts +8 -0
  42. package/src/link/manager.ts +1385 -0
  43. package/src/link/relay.ts +512 -0
  44. package/src/live/index.ts +112 -2
  45. package/src/platform/filesystems.ts +78 -0
  46. package/src/platform/index.ts +1 -0
  47. package/src/protocol-server/index.ts +18 -1
  48. package/src/protocol-server/server.ts +38 -7
  49. package/src/protocol-server/websocket.ts +161 -0
  50. package/src/publish/bundle.ts +398 -0
  51. package/src/publish/manifest.ts +9 -0
  52. package/src/publish/methods.ts +12 -1
  53. package/src/publish/publisher.ts +127 -0
  54. package/src/registry/index.ts +35 -14
  55. package/src/server/api.ts +439 -0
  56. package/src/server/auth.ts +613 -0
  57. package/src/server/config.ts +221 -0
  58. package/src/server/data.ts +369 -0
  59. package/src/server/directory.ts +141 -0
  60. package/src/server/hosted.ts +822 -0
  61. package/src/server/index.ts +368 -0
  62. package/src/server/relay.ts +1163 -0
  63. package/src/share/index.ts +110 -6
  64. package/dist/directories-mJ1qlVht.js.map +0 -1
  65. package/dist/instance-BRfg27Rg.js.map +0 -1
@@ -0,0 +1,822 @@
1
+ /**
2
+ * A hosted home (ARCHITECTURE §15.2, DATA_MODEL §7.2, D165): a Mostra home on a remote server with
3
+ * the same ledger, registry, interaction core and events as a local one, and no sources, builds,
4
+ * verify, workers, dependency store or secrets. Its versions arrive from the owner instance
5
+ * (`hosted/push`): the client files the listing names, checked against `outputDigest`, never the
6
+ * server files; its server code runs on the owner, through the relay.
7
+ *
8
+ * Its host protocol is served by a {@link ProtocolServer} of its own, reached over the network
9
+ * binding (§18.2), so the owner instance is a host of its hosted home as any host is of an
10
+ * instance (invariant 11): it registers `submissions`, and a submission's one delivery owner is its
11
+ * artifact's owner link (D165, after the Opus review).
12
+ */
13
+ import { createHash, randomBytes } from "node:crypto";
14
+ import { linkSync, mkdirSync, writeFileSync } from "node:fs";
15
+ import { copyFile, readFile, rm } from "node:fs/promises";
16
+ import type { IncomingMessage, ServerResponse } from "node:http";
17
+ import { isAbsolute, join, relative } from "node:path";
18
+ import {
19
+ ArtifactManifest,
20
+ artifactGetMethod,
21
+ artifactListMethod,
22
+ createDiagnostic,
23
+ type HostedPushParams,
24
+ type HostedPushResult,
25
+ type HostedRoute,
26
+ hostedPushMethod,
27
+ hostedSubmissionMethod,
28
+ type InstanceInfo,
29
+ RouteId,
30
+ RpcError,
31
+ remoteTokenMethod,
32
+ } from "@mostra/protocol";
33
+ import type { Addressing } from "../addressing/index.ts";
34
+ import { coverageMatcher, readFieldCoverage, readServerFunctions } from "../builder/index.ts";
35
+ import { noFaults } from "../faults.ts";
36
+ import {
37
+ Capabilities,
38
+ capabilityKey,
39
+ createGateway,
40
+ type FaceSpec,
41
+ type Gateway,
42
+ } from "../gateway/index.ts";
43
+ import { platformName } from "../home/index.ts";
44
+ import { createEphemeralBus, createInteraction, type Interaction } from "../interaction/index.ts";
45
+ import type { Ledger } from "../ledger/index.ts";
46
+ import { createLive, liveMethods } from "../live/index.ts";
47
+ import type { Log } from "../log.ts";
48
+ import { handler, ProtocolServer, type Session } from "../protocol-server/index.ts";
49
+ import { canonicalRef, listingDigest, versionIdFor } from "../publish/index.ts";
50
+ import { openRegistry, type Registry } from "../registry/index.ts";
51
+ import type { Authorization } from "./auth.ts";
52
+ import { rotateIncarnation } from "./data.ts";
53
+ import { createHostedRelay } from "./relay.ts";
54
+
55
+ /** Lower-case Crockford base32, for route labels (one DNS label, 130 bits). */
56
+ const LABEL_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
57
+
58
+ /** A random route label: 26 lower-case Crockford base32 characters (INTERFACES §18.4). */
59
+
60
+ /** A character no part of a listing's path may hold: a backslash, a colon, a control character. */
61
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses
62
+ const UNSAFE_PART = /[\\:\u0000-\u001f\u007f]/;
63
+
64
+ /**
65
+ * Whether a pushed listing's path is one a version can hold on every system the server runs on: `/`
66
+ * between non-empty parts, none `.` or `..`, and no backslash, colon or control character, which
67
+ * Windows reads as separators, drive or stream names, or refuses (Opus review of WP-29, 5); in NFC,
68
+ * as listings are written (DATA_MODEL §2).
69
+ */
70
+ function safeListingPath(path: string): boolean {
71
+ if (path.length > 1024 || path.normalize("NFC") !== path) return false;
72
+ return path
73
+ .split("/")
74
+ .every((part) => part !== "" && part !== "." && part !== ".." && !UNSAFE_PART.test(part));
75
+ }
76
+
77
+ export function randomLabel(): string {
78
+ const bytes = randomBytes(26);
79
+ let label = "";
80
+ for (const byte of bytes) label += LABEL_ALPHABET[byte & 31];
81
+ return label;
82
+ }
83
+
84
+ /** What the server keeps of one open hosted home. */
85
+ export interface HostedHome {
86
+ readonly id: string;
87
+ readonly dir: string;
88
+ readonly ledger: Ledger;
89
+ readonly registry: Registry;
90
+ readonly interaction: Interaction;
91
+ /** The home's host protocol, served over the binding. */
92
+ readonly protocol: ProtocolServer;
93
+ /** The home's current incarnation (DATA_MODEL §7.2). */
94
+ incarnation(): string;
95
+ /** The SHA-256s of client files a pending push of this home names as missing. */
96
+ wanted(sha256: string): boolean;
97
+ /** Records a file this home uploaded (`PUT /files/<sha256>`, §18.2). */
98
+ uploaded(sha256: string): void;
99
+ /** Whether a binding is open, a stream or poll is served, or a delivery waits. */
100
+ busy(): boolean;
101
+ /**
102
+ * Serves a request the server's front routed here by its exact `Host` (INTERFACES §18.4): the
103
+ * shell on a user-content domain's apex (`/a/<routeId>…`), or a route's frames on its label.
104
+ */
105
+ serve(request: IncomingMessage, response: ServerResponse, at: HostedAddress): Promise<void>;
106
+ stop(): Promise<void>;
107
+ }
108
+
109
+ /** Where a hosted request came in: a domain's apex, or a route's label on it. */
110
+ export type HostedAddress =
111
+ | { readonly kind: "shell"; readonly domain: string; readonly routeId: string }
112
+ | { readonly kind: "frame"; readonly domain: string; readonly routeId: string };
113
+
114
+ /** Options for {@link openHostedHome}. */
115
+ export interface HostedHomeOptions {
116
+ readonly id: string;
117
+ readonly dir: string;
118
+ readonly ledger: Ledger;
119
+ readonly incarnation: string;
120
+ /** The server's directory ledger (routes, files, links). */
121
+ readonly directory: Ledger;
122
+ /** `<data>/files`: version files, content-addressed, stored once for the directory. */
123
+ readonly filesDir: string;
124
+ readonly auth: Authorization;
125
+ readonly runtimeVersion: string;
126
+ readonly log: Log;
127
+ /** `https` behind a TLS terminator; `http` only for loopback tests (§18.1). */
128
+ readonly scheme: "https" | "http";
129
+ /** The user-content domains: new links on `active`, issued ones keep theirs (D137). */
130
+ readonly domains: { readonly active: string; readonly spares: readonly string[] };
131
+ /** The shell's built files. */
132
+ readonly shellDir: string | undefined;
133
+ /** The relay's server settings (`relay` in the configuration, D165 item 4). */
134
+ readonly relay?: {
135
+ readonly waitingRunsPerArtifact?: number | undefined;
136
+ readonly drainPerSecond?: number | undefined;
137
+ /** How often waiting and unacknowledged runs meet their limits (tests shorten it). */
138
+ readonly sweepMs?: number | undefined;
139
+ /** How often viewers' live interest is renewed with the owner (tests shorten it). */
140
+ readonly liveRenewMs?: number | undefined;
141
+ /** `rateLimits.perLink.relayedRuns`, in milliseconds. */
142
+ readonly perLink?: { readonly count: number; readonly perMs: number } | undefined;
143
+ };
144
+ }
145
+
146
+ function refuse(code: Parameters<typeof createDiagnostic>[0], message: string): RpcError {
147
+ return new RpcError(createDiagnostic(code, { message }));
148
+ }
149
+
150
+ /** Opens the parts of a hosted home over its ledger. */
151
+ export async function openHostedHome(options: HostedHomeOptions): Promise<HostedHome> {
152
+ const { id, dir, ledger, directory, log } = options;
153
+ const registry = await openRegistry({ home: dir, ledger });
154
+ /** Pending pushes: version ID → the client files still missing. */
155
+ const pending = new Map<string, Set<string>>();
156
+ let incarnation = options.incarnation;
157
+
158
+ const ownerLinkOf = (artifactId: string): string | undefined =>
159
+ directory.read(
160
+ (db) =>
161
+ db.get<{ owner_link_id: string }>(
162
+ "SELECT owner_link_id FROM artifact_route WHERE home_id = ? AND artifact_id = ?",
163
+ id,
164
+ artifactId,
165
+ )?.owner_link_id,
166
+ );
167
+
168
+ const coverage = (() => {
169
+ const cache = new Map<string, (fieldId: string) => boolean>();
170
+ return (versionId: string) => {
171
+ let matcher = cache.get(versionId);
172
+ if (!matcher) {
173
+ matcher = coverageMatcher(readFieldCoverage(registry.store.versionDir(versionId)));
174
+ if (cache.size >= 512) cache.delete(cache.keys().next().value as string);
175
+ cache.set(versionId, matcher);
176
+ }
177
+ return matcher;
178
+ };
179
+ })();
180
+
181
+ let protocol: ProtocolServer;
182
+ const interaction = createInteraction({
183
+ // A respondent on a hosted link learns only that the answer was sent (D165 item 1a).
184
+ sentOnly: true,
185
+ ledger,
186
+ log,
187
+ faults: noFaults,
188
+ hosts: {
189
+ registrants: (port) => protocol.registrants(port),
190
+ call: (session, method, params, timeoutMs) =>
191
+ protocol.callSession(session, method, params as never, timeoutMs),
192
+ notify: (session, method, params) => protocol.notify(session, method, params as never),
193
+ drained: (session) => protocol.drained(session),
194
+ },
195
+ expectedHosts: () => [],
196
+ artifacts: { resolve: (ref) => registry.get(canonicalRef(ref)).id },
197
+ coverage,
198
+ // A submission's one delivery owner is its artifact's owner link, connected or not, so it
199
+ // waits for that instance and no other instance of the account receives it (D165 item 1b).
200
+ deliverSnapshots: true,
201
+ deliveryOwners: (artifactId) => {
202
+ const owner = ownerLinkOf(artifactId);
203
+ return owner === undefined ? undefined : [owner];
204
+ },
205
+ });
206
+
207
+ /** The route of an artifact on this home, minted on its first push by `link`. */
208
+ const routeFor = (artifactId: string, link: string): HostedRoute =>
209
+ directory.write((db) => {
210
+ const found = db.get<{ id: string; label: string; owner_link_id: string }>(
211
+ "SELECT id, label, owner_link_id FROM artifact_route WHERE home_id = ? AND artifact_id = ?",
212
+ id,
213
+ artifactId,
214
+ );
215
+ if (found) {
216
+ if (found.owner_link_id !== link) {
217
+ const owner = db.get<{ name: string }>(
218
+ "SELECT name FROM instance_link WHERE id = ?",
219
+ found.owner_link_id,
220
+ );
221
+ throw refuse(
222
+ "MOSTRA_REMOTE_NOT_OWNER_INSTANCE",
223
+ `The instance "${owner?.name ?? found.owner_link_id}" owns this hosted artifact; push it from there.`,
224
+ );
225
+ }
226
+ return { routeId: found.id, label: found.label };
227
+ }
228
+ const routeId = RouteId.create();
229
+ let label = randomLabel();
230
+ // A label is issued once, forever (label_issued keeps every one): a collision draws again.
231
+ while (db.get("SELECT 1 FROM label_issued WHERE label = ?", label)) label = randomLabel();
232
+ const at = new Date().toISOString();
233
+ db.run(
234
+ "INSERT INTO label_issued (label, home_id, route_id, kind, issued_at) VALUES (?, ?, ?, 'server', ?)",
235
+ label,
236
+ id,
237
+ routeId,
238
+ at,
239
+ );
240
+ db.run(
241
+ "INSERT INTO artifact_route (id, home_id, artifact_id, owner_link_id, label, created_at) VALUES (?, ?, ?, ?, ?, ?)",
242
+ routeId,
243
+ id,
244
+ artifactId,
245
+ link,
246
+ label,
247
+ at,
248
+ );
249
+ log.info("server.route_minted", { home: id, artifactId, routeId });
250
+ return { routeId, label };
251
+ });
252
+
253
+ // ── Hosted pages (INTERFACES §18.4) ────────────────────────────────────────────────────
254
+
255
+ const routeOf = (artifactId: string): { id: string; label: string } | undefined =>
256
+ directory.read((db) =>
257
+ db.get<{ id: string; label: string }>(
258
+ "SELECT id, label FROM artifact_route WHERE home_id = ? AND artifact_id = ?",
259
+ id,
260
+ artifactId,
261
+ ),
262
+ );
263
+ const artifactOfRoute = (routeId: string): string | undefined =>
264
+ directory.read(
265
+ (db) =>
266
+ db.get<{ artifact_id: string }>(
267
+ "SELECT artifact_id FROM artifact_route WHERE id = ? AND home_id = ?",
268
+ routeId,
269
+ id,
270
+ )?.artifact_id,
271
+ );
272
+ const domains = [options.domains.active, ...options.domains.spares];
273
+ const originOf = (host: string): string => `${options.scheme}://${host}`;
274
+ const capabilities: Capabilities = new Capabilities({
275
+ ledger,
276
+ log,
277
+ key: capabilityKey(dir, log),
278
+ now: () => Date.now(),
279
+ shellOrigin: () => originOf(options.domains.active),
280
+ servesShell: (origin) => domains.some((domain) => originOf(domain) === origin),
281
+ });
282
+ // A hosted home binds nothing: its faces are served through the front. These answer the few
283
+ // questions the gateway asks of loopback addressing, none of which a hosted face reaches.
284
+ const addressing: Addressing = {
285
+ bindAddress: "",
286
+ urlHost: options.domains.active,
287
+ origin: () => originOf(options.domains.active),
288
+ hosts: () => [],
289
+ leased: () => undefined,
290
+ leases: () => [],
291
+ listen: () => Promise.reject(new Error("A hosted home binds no listener.")),
292
+ frameMode: () => "worker",
293
+ listenFace: () => Promise.reject(new Error("A hosted home binds no listener.")),
294
+ releaseFace: () => undefined,
295
+ faceLocal: () => "",
296
+ };
297
+ const bus = createEphemeralBus();
298
+ // Live values a hosted page reads: tallies (counted here, RM-07) and the values its owner's
299
+ // producers push through the relay. No producer runs here: the home runs no artifact code.
300
+ const noPool = new Proxy(
301
+ {},
302
+ {
303
+ get: () => {
304
+ throw new Error("A hosted home runs no workers.");
305
+ },
306
+ },
307
+ ) as Parameters<typeof createLive>[0]["pool"];
308
+ const live = createLive({
309
+ ledger,
310
+ log,
311
+ bus,
312
+ pool: noPool,
313
+ interaction,
314
+ latest: () => undefined,
315
+ artifactsWithLive: () => [],
316
+ version: () => undefined,
317
+ });
318
+ // The relay: a hosted page's runs and calls run on its owner instance (D165 item 4).
319
+ const relay = createHostedRelay({
320
+ ledger,
321
+ interaction,
322
+ bus,
323
+ log,
324
+ ownerOf: (artifactId) => ownerLinkOf(artifactId),
325
+ // The newest session of a link is its own: an older one is a connection the owner already
326
+ // left, which the server may hold until its silence limit (Opus review of WP-29, 1).
327
+ sessionOf: (linkId) =>
328
+ protocol
329
+ .registrants("relay")
330
+ .filter((entry) => entry.owner === linkId)
331
+ .at(-1)?.session,
332
+ call: (session, method, params, timeoutMs) =>
333
+ protocol.callSession(session, method, params, timeoutMs),
334
+ functions: (versionId) => readServerFunctions(registry.store.versionDir(versionId)),
335
+ ...(options.relay?.waitingRunsPerArtifact !== undefined
336
+ ? { waitingRunsPerArtifact: options.relay.waitingRunsPerArtifact }
337
+ : {}),
338
+ ...(options.relay?.drainPerSecond !== undefined
339
+ ? { drainPerSecond: options.relay.drainPerSecond }
340
+ : {}),
341
+ ...(options.relay?.sweepMs !== undefined ? { sweepMs: options.relay.sweepMs } : {}),
342
+ ...(options.relay?.liveRenewMs !== undefined ? { liveRenewMs: options.relay.liveRenewMs } : {}),
343
+ ...(options.relay?.perLink !== undefined ? { perLink: options.relay.perLink } : {}),
344
+ latestVersion: (artifactId) =>
345
+ ledger.read(
346
+ (db) =>
347
+ db.get<{ latest_version_id: string | null }>(
348
+ "SELECT latest_version_id FROM artifact WHERE id = ?",
349
+ artifactId,
350
+ )?.latest_version_id ?? undefined,
351
+ ),
352
+ storeLive: (artifactId, versionId, produced) => live.relayed(artifactId, versionId, produced),
353
+ });
354
+ /** A page's live reads: they ask the owner for producers, and say when it is away. */
355
+ const hostedLive: Pick<typeof live, "read"> = {
356
+ read(page, input) {
357
+ const states = live.read(page, input);
358
+ relay.liveWanted(page.artifactId);
359
+ if (!relay.ownerOffline(page.artifactId)) return states;
360
+ return states.map((state) =>
361
+ state.key.startsWith("$tally/") ? state : { ...state, ownerOffline: true },
362
+ );
363
+ },
364
+ };
365
+ const gateway: Gateway = createGateway({
366
+ ledger,
367
+ log,
368
+ addressing,
369
+ capabilities,
370
+ artifacts: {
371
+ get: (ref) => registry.get(canonicalRef(ref)),
372
+ versionDir: (versionId) => registry.store.versionDir(versionId),
373
+ damage: (versionId) => hostedDamage(registry.store.versionDir(versionId)),
374
+ },
375
+ shellDir: options.shellDir,
376
+ interaction,
377
+ bus,
378
+ actions: relay,
379
+ live: hostedLive,
380
+ // Both channels: a hosted home has no host to narrow them (its owner is a host of it, D165).
381
+ controls: async () => ({ submitChannels: ["shell", "artifact"] }),
382
+ activated: () => undefined,
383
+ hosted: {
384
+ shellOrigin: () => originOf(options.domains.active),
385
+ servesShell: (origin) => domains.some((domain) => originOf(domain) === origin),
386
+ shellPath: (artifactId) => `/a/${routeOf(artifactId)?.id ?? artifactId}`,
387
+ artifactOrigin: (artifactId, shellOrigin) => {
388
+ const route = routeOf(artifactId);
389
+ const domain = domains.find((candidate) => originOf(candidate) === shellOrigin);
390
+ return route && domain ? originOf(`${route.label}.${domain}`) : undefined;
391
+ },
392
+ },
393
+ });
394
+ /** The faces of a domain: its shell, and a route's frames, opened when first asked for. */
395
+ const shellSpec = (domain: string): FaceSpec => ({
396
+ by: "hosted",
397
+ group: `hosted:${domain}`,
398
+ listener: "shell",
399
+ via: "token",
400
+ lease: false,
401
+ });
402
+ const ensureShell = async (domain: string): Promise<string> => {
403
+ const spec = shellSpec(domain);
404
+ const handle = await gateway.openFace(spec);
405
+ handle.setOrigin(originOf(domain));
406
+ return handle.key;
407
+ };
408
+ const ensureFrame = async (
409
+ domain: string,
410
+ artifactId: string,
411
+ label: string,
412
+ ): Promise<string> => {
413
+ await ensureShell(domain);
414
+ const handle = await gateway.openFace({
415
+ by: "hosted",
416
+ group: `hosted:${domain}`,
417
+ listener: "artifact",
418
+ artifactId,
419
+ via: "token",
420
+ lease: false,
421
+ mode: "worker",
422
+ });
423
+ handle.setOrigin(originOf(`${label}.${domain}`));
424
+ return handle.key;
425
+ };
426
+ const notServed = (response: ServerResponse): void => {
427
+ response.writeHead(404, { "content-type": "application/json", "cache-control": "no-store" });
428
+ response.end(
429
+ JSON.stringify(
430
+ createDiagnostic("MOSTRA_HYGIENE_NOT_SERVED", {
431
+ message: "Nothing is served at this path.",
432
+ }),
433
+ ),
434
+ );
435
+ };
436
+ const serve = async (
437
+ request: IncomingMessage,
438
+ response: ServerResponse,
439
+ at: HostedAddress,
440
+ ): Promise<void> => {
441
+ const artifactId = artifactOfRoute(at.routeId);
442
+ const route = artifactId === undefined ? undefined : routeOf(artifactId);
443
+ if (artifactId === undefined || !route) {
444
+ notServed(response);
445
+ return;
446
+ }
447
+ if (at.kind === "shell") {
448
+ // The shell's paths name the route; the gateway's routes name the artifact (§18.4).
449
+ const url = request.url ?? "/";
450
+ const prefix = `/a/${at.routeId}`;
451
+ if (!url.startsWith(prefix)) {
452
+ notServed(response);
453
+ return;
454
+ }
455
+ request.url = `/a/${artifactId}${url.slice(prefix.length)}`;
456
+ const key = await ensureShell(at.domain);
457
+ if (!gateway.dispatch(key, request, response)) notServed(response);
458
+ return;
459
+ }
460
+ const key = await ensureFrame(at.domain, artifactId, route.label);
461
+ if (!gateway.dispatch(key, request, response)) notServed(response);
462
+ };
463
+
464
+ /** The client files of a listing this home doesn't hold yet. */
465
+ const missingOf = (files: readonly string[]): string[] =>
466
+ directory.read((db) =>
467
+ files.filter(
468
+ (sha) => !db.get("SELECT 1 FROM home_file WHERE home_id = ? AND sha256 = ?", id, sha),
469
+ ),
470
+ );
471
+
472
+ const push = async (params: HostedPushParams, session: Session): Promise<HostedPushResult> => {
473
+ const link = session.link?.instanceId;
474
+ if (link === undefined || session.attributes["linkId"] !== link) {
475
+ throw refuse(
476
+ "MOSTRA_REMOTE_NOT_OWNER_INSTANCE",
477
+ "Only an owner instance's binding pushes versions.",
478
+ );
479
+ }
480
+ const version = params.version;
481
+ // The identity is checked, not believed: the version ID is a digest of the artifact ID and the
482
+ // two digests (D89), and the listing's digest is the output digest (DATA_MODEL §2).
483
+ if (
484
+ versionIdFor(params.artifactId, version.sourceDigest, version.envDigest) !== version.versionId
485
+ ) {
486
+ throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed version's ID doesn't match its digests.");
487
+ }
488
+ const listed = version.listing.map(([path, executable, sha256]) => ({
489
+ path,
490
+ executable,
491
+ sha256,
492
+ }));
493
+ if (listingDigest(listed) !== version.outputDigest) {
494
+ throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed listing doesn't match the output digest.");
495
+ }
496
+ const registryEntry = version.listing.find(([path]) => path === "registry.json");
497
+ if (!registryEntry || sha256Text(version.registry) !== registryEntry[2]) {
498
+ throw refuse(
499
+ "MOSTRA_HOME_INTEGRITY",
500
+ "The pushed registry.json isn't the one the listing names.",
501
+ );
502
+ }
503
+ for (const [path] of version.listing) {
504
+ if (!(path === "registry.json" || path.startsWith("client/") || path.startsWith("server/"))) {
505
+ throw refuse("MOSTRA_HOME_INTEGRITY", `The listing names ${path}, outside a version.`);
506
+ }
507
+ if (!safeListingPath(path)) {
508
+ throw refuse(
509
+ "MOSTRA_HOME_INTEGRITY",
510
+ `The listing names an unsafe path, ${JSON.stringify(path.slice(0, 300))}.`,
511
+ );
512
+ }
513
+ }
514
+ let manifestDoc: { manifest?: unknown; artifactId?: unknown; versionId?: unknown };
515
+ try {
516
+ manifestDoc = JSON.parse(version.manifest) as typeof manifestDoc;
517
+ } catch {
518
+ throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed manifest.json isn't JSON.");
519
+ }
520
+ if (
521
+ manifestDoc.artifactId !== params.artifactId ||
522
+ manifestDoc.versionId !== version.versionId
523
+ ) {
524
+ throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed manifest.json names another version.");
525
+ }
526
+ const manifest = ArtifactManifest.safeParse(manifestDoc.manifest);
527
+ if (!manifest.success)
528
+ throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed artifact manifest isn't valid.");
529
+
530
+ const route = routeFor(params.artifactId, link);
531
+ if (registry.hasVersion(version.versionId)) {
532
+ const known = registry
533
+ .get({ artifactId: params.artifactId })
534
+ .versions.find((v) => v.id === version.versionId);
535
+ return {
536
+ status: "complete",
537
+ versionId: version.versionId,
538
+ number: known?.number ?? version.number,
539
+ route,
540
+ };
541
+ }
542
+ // Only client files are stored: server code never reaches the server (D165 item 3).
543
+ const clientFiles = version.listing.filter(([path]) => path.startsWith("client/"));
544
+ const missing = missingOf([...new Set(clientFiles.map(([, , sha]) => sha))]);
545
+ if (missing.length > 0) {
546
+ pending.set(version.versionId, new Set(missing));
547
+ return { status: "missing", files: missing, route };
548
+ }
549
+ pending.delete(version.versionId);
550
+
551
+ // Every file is here: lay the version out as the gateway serves versions, then commit it.
552
+ const stage = join(
553
+ registry.store.stagingDir,
554
+ `${version.versionId}.push-${process.pid}-${Date.now()}`,
555
+ );
556
+ await rm(stage, { recursive: true, force: true });
557
+ mkdirSync(stage, { recursive: true, mode: 0o700 });
558
+ try {
559
+ writeFileSync(join(stage, "manifest.json"), version.manifest);
560
+ writeFileSync(join(stage, "registry.json"), version.registry);
561
+ writeFileSync(join(stage, "lock.yaml"), version.lock);
562
+ // The full listing, server files included, so the version can be checked as built.
563
+ writeFileSync(join(stage, "listing.json"), JSON.stringify(version.listing));
564
+ for (const [path, , sha] of clientFiles) {
565
+ const target = join(stage, ...path.split("/"));
566
+ // Checked again where it lands: nothing a tenant names leaves its own staging directory.
567
+ if (relative(stage, target).startsWith("..") || isAbsolute(relative(stage, target))) {
568
+ throw refuse("MOSTRA_HOME_INTEGRITY", "The listing names a path outside the version.");
569
+ }
570
+ mkdirSync(join(target, ".."), { recursive: true, mode: 0o700 });
571
+ const stored = join(options.filesDir, sha);
572
+ try {
573
+ linkSync(stored, target);
574
+ } catch {
575
+ await copyFile(stored, target);
576
+ }
577
+ }
578
+ await registry.store.promote(stage, version.versionId);
579
+ } catch (error) {
580
+ await rm(stage, { recursive: true, force: true });
581
+ throw error;
582
+ }
583
+ const committed = registry.commit({
584
+ artifactId: params.artifactId,
585
+ bindingPath: undefined,
586
+ number: version.number,
587
+ manifestId: params.artifactId,
588
+ versionId: version.versionId,
589
+ sourceDigest: version.sourceDigest,
590
+ envDigest: version.envDigest,
591
+ outputDigest: version.outputDigest,
592
+ manifest: manifest.data,
593
+ // The owner's policy in force, as the owner's host decided it (D102): it sticks here.
594
+ policy: version.policy,
595
+ forcedCodes: [],
596
+ stillClaims: () => false,
597
+ });
598
+ directory.write((db) => {
599
+ for (const sha of new Set(clientFiles.map(([, , file]) => file))) {
600
+ const added = db.run(
601
+ "INSERT OR IGNORE INTO home_file (home_id, sha256) VALUES (?, ?)",
602
+ id,
603
+ sha,
604
+ );
605
+ if (added.changes > 0) {
606
+ db.run(
607
+ "INSERT INTO file_ref (sha256, homes) VALUES (?, 1) ON CONFLICT (sha256) DO UPDATE SET homes = homes + 1, unreferenced_at = NULL",
608
+ sha,
609
+ );
610
+ }
611
+ }
612
+ });
613
+ log.info("server.version_pushed", {
614
+ home: id,
615
+ artifactId: params.artifactId,
616
+ versionId: version.versionId,
617
+ });
618
+ return { status: "complete", versionId: version.versionId, number: committed.version, route };
619
+ };
620
+
621
+ const describe = (): InstanceInfo => {
622
+ const head = ledger.read(
623
+ (db) =>
624
+ db.get<{ cursor: number | null }>("SELECT MAX(cursor) AS cursor FROM event")?.cursor ?? 0,
625
+ );
626
+ return {
627
+ version: options.runtimeVersion,
628
+ home: `hosted:${id}`,
629
+ platform: platformName(),
630
+ pid: process.pid,
631
+ mode: "hosted",
632
+ incarnation,
633
+ cursor: String(head),
634
+ };
635
+ };
636
+
637
+ protocol = new ProtocolServer({
638
+ log,
639
+ describe,
640
+ servesHome: () => false,
641
+ supportedPorts: ["submissions", "relay"],
642
+ notifications: ["events/notify"],
643
+ admit: (session, params) => {
644
+ // The owner instance is the witness a restore can't roll back: a home that holds less than
645
+ // its owner committed, or saw less of its relay, was restored to an earlier copy, and rotates
646
+ // its incarnation before it answers (INTERFACES §18.2).
647
+ const link = params.link;
648
+ if (link !== undefined && link.instanceId === session.attributes["linkId"]) {
649
+ const marks = ledger.read((db) => ({
650
+ head: db.get<{ head: number | null }>("SELECT MAX(cursor) AS head FROM event")?.head ?? 0,
651
+ // What the home knows of the link's relay: its runs, and the highest mark its owner
652
+ // reported, kept so a restore is told once, not at every later reconnect.
653
+ relayHigh: Math.max(
654
+ db.get<{ high: number | null }>(
655
+ "SELECT MAX(relay_seq) AS high FROM relay_run WHERE owner_link_id = ?",
656
+ link.instanceId,
657
+ )?.high ?? 0,
658
+ db.get<{ floor: number }>(
659
+ "SELECT floor FROM relay_floor WHERE link_id = ?",
660
+ link.instanceId,
661
+ )?.floor ?? 0,
662
+ ),
663
+ }));
664
+ const followedAhead =
665
+ link.followed !== undefined &&
666
+ link.followed.incarnation === incarnation &&
667
+ Number(link.followed.cursor) > marks.head;
668
+ const relayAhead = link.relayMark > marks.relayHigh;
669
+ if (followedAhead || relayAhead) {
670
+ incarnation = rotateIncarnation(ledger);
671
+ log.warn("server.home_rotated", {
672
+ home: id,
673
+ why: followedAhead ? "owner-cursor" : "owner-relay-mark",
674
+ });
675
+ }
676
+ ledger.write((db) =>
677
+ db.run(
678
+ `INSERT INTO relay_floor (link_id, floor) VALUES (?, ?)
679
+ ON CONFLICT (link_id) DO UPDATE SET floor = MAX(floor, excluded.floor)`,
680
+ link.instanceId,
681
+ link.relayMark,
682
+ ),
683
+ );
684
+ }
685
+ // An owner link is its own grant's: a session can't speak for another instance's link.
686
+ if (params.link !== undefined && params.link.instanceId !== session.attributes["linkId"]) {
687
+ throw refuse(
688
+ "MOSTRA_REMOTE_NOT_OWNER_INSTANCE",
689
+ "This binding's sign-in is for another instance link.",
690
+ );
691
+ }
692
+ // A session that takes deliveries or relayed runs is an owner instance's, so it names its own
693
+ // link: one without a link could otherwise be taken for an owner by its client name (Opus
694
+ // review of WP-29, 6).
695
+ if (params.link === undefined && params.ports.length > 0) {
696
+ throw refuse(
697
+ "MOSTRA_REMOTE_NOT_OWNER_INSTANCE",
698
+ "A binding that registers ports must name its own instance link.",
699
+ );
700
+ }
701
+ },
702
+ onInitialized: (session) => {
703
+ interaction.connected(session);
704
+ relay.connected(session);
705
+ },
706
+ onClosed: (session) => {
707
+ interaction.disconnected(session);
708
+ relay.disconnected(session);
709
+ },
710
+ handlers: [
711
+ ...interaction.methods(),
712
+ handler(artifactListMethod, (params) => ({ artifacts: registry.list(params.filter ?? {}) })),
713
+ handler(artifactGetMethod, (params) => registry.get(canonicalRef(params.artifact))),
714
+ handler(hostedPushMethod, (params, session) => push(params, session)),
715
+ handler(hostedSubmissionMethod, (params, session) => {
716
+ // Only the owner instance of its artifact reads a submission this way (D165 item 1b),
717
+ // and only one it was, or is, delivered.
718
+ const link = session.link?.instanceId;
719
+ const envelope =
720
+ link === undefined ? undefined : interaction.envelopeFor(params.submissionId, link);
721
+ if (!envelope) {
722
+ throw refuse(
723
+ "MOSTRA_HOST_INVALID_PARAMS",
724
+ `This home delivers no submission ${params.submissionId} to this instance.`,
725
+ );
726
+ }
727
+ return envelope;
728
+ }),
729
+ ...gateway.methods(),
730
+ ...relay.methods(),
731
+ ...liveMethods(live, (ref) => registry.get(canonicalRef(ref)).id),
732
+ handler(remoteTokenMethod, (params, session) => {
733
+ const found = options.auth.authenticate(params.accessToken);
734
+ if (!found || found.grantId !== session.attributes["grantId"]) {
735
+ throw refuse(
736
+ "MOSTRA_REMOTE_LOGIN_FAILED",
737
+ "That access token isn't this binding's grant's.",
738
+ );
739
+ }
740
+ const replace = session.attributes["replaceToken"] as
741
+ | ((expiresAt: number) => void)
742
+ | undefined;
743
+ replace?.(found.expiresAt);
744
+ return { expiresAt: new Date(found.expiresAt).toISOString() };
745
+ }),
746
+ ],
747
+ });
748
+ interaction.start();
749
+ live.start();
750
+
751
+ return {
752
+ id,
753
+ dir,
754
+ ledger,
755
+ registry,
756
+ interaction,
757
+ protocol,
758
+ incarnation: () => incarnation,
759
+ wanted: (sha) => [...pending.values()].some((files) => files.has(sha)),
760
+ uploaded(sha) {
761
+ directory.write((db) => {
762
+ const added = db.run(
763
+ "INSERT OR IGNORE INTO home_file (home_id, sha256) VALUES (?, ?)",
764
+ id,
765
+ sha,
766
+ );
767
+ if (added.changes > 0) {
768
+ db.run(
769
+ "INSERT INTO file_ref (sha256, homes) VALUES (?, 1) ON CONFLICT (sha256) DO UPDATE SET homes = homes + 1, unreferenced_at = NULL",
770
+ sha,
771
+ );
772
+ }
773
+ });
774
+ for (const files of pending.values()) files.delete(sha);
775
+ },
776
+ busy: () => protocol.connections > 0 || bus.activeViews() > 0 || relay.busy(),
777
+ serve,
778
+ async stop() {
779
+ relay.stop();
780
+ live.stop();
781
+ interaction.stop();
782
+ await gateway.close();
783
+ await protocol.close();
784
+ bus.close?.();
785
+ },
786
+ };
787
+ }
788
+
789
+ /**
790
+ * What is wrong with a hosted version's stored files (FAILURE_MODEL §3): its listing must be the
791
+ * one its output digest names, and every client file it lists present with its bytes. Server files
792
+ * are listed but never stored (D165 item 3).
793
+ */
794
+ async function hostedDamage(versionDir: string): Promise<string | undefined> {
795
+ try {
796
+ const manifest = JSON.parse(await readFile(join(versionDir, "manifest.json"), "utf8")) as {
797
+ outputDigest?: string;
798
+ };
799
+ const listing = JSON.parse(await readFile(join(versionDir, "listing.json"), "utf8")) as [
800
+ string,
801
+ boolean,
802
+ string,
803
+ number,
804
+ ][];
805
+ const listed = listing.map(([path, executable, sha256]) => ({ path, executable, sha256 }));
806
+ if (listingDigest(listed) !== manifest.outputDigest)
807
+ return "its listing doesn't match its digest";
808
+ for (const [path, , sha256] of listing) {
809
+ if (!path.startsWith("client/") && path !== "registry.json") continue;
810
+ const bytes = await readFile(join(versionDir, ...path.split("/")));
811
+ if (createHash("sha256").update(bytes).digest("hex") !== sha256) return `${path} was changed`;
812
+ }
813
+ return undefined;
814
+ } catch (error) {
815
+ return `a file is missing (${(error as NodeJS.ErrnoException).code ?? "unreadable"})`;
816
+ }
817
+ }
818
+
819
+ /** The SHA-256 of a text's UTF-8 bytes, lowercase hex. */
820
+ function sha256Text(text: string): string {
821
+ return createHash("sha256").update(text, "utf8").digest("hex");
822
+ }