@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
package/dist/bin.js CHANGED
@@ -1,10 +1,2791 @@
1
1
  #!/usr/bin/env node
2
- import { a as uninstallService, i as serviceStatus, n as startInstance, o as checkPlatform, r as installService, s as resolveHomePath, t as runtimeVersion } from "./instance-BRfg27Rg.js";
3
- import { s as realPath } from "./files-FygSJIzK.js";
4
- import { mkdirSync } from "node:fs";
2
+ import { A as MAX_FRAME_BYTES, B as coverageMatcher, C as finishRun, D as runState, E as markWaiting, F as openLedger, I as noFaults, L as readFieldCoverage, M as ProtocolServer, N as handler, O as appendEvent, P as holdLock, R as readServerFunctions, S as appendRunOutput, T as markUnknown, V as openFileLog, _ as Capabilities, a as uninstallService, b as createInteraction, c as resolveHomePath, d as versionIdFor, f as createLive, g as shellAssetResponse, h as locateShell, i as serviceStatus, j as serveWebSocket, k as BINDING_SUBPROTOCOL, l as canonicalRef, m as createGateway, n as startInstance, o as checkPlatform, p as liveMethods, r as installService, s as platformName, t as runtimeVersion, u as listingDigest, v as capabilityKey, w as markRunning, x as createEphemeralBus, y as openRegistry, z as readProcess } from "./instance-FExcyENK.js";
3
+ import { s as realPath } from "./files-DGeWuE4I.js";
4
+ import { i as ownedDirectory } from "./directories-BLJjeSPD.js";
5
+ import { createWriteStream, existsSync, linkSync, mkdirSync, readFileSync, renameSync, statfsSync, writeFileSync } from "node:fs";
6
+ import { isAbsolute, join, parse, relative } from "node:path";
5
7
  import { fileURLToPath } from "node:url";
6
- import { LineSplitter, RpcError, RpcPeer, createDiagnostic, encodeLine } from "@mostra/protocol";
8
+ import { ACTION_ARGS_MAX, AccountId, ArtifactManifest, Duration, HOSTED_OFFLINE_LIMIT_DEFAULT, HomeId, LineSplitter, LinkId, RouteId, RpcError, RpcPeer, TALLY_LIVE_PREFIX, artifactGetMethod, artifactListMethod, checkArgumentFrames, createDiagnostic, durationMs, encodeLine, hostedPushMethod, hostedSubmissionMethod, isFinalRunStatus, portRelayCallMethod, portRelayCancelMethod, portRelayLiveMethod, portRelayReconcileMethod, portRelayRunMethod, relayCallBatchMethod, relayEffectMethod, relayLiveValueMethod, relayRunUpdateMethod, remoteTokenMethod } from "@mostra/protocol";
9
+ import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
10
+ import { execFileSync } from "node:child_process";
11
+ import { copyFile, readFile, rm } from "node:fs/promises";
12
+ import * as z from "zod";
13
+ import { createServer } from "node:http";
14
+ import { getRequestListener } from "@hono/node-server";
15
+ import { WebSocketServer } from "ws";
7
16
  import { parseArgs } from "node:util";
17
+ //#region src/platform/filesystems.ts
18
+ /**
19
+ * Whether a directory is on a network filesystem (D165 item 0b, DATA_MODEL §7.1): a remote
20
+ * server's data directory never is, since its locks and SQLite's WAL need a local disk, and a
21
+ * lock a network filesystem only pretends to hold would let two servers write one home.
22
+ *
23
+ * - **Linux:** the filesystem's magic number from `statfs(2)`: NFS, SMB, CIFS, SMB2, Ceph,
24
+ * AFS, Coda, 9P and FUSE (a FUSE mount may be sshfs or s3fs; a local FUSE data directory is
25
+ * refused too, rather than guessed at).
26
+ * - **macOS:** the filesystem's name (`stat -f %T`): `nfs`, `smbfs`, `afpfs`, `webdav`,
27
+ * `macfuse`/`osxfuse` and other FUSE names.
28
+ * - **Windows:** a UNC path (`\\server\share`), or a drive Windows reports as remote
29
+ * (`GetDriveTypeW`, through `fsutil fsinfo drivetype`).
30
+ *
31
+ * Answers the filesystem's name when it is a network one, `undefined` when it is local or can't
32
+ * be told (a check that can't run never refuses a disk it can't classify).
33
+ */
34
+ /** Linux `statfs` magic numbers of network and user-space filesystems. */
35
+ const LINUX_NETWORK = /* @__PURE__ */ new Map([
36
+ [26985, "nfs"],
37
+ [20859, "smb"],
38
+ [4283649346, "cifs"],
39
+ [4266872130, "smb2"],
40
+ [12805120, "ceph"],
41
+ [1397113167, "afs"],
42
+ [1937076805, "coda"],
43
+ [16914839, "9p"],
44
+ [1702057286, "fuse"]
45
+ ]);
46
+ const MAC_NETWORK = /^(nfs|smbfs|afpfs|webdav|cifs|ftp|macfuse|osxfuse|fuse.*)$/i;
47
+ /** The network filesystem `dir` is on, or `undefined` (local, or not knowable). */
48
+ function networkFilesystem(dir) {
49
+ if (process.platform === "linux") try {
50
+ const type = statfsSync(dir).type >>> 0;
51
+ return LINUX_NETWORK.get(type);
52
+ } catch {
53
+ return;
54
+ }
55
+ if (process.platform === "darwin") try {
56
+ const name = execFileSync("/usr/bin/stat", [
57
+ "-f",
58
+ "%T",
59
+ dir
60
+ ], {
61
+ encoding: "utf8",
62
+ stdio: [
63
+ "ignore",
64
+ "pipe",
65
+ "ignore"
66
+ ]
67
+ }).trim();
68
+ return MAC_NETWORK.test(name) ? name : void 0;
69
+ } catch {
70
+ return;
71
+ }
72
+ if (process.platform === "win32") {
73
+ if (/^\\\\[^\\?.]/.test(dir)) return "unc";
74
+ const drive = parse(dir).root.replace(/\\$/, "");
75
+ if (!/^[A-Za-z]:$/.test(drive)) return void 0;
76
+ try {
77
+ const answer = execFileSync(`${process.env["SystemRoot"] ?? "C:\\Windows"}\\System32\\fsutil.exe`, [
78
+ "fsinfo",
79
+ "drivetype",
80
+ drive
81
+ ], {
82
+ encoding: "utf8",
83
+ stdio: [
84
+ "ignore",
85
+ "pipe",
86
+ "ignore"
87
+ ],
88
+ windowsHide: true
89
+ });
90
+ return /remote|network/i.test(answer) ? "remote" : void 0;
91
+ } catch {
92
+ return;
93
+ }
94
+ }
95
+ }
96
+ //#endregion
97
+ //#region src/server/api.ts
98
+ /**
99
+ * The remote server's API origin (INTERFACES §18.2, §18.5): the authorization server's device
100
+ * grant (`/oauth/device`, `/oauth/token`, `/oauth/revoke`, its metadata and the device page), the
101
+ * network binding (`/host`, JSON-RPC over WebSocket with a bearer token) and version files
102
+ * (`PUT /files/<sha256>`). Never on a user-content domain (D165 item 7).
103
+ */
104
+ /** How often an open binding's grant is checked again: a revocation closes it within 60 s. */
105
+ const GRANT_RECHECK_MS = 3e4;
106
+ /** The largest version file accepted (per file; an operator's storage limit is WP-30's). */
107
+ const MAX_FILE_BYTES = 268435456;
108
+ const BASE_HEADERS = {
109
+ "cache-control": "no-store",
110
+ "cross-origin-resource-policy": "same-origin",
111
+ "referrer-policy": "no-referrer",
112
+ "x-content-type-options": "nosniff"
113
+ };
114
+ function send(response, status, body, headers = {}) {
115
+ const text = JSON.stringify(body);
116
+ response.writeHead(status, {
117
+ ...BASE_HEADERS,
118
+ "content-type": "application/json; charset=utf-8",
119
+ "content-length": String(Buffer.byteLength(text)),
120
+ ...headers
121
+ });
122
+ response.end(text);
123
+ }
124
+ function page(response, status, html) {
125
+ response.writeHead(status, {
126
+ ...BASE_HEADERS,
127
+ "content-type": "text/html; charset=utf-8",
128
+ "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'",
129
+ "x-frame-options": "DENY",
130
+ "referrer-policy": "same-origin"
131
+ });
132
+ response.end(html);
133
+ }
134
+ async function readBody(request, limit) {
135
+ const chunks = [];
136
+ let size = 0;
137
+ for await (const chunk of request) {
138
+ size += chunk.length;
139
+ if (size > limit) return void 0;
140
+ chunks.push(chunk);
141
+ }
142
+ return Buffer.concat(chunks);
143
+ }
144
+ function escapeHtml(text) {
145
+ return text.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);
146
+ }
147
+ /** The development identity provider, when the configuration names one (§18.5, WP-29). */
148
+ function developmentProvider(config) {
149
+ const provider = config.identityProviders?.find((candidate) => candidate.kind === "development");
150
+ return provider ? {
151
+ id: provider.id,
152
+ label: provider.label ?? "Development sign-in"
153
+ } : void 0;
154
+ }
155
+ /** The device page: the code, the warning, and the development provider's sign-in. */
156
+ function devicePage(options) {
157
+ return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="robots" content="noindex">
158
+ <meta name="viewport" content="width=device-width, initial-scale=1"><title>Link a machine to Mostra</title>
159
+ <style>body{font:16px/1.5 system-ui,sans-serif;max-width:34rem;margin:3rem auto;padding:0 1rem}
160
+ input{font:inherit;padding:.3rem}button{font:inherit;padding:.4rem .9rem;margin-right:.5rem}</style></head>
161
+ <body><h1>Link a machine to Mostra</h1>${options.done ? `<p>${escapeHtml(options.message ?? "Done.")}</p><p>You can close this page.</p>` : `${options.message ? `<p role="alert">${escapeHtml(options.message)}</p>` : ""}
162
+ <p><strong>Approving links a machine to your account.</strong> That machine's Mostra can then host
163
+ pages under your account and receives their answers. Continue only if you started this sign-in
164
+ yourself, on that machine.</p>
165
+ ${options.provider ? `<form method="post" action="/device">
166
+ <label>Code <input name="user_code" value="${escapeHtml(options.code)}" autocomplete="off" required></label>
167
+ <p>${escapeHtml(options.provider.label)}: this server signs people in with a development provider,
168
+ which trusts the name you type. Use it only on a server you run for yourself or for tests.</p>
169
+ <label>Your name <input name="name" required maxlength="64"></label>
170
+ <input type="hidden" name="provider" value="${escapeHtml(options.provider.id)}">
171
+ <p><button name="decision" value="approve">Approve this machine</button>
172
+ <button name="decision" value="deny">Refuse</button></p>
173
+ </form>` : "<p>This server has no identity provider configured, so nobody can sign in yet.</p>"}`}</body></html>`;
174
+ }
175
+ /** Creates the API origin. */
176
+ function createApi(options) {
177
+ const { config, auth, log } = options;
178
+ const apiOrigin = config.apiOrigin;
179
+ const sockets = new WebSocketServer({
180
+ noServer: true,
181
+ maxPayload: MAX_FRAME_BYTES,
182
+ perMessageDeflate: false,
183
+ handleProtocols: (protocols) => protocols.has("mostra.host") ? BINDING_SUBPROTOCOL : false
184
+ });
185
+ const bindings = /* @__PURE__ */ new Set();
186
+ const bearer = (request) => {
187
+ const header = request.headers.authorization ?? "";
188
+ const match = /^bearer\s+(\S+)$/i.exec(header);
189
+ return match ? auth.authenticate(match[1]) : void 0;
190
+ };
191
+ const unauthorized = (response, message) => send(response, 401, {
192
+ code: "MOSTRA_REMOTE_LOGIN_FAILED",
193
+ message
194
+ }, { "www-authenticate": `Bearer resource_metadata="${apiOrigin}/.well-known/oauth-protected-resource/host"` });
195
+ const metadata = () => ({
196
+ issuer: apiOrigin,
197
+ token_endpoint: `${apiOrigin}/oauth/token`,
198
+ device_authorization_endpoint: `${apiOrigin}/oauth/device`,
199
+ revocation_endpoint: `${apiOrigin}/oauth/revoke`,
200
+ grant_types_supported: ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"],
201
+ token_endpoint_auth_methods_supported: ["none"],
202
+ code_challenge_methods_supported: ["S256"],
203
+ scopes_supported: ["mostra", "offline_access"],
204
+ authorization_response_iss_parameter_supported: true
205
+ });
206
+ const form = async (request) => {
207
+ if (!(request.headers["content-type"] ?? "").startsWith("application/x-www-form-urlencoded")) return void 0;
208
+ const body = await readBody(request, 65536);
209
+ return body === void 0 ? void 0 : new URLSearchParams(body.toString("utf8"));
210
+ };
211
+ const upload = async (request, response, sha) => {
212
+ const who = bearer(request);
213
+ if (!who) {
214
+ unauthorized(response, "Version files need the binding's access token.");
215
+ return;
216
+ }
217
+ const home = await options.home(who.homeId);
218
+ options.touch(who.homeId);
219
+ if (!home.wanted(sha)) {
220
+ send(response, 409, {
221
+ code: "MOSTRA_HOME_INTEGRITY",
222
+ message: "No pending push of this home names that file as missing."
223
+ });
224
+ return;
225
+ }
226
+ const target = join(options.filesDir, sha);
227
+ const scratch = join(options.filesDir, `.upload-${randomBytes(8).toString("hex")}`);
228
+ const hash = createHash("sha256");
229
+ let size = 0;
230
+ let tooLarge = false;
231
+ await new Promise((resolve, reject) => {
232
+ const out = createWriteStream(scratch, { mode: 384 });
233
+ request.on("data", (chunk) => {
234
+ size += chunk.length;
235
+ if (size > MAX_FILE_BYTES) {
236
+ tooLarge = true;
237
+ request.destroy();
238
+ return;
239
+ }
240
+ hash.update(chunk);
241
+ out.write(chunk);
242
+ });
243
+ request.on("end", () => out.end(() => resolve()));
244
+ request.on("error", reject);
245
+ request.on("close", () => {
246
+ if (tooLarge) out.end(() => resolve());
247
+ });
248
+ }).catch(() => void 0);
249
+ if (tooLarge || hash.digest("hex") !== sha) {
250
+ await rm(scratch, { force: true });
251
+ send(response, tooLarge ? 413 : 400, {
252
+ code: "MOSTRA_HOME_INTEGRITY",
253
+ message: tooLarge ? "The file is too large." : "The bytes don't hash to the file's name."
254
+ });
255
+ return;
256
+ }
257
+ if (existsSync(target)) await rm(scratch, { force: true });
258
+ else renameSync(scratch, target);
259
+ home.uploaded(sha);
260
+ send(response, 201, {
261
+ sha256: sha,
262
+ size
263
+ });
264
+ };
265
+ return {
266
+ async request(request, response, path) {
267
+ const method = request.method ?? "GET";
268
+ if (method === "GET" && path === "/.well-known/oauth-authorization-server") {
269
+ send(response, 200, metadata());
270
+ return;
271
+ }
272
+ if (method === "GET" && path === "/.well-known/oauth-protected-resource/host") {
273
+ send(response, 200, {
274
+ resource: `${apiOrigin}/host`,
275
+ authorization_servers: [apiOrigin],
276
+ scopes_supported: ["mostra"]
277
+ });
278
+ return;
279
+ }
280
+ if (method === "POST" && path === "/oauth/device") {
281
+ const body = await form(request);
282
+ if (!body) {
283
+ send(response, 400, {
284
+ error: "invalid_request",
285
+ error_description: "Send a form."
286
+ });
287
+ return;
288
+ }
289
+ const answer = auth.device(body);
290
+ if ("error" in answer && typeof answer["status"] === "number") {
291
+ const failed = answer;
292
+ send(response, failed.status, {
293
+ error: failed.error,
294
+ error_description: failed.description
295
+ });
296
+ return;
297
+ }
298
+ send(response, 200, answer);
299
+ return;
300
+ }
301
+ if (method === "POST" && path === "/oauth/token") {
302
+ const body = await form(request);
303
+ if (!body) {
304
+ send(response, 400, {
305
+ error: "invalid_request",
306
+ error_description: "Send a form."
307
+ });
308
+ return;
309
+ }
310
+ const answer = auth.token(body);
311
+ if ("error" in answer) {
312
+ send(response, answer.status, {
313
+ error: answer.error,
314
+ error_description: answer.description
315
+ });
316
+ return;
317
+ }
318
+ send(response, 200, answer);
319
+ return;
320
+ }
321
+ if (method === "POST" && path === "/oauth/revoke") {
322
+ const body = await form(request);
323
+ if (body) auth.revoke(body);
324
+ send(response, 200, {});
325
+ return;
326
+ }
327
+ if (path === "/device") {
328
+ const provider = developmentProvider(config);
329
+ if (method === "GET") {
330
+ page(response, 200, devicePage({
331
+ code: new URL(request.url ?? "/", apiOrigin).searchParams.get("user_code") ?? "",
332
+ provider
333
+ }));
334
+ return;
335
+ }
336
+ if (method === "POST") {
337
+ if (request.headers.origin !== apiOrigin) {
338
+ page(response, 403, devicePage({
339
+ code: "",
340
+ provider,
341
+ message: "This form must be sent from this page."
342
+ }));
343
+ return;
344
+ }
345
+ const body = await form(request);
346
+ const code = body?.get("user_code") ?? "";
347
+ const name = (body?.get("name") ?? "").trim().slice(0, 64);
348
+ if (!body || !provider || body.get("provider") !== provider.id || name === "") {
349
+ page(response, 400, devicePage({
350
+ code,
351
+ provider,
352
+ message: "Enter the code and your name."
353
+ }));
354
+ return;
355
+ }
356
+ const approve = body.get("decision") === "approve";
357
+ const decided = auth.decide({
358
+ code,
359
+ approve,
360
+ identity: {
361
+ provider: provider.id,
362
+ subject: name.toLowerCase(),
363
+ name
364
+ }
365
+ });
366
+ if (!decided.ok) {
367
+ page(response, 400, devicePage({
368
+ code,
369
+ provider,
370
+ message: decided.reason
371
+ }));
372
+ return;
373
+ }
374
+ page(response, 200, devicePage({
375
+ code,
376
+ provider,
377
+ done: true,
378
+ message: approve ? "The machine is linked to your account." : "The sign-in was refused."
379
+ }));
380
+ return;
381
+ }
382
+ }
383
+ const file = /^\/files\/([0-9a-f]{64})$/.exec(path);
384
+ if (file && method === "PUT") {
385
+ await upload(request, response, file[1]);
386
+ return;
387
+ }
388
+ send(response, 404, {
389
+ code: "MOSTRA_HYGIENE_NOT_SERVED",
390
+ message: "Nothing is served at this path."
391
+ });
392
+ },
393
+ upgrade(request, socket, head, path) {
394
+ const refuse = (status, text, extra = "") => {
395
+ socket.end(`HTTP/1.1 ${status} ${text}\r\nconnection: close\r\ncontent-length: 0\r\n${extra}\r\n`);
396
+ };
397
+ if (path !== "/host") {
398
+ refuse(404, "Not Found");
399
+ return;
400
+ }
401
+ const who = bearer(request);
402
+ if (!who) {
403
+ refuse(401, "Unauthorized", `www-authenticate: Bearer resource_metadata="${apiOrigin}/.well-known/oauth-protected-resource/host"\r\n`);
404
+ return;
405
+ }
406
+ options.home(who.homeId).then((home) => {
407
+ sockets.handleUpgrade(request, socket, head, (ws) => {
408
+ bindings.add(ws);
409
+ let expiresAt = who.expiresAt;
410
+ const attributes = {
411
+ accountId: who.accountId,
412
+ grantId: who.grantId,
413
+ homeId: who.homeId,
414
+ linkId: who.linkId,
415
+ replaceToken: (next) => {
416
+ expiresAt = next;
417
+ }
418
+ };
419
+ const watch = setInterval(() => {
420
+ if (Date.now() >= expiresAt) {
421
+ log.info("binding.token_expired", { home: who.homeId });
422
+ ws.close(4401, "token expired");
423
+ } else if (!auth.grantLive(who.grantId)) {
424
+ log.info("binding.grant_revoked", { home: who.homeId });
425
+ ws.close(4403, "grant revoked");
426
+ }
427
+ }, Math.min(GRANT_RECHECK_MS, options.recheckMs ?? GRANT_RECHECK_MS));
428
+ watch.unref();
429
+ ws.once("close", () => {
430
+ clearInterval(watch);
431
+ bindings.delete(ws);
432
+ });
433
+ ws.on("message", () => options.touch(who.homeId));
434
+ serveWebSocket(home.protocol, ws, {
435
+ attributes,
436
+ log
437
+ });
438
+ log.info("binding.opened", {
439
+ home: who.homeId,
440
+ link: who.linkId
441
+ });
442
+ });
443
+ }, (error) => {
444
+ log.error("binding.home_failed", {
445
+ home: who.homeId,
446
+ error
447
+ });
448
+ refuse(503, "Service Unavailable");
449
+ });
450
+ },
451
+ close() {
452
+ for (const ws of bindings) ws.terminate();
453
+ sockets.close();
454
+ }
455
+ };
456
+ }
457
+ //#endregion
458
+ //#region src/server/auth.ts
459
+ /**
460
+ * The remote server's authorization server, as far as WP-29 builds it (INTERFACES §18.5, D165
461
+ * items 2, 8): the OAuth 2.0 device authorization grant (RFC 8628) behind `mostra login`, with
462
+ * rotating refresh tokens and revocation, and a development identity provider for tests and a
463
+ * self-hoster's first run. WP-30 adds the real identity providers, viewer sign-in and the MCP
464
+ * clients' flows on the same tables.
465
+ *
466
+ * Every token is an opaque random secret, stored only as its SHA-256 (DATA_MODEL §7.1): a copy of
467
+ * the directory grants nothing. Access tokens last an hour; a refresh token rotates on every use,
468
+ * returns the same successor for 30 s after it was used, so parallel refreshes don't collide, and a
469
+ * use after that revokes its grant. The device page says that approving links a machine to the
470
+ * account, and a new link is the hosted event `instance.linked`.
471
+ */
472
+ /** The CLI's client ID: a first-party public client (§18.5). */
473
+ const CLI_CLIENT_ID = "mostra-cli";
474
+ const ACCESS_TTL_MS = 36e5;
475
+ const REFRESH_TTL_MS = 7776e6;
476
+ const DEVICE_TTL_MS = 6e5;
477
+ const DEVICE_INTERVAL_S = 5;
478
+ const ROTATION_GRACE_MS = 3e4;
479
+ /** User codes: eight letters a person can't confuse (RFC 8628 §6.1), shown as `ABCD-EFGH`. */
480
+ const USER_CODE_LETTERS = "BCDFGHJKLMNPQRSTVWXZ";
481
+ /** The SHA-256 of a secret, as the directory stores it. */
482
+ function hashSecret(secret) {
483
+ return createHash("sha256").update(secret).digest("hex");
484
+ }
485
+ function secret() {
486
+ return randomBytes(32).toString("base64url");
487
+ }
488
+ function userCode() {
489
+ let code = "";
490
+ for (let index = 0; index < 8; index++) code += USER_CODE_LETTERS[randomInt(20)];
491
+ return code;
492
+ }
493
+ /** `abcd-efgh`, `ABCDEFGH` → `ABCDEFGH`. */
494
+ function normalizeUserCode(input) {
495
+ return input.toUpperCase().replace(/[^A-Z]/g, "");
496
+ }
497
+ function oauthError(status, error, description) {
498
+ return {
499
+ status,
500
+ error,
501
+ description
502
+ };
503
+ }
504
+ /** Creates the authorization server over the server's directory. */
505
+ function createAuthorization(options) {
506
+ const { directory, config, log } = options;
507
+ const now = options.now ?? (() => Date.now());
508
+ const accessTtlMs = options.accessTtlMs ?? ACCESS_TTL_MS;
509
+ const iso = (ms) => new Date(ms).toISOString();
510
+ const verificationUri = `${config.apiOrigin}/device`;
511
+ directory.write((db) => {
512
+ db.run("INSERT OR IGNORE INTO oauth_client (id, kind, metadata_json, created_at) VALUES (?, 'cli', ?, ?)", CLI_CLIENT_ID, JSON.stringify({ client_name: "Mostra CLI" }), iso(now()));
513
+ });
514
+ const deviceRow = (db, hash) => db.get("SELECT data_json, expires_at FROM token WHERE hash = ? AND kind = 'device'", hash);
515
+ /** The account for a sign-in identity, made on the first sign-in. */
516
+ const accountFor = (db, identity) => {
517
+ const found = db.get("SELECT account_id FROM identity WHERE provider = ? AND subject = ?", identity.provider, identity.subject);
518
+ if (found) return found.account_id;
519
+ const account = AccountId.create();
520
+ db.run("INSERT INTO account (id, name, status, created_at) VALUES (?, ?, 'active', ?)", account, identity.name ?? null, iso(now()));
521
+ db.run("INSERT INTO identity (provider, subject, account_id, name, linked_at) VALUES (?, ?, ?, ?, ?)", identity.provider, identity.subject, account, identity.name ?? null, iso(now()));
522
+ return account;
523
+ };
524
+ /** The account's hosted home, made on its first link (one home per owner per server). */
525
+ const homeFor = (db, account) => {
526
+ const found = db.get("SELECT id FROM home WHERE owner_account_id = ?", account);
527
+ if (found) return found.id;
528
+ const home = HomeId.create();
529
+ db.run("INSERT INTO home (id, owner_account_id, data_path, created_at) VALUES (?, ?, ?, ?)", home, account, `homes/${home}`, iso(now()));
530
+ return home;
531
+ };
532
+ /** Makes or binds again the instance link a sign-in names. */
533
+ const linkFor = (db, account, home, wanted, name) => {
534
+ if (wanted !== void 0 && LinkId.is(wanted)) {
535
+ if (db.get("SELECT account_id FROM instance_link WHERE id = ?", wanted)?.account_id === account) {
536
+ db.run("UPDATE instance_link SET revoked_at = NULL, name = ? WHERE id = ?", name, wanted);
537
+ return wanted;
538
+ }
539
+ }
540
+ const link = LinkId.create();
541
+ const first = db.get("SELECT COUNT(*) AS n FROM instance_link WHERE account_id = ?", account)?.n === 0;
542
+ db.run("INSERT INTO instance_link (id, account_id, home_id, name, is_default, relay_high, linked_at) VALUES (?, ?, ?, ?, ?, 0, ?)", link, account, home, name, first ? 1 : 0, iso(now()));
543
+ return link;
544
+ };
545
+ /** Issues an access and a refresh token for a grant. */
546
+ const issue = (db, grantId) => {
547
+ const access = secret();
548
+ const refresh = secret();
549
+ db.run("INSERT INTO token (hash, grant_id, kind, expires_at) VALUES (?, ?, 'access', ?)", hashSecret(access), grantId, iso(now() + accessTtlMs));
550
+ db.run("INSERT INTO token (hash, grant_id, kind, expires_at) VALUES (?, ?, 'refresh', ?)", hashSecret(refresh), grantId, iso(now() + REFRESH_TTL_MS));
551
+ return {
552
+ access,
553
+ refresh
554
+ };
555
+ };
556
+ const answer = (db, grantId, tokens) => {
557
+ const row = db.get(`SELECT g.account_id, g.link_id, a.name, l.is_default, l.home_id
558
+ FROM "grant" g JOIN account a ON a.id = g.account_id
559
+ LEFT JOIN instance_link l ON l.id = g.link_id WHERE g.id = ?`, grantId);
560
+ if (!row) throw new Error("grant vanished");
561
+ return {
562
+ access_token: tokens.access,
563
+ token_type: "Bearer",
564
+ expires_in: Math.max(1, Math.floor(accessTtlMs / 1e3)),
565
+ refresh_token: tokens.refresh,
566
+ scope: "mostra",
567
+ mostra_account: {
568
+ id: row.account_id,
569
+ ...row.name !== null ? { name: row.name } : {}
570
+ },
571
+ mostra_instance: row.link_id ?? "",
572
+ mostra_default: row.is_default === 1,
573
+ mostra_home: row.home_id ?? ""
574
+ };
575
+ };
576
+ /**
577
+ * The successors of refresh tokens used in the last 30 s, by the used token's hash: kept in
578
+ * memory only, so the directory never holds a usable secret. After a restart inside the grace, a
579
+ * repeated refresh is refused without revoking anything; the client still holds its successor.
580
+ */
581
+ const recent = /* @__PURE__ */ new Map();
582
+ const forgetOld = () => {
583
+ for (const [hash, entry] of recent) if (now() - entry.at > ROTATION_GRACE_MS) recent.delete(hash);
584
+ };
585
+ const grantLiveIn = (db, grantId) => {
586
+ const row = db.get("SELECT g.revoked_at, a.status FROM \"grant\" g JOIN account a ON a.id = g.account_id WHERE g.id = ?", grantId);
587
+ return row !== void 0 && row.revoked_at === null && row.status === "active";
588
+ };
589
+ return {
590
+ verificationUri,
591
+ device(form) {
592
+ if (form.get("client_id") !== "mostra-cli") return oauthError(401, "invalid_client", "Only the Mostra CLI uses the device grant here.");
593
+ if (!(form.get("scope") ?? "mostra").split(" ").every((part) => part === "mostra" || part === "offline_access")) return oauthError(400, "invalid_scope", "The only scope is mostra.");
594
+ const deviceCode = secret();
595
+ const code = userCode();
596
+ const instance = form.get("mostra_instance") ?? void 0;
597
+ const state = {
598
+ userCode: code,
599
+ status: "pending",
600
+ name: (form.get("mostra_name") ?? "").slice(0, 128) || "Mostra instance",
601
+ ...instance !== void 0 ? { instance } : {},
602
+ ...form.get("mostra_default") === "1" ? { makeDefault: true } : {}
603
+ };
604
+ directory.write((db) => db.run("INSERT INTO token (hash, kind, expires_at, data_json) VALUES (?, 'device', ?, ?)", hashSecret(deviceCode), iso(now() + DEVICE_TTL_MS), JSON.stringify(state)));
605
+ const shown = `${code.slice(0, 4)}-${code.slice(4)}`;
606
+ log.info("auth.device_started", {});
607
+ return {
608
+ device_code: deviceCode,
609
+ user_code: shown,
610
+ verification_uri: verificationUri,
611
+ verification_uri_complete: `${verificationUri}?user_code=${shown}`,
612
+ expires_in: Math.floor(DEVICE_TTL_MS / 1e3),
613
+ interval: DEVICE_INTERVAL_S
614
+ };
615
+ },
616
+ token(form) {
617
+ const grantType = form.get("grant_type");
618
+ if (form.get("client_id") !== "mostra-cli") return oauthError(401, "invalid_client", "Unknown client.");
619
+ if (grantType === "urn:ietf:params:oauth:grant-type:device_code") {
620
+ const hash = hashSecret(form.get("device_code") ?? "");
621
+ return directory.write((db) => {
622
+ const row = deviceRow(db, hash);
623
+ if (!row) return oauthError(400, "invalid_grant", "Unknown device code.");
624
+ if (Date.parse(row.expires_at) <= now()) return oauthError(400, "expired_token", "The code expired; sign in again.");
625
+ const state = JSON.parse(row.data_json);
626
+ if (state.status === "denied") return oauthError(400, "access_denied", "The sign-in was refused.");
627
+ if (state.status === "pending") {
628
+ const tooSoon = state.lastPollAt !== void 0 && now() - state.lastPollAt < DEVICE_INTERVAL_S * 1e3 - 250;
629
+ db.run("UPDATE token SET data_json = ? WHERE hash = ?", JSON.stringify({
630
+ ...state,
631
+ lastPollAt: now()
632
+ }), hash);
633
+ return tooSoon ? oauthError(400, "slow_down", "Poll less often.") : oauthError(400, "authorization_pending", "Waiting for the person to approve.");
634
+ }
635
+ const account = state.accountId;
636
+ const home = homeFor(db, account);
637
+ const link = linkFor(db, account, home, state.instance, state.name ?? "Mostra instance");
638
+ if (state.makeDefault === true) {
639
+ db.run("UPDATE instance_link SET is_default = 0 WHERE account_id = ? AND id != ?", account, link);
640
+ db.run("UPDATE instance_link SET is_default = 1 WHERE id = ?", link);
641
+ }
642
+ const grantId = `grt_${randomBytes(16).toString("hex")}`;
643
+ db.run("INSERT INTO \"grant\" (id, account_id, client_id, scope, resource, link_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)", grantId, account, CLI_CLIENT_ID, "mostra", `${config.apiOrigin}/host`, link, iso(now()));
644
+ db.run("DELETE FROM token WHERE hash = ?", hash);
645
+ const tokens = issue(db, grantId);
646
+ setImmediate(() => options.linked?.({
647
+ homeId: home,
648
+ linkId: link,
649
+ name: state.name ?? ""
650
+ }));
651
+ log.info("auth.linked", {
652
+ account,
653
+ home,
654
+ link
655
+ });
656
+ return answer(db, grantId, tokens);
657
+ });
658
+ }
659
+ if (grantType === "refresh_token") {
660
+ const hash = hashSecret(form.get("refresh_token") ?? "");
661
+ return directory.write((db) => {
662
+ const row = db.get("SELECT grant_id, expires_at, used_at FROM token WHERE hash = ? AND kind = 'refresh'", hash);
663
+ if (!row || !grantLiveIn(db, row.grant_id)) return oauthError(400, "invalid_grant", "The refresh token isn't valid; sign in again.");
664
+ if (Date.parse(row.expires_at) <= now()) return oauthError(400, "invalid_grant", "The refresh token expired; sign in again.");
665
+ if (row.used_at !== null) {
666
+ const used = Date.parse(row.used_at);
667
+ forgetOld();
668
+ if (now() - used <= ROTATION_GRACE_MS) {
669
+ const kept = recent.get(hash);
670
+ if (kept) return answer(db, row.grant_id, kept.tokens);
671
+ return oauthError(400, "invalid_grant", "This refresh token was just used; use its successor.");
672
+ }
673
+ db.run("UPDATE \"grant\" SET revoked_at = ? WHERE id = ?", iso(now()), row.grant_id);
674
+ log.warn("auth.refresh_reused", { grant: row.grant_id });
675
+ return oauthError(400, "invalid_grant", "The refresh token was used before; sign in again.");
676
+ }
677
+ const tokens = issue(db, row.grant_id);
678
+ db.run("UPDATE token SET used_at = ?, successor_hash = ? WHERE hash = ?", iso(now()), hashSecret(tokens.refresh), hash);
679
+ forgetOld();
680
+ recent.set(hash, {
681
+ tokens,
682
+ at: now()
683
+ });
684
+ return answer(db, row.grant_id, tokens);
685
+ });
686
+ }
687
+ return oauthError(400, "unsupported_grant_type", "Use the device grant or a refresh token.");
688
+ },
689
+ revoke(form) {
690
+ const hash = hashSecret(form.get("token") ?? "");
691
+ directory.write((db) => {
692
+ const row = db.get("SELECT grant_id FROM token WHERE hash = ?", hash);
693
+ if (row?.grant_id) {
694
+ db.run("UPDATE \"grant\" SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL", iso(now()), row.grant_id);
695
+ log.info("auth.revoked", { grant: row.grant_id });
696
+ }
697
+ });
698
+ },
699
+ authenticate(bearer) {
700
+ if (bearer.length < 20 || bearer.length > 200) return void 0;
701
+ const hash = hashSecret(bearer);
702
+ return directory.read((db) => {
703
+ const row = db.get(`SELECT t.hash, t.expires_at, t.grant_id, g.account_id, g.link_id, a.name
704
+ FROM token t JOIN "grant" g ON g.id = t.grant_id JOIN account a ON a.id = g.account_id
705
+ WHERE t.hash = ? AND t.kind = 'access'`, hash);
706
+ if (!row) return void 0;
707
+ if (!timingSafeEqual(Buffer.from(row.hash), Buffer.from(hash))) return void 0;
708
+ const expiresAt = Date.parse(row.expires_at);
709
+ if (expiresAt <= now() || !grantLiveIn(db, row.grant_id)) return void 0;
710
+ const home = db.get("SELECT id FROM home WHERE owner_account_id = ?", row.account_id);
711
+ if (!home) return void 0;
712
+ return {
713
+ accountId: row.account_id,
714
+ accountName: row.name ?? void 0,
715
+ grantId: row.grant_id,
716
+ homeId: home.id,
717
+ linkId: row.link_id ?? void 0,
718
+ expiresAt
719
+ };
720
+ });
721
+ },
722
+ grantLive(grantId) {
723
+ return directory.read((db) => grantLiveIn(db, grantId));
724
+ },
725
+ pendingCode(code) {
726
+ const wanted = normalizeUserCode(code);
727
+ return directory.read((db) => {
728
+ const row = db.all("SELECT data_json, expires_at FROM token WHERE kind = 'device' AND expires_at > ?", iso(now())).find((candidate) => JSON.parse(candidate.data_json).userCode === wanted);
729
+ if (!row) return {
730
+ ok: false,
731
+ reason: "That code is unknown or has expired."
732
+ };
733
+ return JSON.parse(row.data_json).status === "pending" ? { ok: true } : {
734
+ ok: false,
735
+ reason: "That code was already used."
736
+ };
737
+ });
738
+ },
739
+ decide(input) {
740
+ const wanted = normalizeUserCode(input.code);
741
+ return directory.write((db) => {
742
+ const row = db.all("SELECT hash, data_json FROM token WHERE kind = 'device' AND expires_at > ?", iso(now())).find((candidate) => JSON.parse(candidate.data_json).userCode === wanted);
743
+ if (!row) return {
744
+ ok: false,
745
+ reason: "That code is unknown or has expired."
746
+ };
747
+ const state = JSON.parse(row.data_json);
748
+ if (state.status !== "pending") return {
749
+ ok: false,
750
+ reason: "That code was already used."
751
+ };
752
+ if (!input.approve) {
753
+ db.run("UPDATE token SET data_json = ? WHERE hash = ?", JSON.stringify({
754
+ ...state,
755
+ status: "denied"
756
+ }), row.hash);
757
+ return { ok: true };
758
+ }
759
+ const account = accountFor(db, input.identity);
760
+ db.run("INSERT INTO consent (account_id, client_id, granted_at) VALUES (?, ?, ?) ON CONFLICT (account_id, client_id) DO UPDATE SET revoked_at = NULL", account, CLI_CLIENT_ID, iso(now()));
761
+ db.run("UPDATE token SET data_json = ? WHERE hash = ?", JSON.stringify({
762
+ ...state,
763
+ status: "approved",
764
+ accountId: account
765
+ }), row.hash);
766
+ return { ok: true };
767
+ });
768
+ }
769
+ };
770
+ }
771
+ //#endregion
772
+ //#region src/server/directory.ts
773
+ /** The server directory's migrations: their own list, apart from a home's. */
774
+ const SERVER_MIGRATIONS = [{
775
+ version: 1,
776
+ name: "server directory",
777
+ up(db) {
778
+ db.exec(`
779
+ CREATE TABLE account (
780
+ id TEXT PRIMARY KEY,
781
+ name TEXT,
782
+ status TEXT NOT NULL CHECK (status IN ('active', 'suspended')),
783
+ created_at TEXT NOT NULL
784
+ );
785
+ CREATE TABLE identity (
786
+ provider TEXT NOT NULL,
787
+ subject TEXT NOT NULL,
788
+ account_id TEXT NOT NULL REFERENCES account(id),
789
+ email TEXT,
790
+ name TEXT,
791
+ linked_at TEXT NOT NULL,
792
+ PRIMARY KEY (provider, subject)
793
+ );
794
+ CREATE TABLE home (
795
+ id TEXT PRIMARY KEY,
796
+ owner_account_id TEXT NOT NULL UNIQUE REFERENCES account(id),
797
+ data_path TEXT NOT NULL,
798
+ created_at TEXT NOT NULL,
799
+ suspended_at TEXT
800
+ );
801
+ CREATE TABLE instance_link (
802
+ id TEXT PRIMARY KEY,
803
+ account_id TEXT NOT NULL REFERENCES account(id),
804
+ home_id TEXT NOT NULL REFERENCES home(id),
805
+ name TEXT NOT NULL,
806
+ is_default INTEGER NOT NULL DEFAULT 0,
807
+ relay_high INTEGER NOT NULL DEFAULT 0,
808
+ linked_at TEXT NOT NULL,
809
+ revoked_at TEXT
810
+ );
811
+ CREATE UNIQUE INDEX instance_link_default ON instance_link(account_id) WHERE is_default = 1;
812
+ CREATE TABLE home_cursor (
813
+ home_id TEXT PRIMARY KEY REFERENCES home(id),
814
+ incarnation TEXT NOT NULL,
815
+ high_cursor INTEGER NOT NULL,
816
+ relay_high INTEGER NOT NULL,
817
+ updated_at TEXT NOT NULL
818
+ );
819
+ CREATE TABLE artifact_route (
820
+ id TEXT PRIMARY KEY,
821
+ home_id TEXT NOT NULL REFERENCES home(id),
822
+ artifact_id TEXT NOT NULL,
823
+ owner_link_id TEXT NOT NULL REFERENCES instance_link(id),
824
+ label TEXT NOT NULL UNIQUE,
825
+ created_at TEXT NOT NULL,
826
+ UNIQUE (home_id, artifact_id)
827
+ );
828
+ CREATE TABLE label_issued (
829
+ label TEXT PRIMARY KEY,
830
+ home_id TEXT NOT NULL,
831
+ route_id TEXT,
832
+ kind TEXT NOT NULL CHECK (kind IN ('server', 'operator')),
833
+ issued_at TEXT NOT NULL
834
+ );
835
+ -- A label is issued once, forever: never deleted, never moved to another home.
836
+ CREATE TRIGGER label_issued_kept BEFORE DELETE ON label_issued
837
+ BEGIN
838
+ SELECT RAISE(ABORT, 'an issued label is kept forever');
839
+ END;
840
+ CREATE TRIGGER label_issued_fixed BEFORE UPDATE ON label_issued
841
+ WHEN NEW.label IS NOT OLD.label OR NEW.home_id IS NOT OLD.home_id
842
+ BEGIN
843
+ SELECT RAISE(ABORT, 'an issued label never moves');
844
+ END;
845
+ CREATE TABLE home_file (
846
+ home_id TEXT NOT NULL REFERENCES home(id),
847
+ sha256 TEXT NOT NULL,
848
+ PRIMARY KEY (home_id, sha256)
849
+ );
850
+ CREATE TABLE file_ref (
851
+ sha256 TEXT PRIMARY KEY,
852
+ homes INTEGER NOT NULL CHECK (homes >= 0),
853
+ unreferenced_at TEXT
854
+ );
855
+ CREATE TABLE oauth_client (
856
+ id TEXT PRIMARY KEY,
857
+ kind TEXT NOT NULL CHECK (kind IN ('metadata', 'registered', 'shell', 'cli')),
858
+ metadata_json TEXT NOT NULL,
859
+ created_at TEXT NOT NULL,
860
+ last_used_at TEXT
861
+ );
862
+ CREATE TABLE consent (
863
+ account_id TEXT NOT NULL REFERENCES account(id),
864
+ client_id TEXT NOT NULL REFERENCES oauth_client(id),
865
+ granted_at TEXT NOT NULL,
866
+ revoked_at TEXT,
867
+ PRIMARY KEY (account_id, client_id)
868
+ );
869
+ CREATE TABLE sender_shown (
870
+ account_id TEXT NOT NULL,
871
+ home_id TEXT NOT NULL,
872
+ at TEXT NOT NULL,
873
+ PRIMARY KEY (account_id, home_id)
874
+ );
875
+ CREATE TABLE "grant" (
876
+ id TEXT PRIMARY KEY,
877
+ account_id TEXT NOT NULL REFERENCES account(id),
878
+ client_id TEXT NOT NULL REFERENCES oauth_client(id),
879
+ scope TEXT NOT NULL,
880
+ resource TEXT NOT NULL,
881
+ link_id TEXT REFERENCES instance_link(id),
882
+ created_at TEXT NOT NULL,
883
+ revoked_at TEXT
884
+ );
885
+ CREATE TABLE token (
886
+ hash TEXT PRIMARY KEY,
887
+ grant_id TEXT REFERENCES "grant"(id),
888
+ kind TEXT NOT NULL CHECK (kind IN ('access', 'refresh', 'device', 'code')),
889
+ expires_at TEXT NOT NULL,
890
+ used_at TEXT,
891
+ successor_hash TEXT,
892
+ data_json TEXT
893
+ );
894
+ CREATE TABLE outbound (
895
+ id TEXT PRIMARY KEY,
896
+ port TEXT NOT NULL CHECK (port IN ('metering', 'events')),
897
+ payload_json TEXT NOT NULL,
898
+ attempts INTEGER NOT NULL DEFAULT 0,
899
+ next_attempt_at TEXT NOT NULL
900
+ );
901
+ `);
902
+ }
903
+ }];
904
+ //#endregion
905
+ //#region src/server/data.ts
906
+ /**
907
+ * A remote server's data directory (DATA_MODEL §7.1) and its hosted homes (§7.2, D165 items 0b,
908
+ * 6): the directory is refused on a network filesystem, held by `server.lock` so a second server
909
+ * refuses it, and its directory ledger `server.sqlite` opens in WAL with normal locking. Each
910
+ * hosted home opens on its first request (its own `home.lock`, its ledger in normal locking, so a
911
+ * backup replicator can read it) and closes after it has been idle a while. Opening and closing one
912
+ * home are serialized, so a home never has two writers in one process, and a request that meets a
913
+ * home being closed waits for the close and opens it again (FAILURE_MODEL §11.2).
914
+ */
915
+ /** A home's head and relay high-water mark, as `home_cursor` records them (DATA_MODEL §7.1). */
916
+ function marksOf(ledger) {
917
+ return ledger.read((db) => ({
918
+ head: db.get("SELECT MAX(cursor) AS head FROM event")?.head ?? 0,
919
+ relayHigh: db.get("SELECT MAX(relay_seq) AS high FROM relay_run")?.high ?? 0
920
+ }));
921
+ }
922
+ /** A fresh incarnation, written in the one transaction that rotates it (DATA_MODEL §7.2). */
923
+ function rotateIncarnation(ledger) {
924
+ const fresh = randomBytes(16).toString("hex");
925
+ ledger.write((db) => db.run("UPDATE home_meta SET incarnation = ? WHERE id = 1", fresh));
926
+ return fresh;
927
+ }
928
+ function locked(message) {
929
+ return new RpcError(createDiagnostic("MOSTRA_HOME_LOCKED", { message }));
930
+ }
931
+ /**
932
+ * Refuses a data directory on a network filesystem (`MOSTRA_HOME_NETWORK_FILESYSTEM`), before
933
+ * anything in it is opened. `MOSTRA_TEST_NETWORK_FILESYSTEM` names a directory tests treat as one,
934
+ * since no test machine mounts NFS.
935
+ */
936
+ function refuseNetworkFilesystem(dir, env) {
937
+ const testing = env["MOSTRA_TEST_NETWORK_FILESYSTEM"];
938
+ const found = testing !== void 0 && testing !== "" && dir.startsWith(testing) ? "nfs (test)" : networkFilesystem(dir);
939
+ if (found !== void 0) throw new RpcError(createDiagnostic("MOSTRA_HOME_NETWORK_FILESYSTEM", { message: `The data directory ${dir} is on a network filesystem (${found}); a remote server's homes need a local disk.` }));
940
+ }
941
+ /** Opens and holds a server's data directory. Throws `MOSTRA_HOME_LOCKED` when another server holds it. */
942
+ async function openDataDirectory(options) {
943
+ const { dir, log } = options;
944
+ mkdirSync(dir, {
945
+ recursive: true,
946
+ mode: 448
947
+ });
948
+ ownedDirectory(dir);
949
+ refuseNetworkFilesystem(dir, options.env);
950
+ const serverLock = holdLock(join(dir, "server.lock"), options.owner);
951
+ if (!serverLock) throw locked(`Another server process holds the data directory ${dir} (server.lock).`);
952
+ let directory;
953
+ try {
954
+ const opening = openLedger({
955
+ storeDir: dir,
956
+ fileName: "server.sqlite",
957
+ runtimeVersion: options.runtimeVersion,
958
+ owner: options.owner,
959
+ log,
960
+ migrations: SERVER_MIGRATIONS,
961
+ locking: "normal",
962
+ ...options.walAutocheckpoint !== void 0 ? { walAutocheckpoint: options.walAutocheckpoint } : {}
963
+ });
964
+ if (!opening.ok) throw locked(`server.sqlite in ${dir} is locked by another process.`);
965
+ directory = opening.ledger;
966
+ } catch (error) {
967
+ serverLock.release();
968
+ throw error;
969
+ }
970
+ mkdirSync(join(dir, "homes"), {
971
+ recursive: true,
972
+ mode: 448
973
+ });
974
+ mkdirSync(join(dir, "files"), {
975
+ recursive: true,
976
+ mode: 448
977
+ });
978
+ mkdirSync(join(dir, "keys"), {
979
+ recursive: true,
980
+ mode: 448
981
+ });
982
+ const entries = /* @__PURE__ */ new Map();
983
+ /** `--restored`'s homes not opened since this server started. */
984
+ const restores = new Set(options.restored ?? []);
985
+ /** Writes a home's high-water marks, which a home opened below them was restored. */
986
+ const recordCursor = (id, ledger, incarnation) => {
987
+ const { head, relayHigh } = marksOf(ledger);
988
+ directory.write((db) => db.run(`INSERT INTO home_cursor (home_id, incarnation, high_cursor, relay_high, updated_at)
989
+ VALUES (?, ?, ?, ?, ?)
990
+ ON CONFLICT(home_id) DO UPDATE SET incarnation = excluded.incarnation,
991
+ high_cursor = excluded.high_cursor, relay_high = excluded.relay_high,
992
+ updated_at = excluded.updated_at`, id, incarnation, head, relayHigh, (/* @__PURE__ */ new Date()).toISOString()));
993
+ };
994
+ const idleCloseMs = options.idleCloseMs ?? 6e5;
995
+ let closed = false;
996
+ const openHome = async (id) => {
997
+ const row = directory.read((db) => db.get("SELECT data_path FROM home WHERE id = ?", id));
998
+ if (!row) throw new RpcError(createDiagnostic("MOSTRA_HOST_INVALID_PARAMS", { message: `No hosted home ${id}.` }));
999
+ const homeDir = join(dir, row.data_path);
1000
+ mkdirSync(homeDir, {
1001
+ recursive: true,
1002
+ mode: 448
1003
+ });
1004
+ const lock = holdLock(join(homeDir, "home.lock"), options.owner);
1005
+ if (!lock) throw locked(`Another process holds the hosted home ${id} (home.lock).`);
1006
+ try {
1007
+ const opening = openLedger({
1008
+ storeDir: join(homeDir, "store"),
1009
+ runtimeVersion: options.runtimeVersion,
1010
+ owner: options.owner,
1011
+ log,
1012
+ locking: "normal",
1013
+ ...options.walAutocheckpoint !== void 0 ? { walAutocheckpoint: options.walAutocheckpoint } : {}
1014
+ });
1015
+ if (!opening.ok) throw locked(`The hosted home ${id}'s ledger is locked by another process.`);
1016
+ const ledger = opening.ledger;
1017
+ const stored = ledger.write((db) => {
1018
+ const meta = db.get("SELECT incarnation FROM home_meta WHERE id = 1");
1019
+ if (meta) return meta.incarnation;
1020
+ const fresh = randomBytes(16).toString("hex");
1021
+ db.run("INSERT INTO home_meta (id, incarnation, created_at) VALUES (1, ?, ?)", fresh, (/* @__PURE__ */ new Date()).toISOString());
1022
+ return fresh;
1023
+ });
1024
+ const recorded = directory.read((db) => db.get("SELECT high_cursor, relay_high FROM home_cursor WHERE home_id = ?", id));
1025
+ const marks = marksOf(ledger);
1026
+ const byHand = restores.has(id) || restores.has("all");
1027
+ restores.delete(id);
1028
+ const below = recorded !== void 0 && (marks.head < recorded.high_cursor || marks.relayHigh < recorded.relay_high);
1029
+ const incarnation = byHand || below ? rotateIncarnation(ledger) : stored;
1030
+ if (incarnation !== stored) log.warn("server.home_rotated", {
1031
+ home: id,
1032
+ why: byHand ? "restored" : "below-mark"
1033
+ });
1034
+ recordCursor(id, ledger, incarnation);
1035
+ try {
1036
+ const assembled = await options.assembler.assemble({
1037
+ id,
1038
+ dir: homeDir,
1039
+ ledger,
1040
+ incarnation
1041
+ });
1042
+ const entry = entries.get(id);
1043
+ if (entry) {
1044
+ entry.lock = lock;
1045
+ entry.ledger = ledger;
1046
+ entry.incarnation = () => options.assembler.incarnation?.(assembled) ?? incarnation;
1047
+ }
1048
+ log.info("server.home_opened", { home: id });
1049
+ return {
1050
+ id,
1051
+ dir: homeDir,
1052
+ ledger,
1053
+ incarnation,
1054
+ assembled
1055
+ };
1056
+ } catch (error) {
1057
+ ledger.close();
1058
+ throw error;
1059
+ }
1060
+ } catch (error) {
1061
+ lock.release();
1062
+ throw error;
1063
+ }
1064
+ };
1065
+ const closeHome = async (id, entry) => {
1066
+ const opened = await entry.opening.catch(() => void 0);
1067
+ if (opened) {
1068
+ try {
1069
+ recordCursor(id, opened.ledger, entry.incarnation?.() ?? opened.incarnation);
1070
+ } catch (error) {
1071
+ log.warn("server.home_cursor_failed", {
1072
+ home: id,
1073
+ error
1074
+ });
1075
+ }
1076
+ await options.assembler.disassemble(opened.assembled).catch((error) => log.warn("server.home_disassemble_failed", {
1077
+ home: id,
1078
+ error
1079
+ }));
1080
+ opened.ledger.close();
1081
+ }
1082
+ entry.lock?.release();
1083
+ entries.delete(id);
1084
+ log.info("server.home_closed", { home: id });
1085
+ };
1086
+ const sweep = setInterval(() => {
1087
+ const now = Date.now();
1088
+ for (const [id, entry] of entries) {
1089
+ if (entry.closing || now - entry.lastUsed < idleCloseMs) continue;
1090
+ entry.opening.then((opened) => {
1091
+ if (options.assembler.busy(opened.assembled) || entry.closing) return;
1092
+ if (Date.now() - entry.lastUsed < idleCloseMs) return;
1093
+ entry.closing = closeHome(id, entry);
1094
+ }, () => {
1095
+ entries.delete(id);
1096
+ });
1097
+ }
1098
+ }, Math.min(3e4, Math.max(50, idleCloseMs / 4)));
1099
+ sweep.unref();
1100
+ const marker = setInterval(() => {
1101
+ for (const [id, entry] of entries) {
1102
+ if (!entry.ledger || entry.closing) continue;
1103
+ try {
1104
+ recordCursor(id, entry.ledger, entry.incarnation?.() ?? "");
1105
+ } catch (error) {
1106
+ log.warn("server.home_cursor_failed", {
1107
+ home: id,
1108
+ error
1109
+ });
1110
+ }
1111
+ }
1112
+ }, 1e4);
1113
+ marker.unref();
1114
+ return {
1115
+ dir,
1116
+ directory,
1117
+ async home(id) {
1118
+ if (closed) throw locked("The server is stopping.");
1119
+ for (;;) {
1120
+ const entry = entries.get(id);
1121
+ if (entry?.closing) {
1122
+ await entry.closing;
1123
+ continue;
1124
+ }
1125
+ if (entry) {
1126
+ entry.lastUsed = Date.now();
1127
+ return entry.opening;
1128
+ }
1129
+ const fresh = {
1130
+ opening: openHome(id),
1131
+ lastUsed: Date.now()
1132
+ };
1133
+ entries.set(id, fresh);
1134
+ fresh.opening.catch(() => {
1135
+ if (entries.get(id) === fresh) entries.delete(id);
1136
+ });
1137
+ return fresh.opening;
1138
+ }
1139
+ },
1140
+ open: () => [...entries.keys()],
1141
+ touch(id) {
1142
+ const entry = entries.get(id);
1143
+ if (entry) entry.lastUsed = Date.now();
1144
+ },
1145
+ async close() {
1146
+ if (closed) return;
1147
+ closed = true;
1148
+ clearInterval(sweep);
1149
+ clearInterval(marker);
1150
+ for (const [id, entry] of [...entries]) {
1151
+ entry.closing ??= closeHome(id, entry);
1152
+ await entry.closing;
1153
+ }
1154
+ directory.close();
1155
+ serverLock.release();
1156
+ }
1157
+ };
1158
+ }
1159
+ //#endregion
1160
+ //#region src/server/relay.ts
1161
+ /**
1162
+ * The relay on a hosted home (D117, D165 item 4; ARCHITECTURE §15.5, INTERFACES §18.3, FAILURE_MODEL
1163
+ * §11.1): a hosted page's runs and plain calls run on the artifact's owner instance, over that
1164
+ * instance's binding. The hosted home records each run as a local instance does, then sends it to
1165
+ * the owner, which records it under the same ID, runs it in its own pool with its own secrets and
1166
+ * reports its progress, log, result and end back (`relay/run.update`). While the owner is away a
1167
+ * run waits (`waiting`), as the artifact's offline policy says, in a capped queue that drains in
1168
+ * order at a bounded rate when the owner returns; after every reconnect, before anything drains,
1169
+ * the runs the owner accepted and hasn't finished are reconciled with it. A run whose end the owner
1170
+ * never reported within the offline limit becomes `unknown`, never `failed`, since it may have
1171
+ * taken effect; the owner's later report replaces it once.
1172
+ *
1173
+ * Plain calls aren't durable: they go out only while the owner is connected.
1174
+ */
1175
+ /** How long a relay port call may take: the owner answers once it recorded the run. */
1176
+ const PORT_CALL_MS = 3e4;
1177
+ /** How long a run its connected owner never acknowledged waits before it is sent again. */
1178
+ const RESEND_MS = 35e3;
1179
+ /** Failures of the connection rather than answers of the owner: the run may yet be recorded. */
1180
+ const TRANSPORT_FAILURES = /* @__PURE__ */ new Set(["MOSTRA_HOST_CONNECTION_CLOSED", "MOSTRA_HOST_TIMEOUT"]);
1181
+ function failed(code, message) {
1182
+ return new RpcError(createDiagnostic(code, { message }));
1183
+ }
1184
+ const iso = (ms) => new Date(ms).toISOString();
1185
+ /** Creates a hosted home's relay. */
1186
+ function createHostedRelay(options) {
1187
+ const { ledger, interaction, bus, log } = options;
1188
+ const now = options.now ?? Date.now;
1189
+ const cap = options.waitingRunsPerArtifact ?? 100;
1190
+ const drainPerSecond = Math.max(1, options.drainPerSecond ?? 2);
1191
+ const calls = /* @__PURE__ */ new Map();
1192
+ /** Owner links whose reconcile finished on their current session: only then may runs go out. */
1193
+ const ready = /* @__PURE__ */ new Map();
1194
+ /** Runs being sent now, so a sweep or a second drain never sends one twice at once. */
1195
+ const sending = /* @__PURE__ */ new Set();
1196
+ /** When each run was last sent, for the sweep's resend while the owner stays connected. */
1197
+ const lastTry = /* @__PURE__ */ new Map();
1198
+ const draining = /* @__PURE__ */ new Set();
1199
+ const versions = /* @__PURE__ */ new Map();
1200
+ /**
1201
+ * The highest relay sequence each owner link's ledger has accepted, as its sessions report it
1202
+ * (`relayMark`): a home restored from a backup continues above it, so no sequence is reused.
1203
+ */
1204
+ const marks = /* @__PURE__ */ new Map();
1205
+ /** The relay mark each open owner session reported, for a resume run again for it. */
1206
+ const sessionMarks = /* @__PURE__ */ new Map();
1207
+ /** A resume that failed is tried again for its session, with backoff (Opus review of WP-29, 1). */
1208
+ const retries = /* @__PURE__ */ new Map();
1209
+ let stopped = false;
1210
+ const versionOf = (versionId) => {
1211
+ const known = versions.get(versionId);
1212
+ if (known) return known;
1213
+ const manifestJson = ledger.read((db) => db.get("SELECT manifest_json FROM version WHERE id = ?", versionId)?.manifest_json);
1214
+ const manifest = manifestJson ? ArtifactManifest.safeParse(JSON.parse(manifestJson)).data : void 0;
1215
+ const offline = manifest?.hosted?.offline;
1216
+ const version = {
1217
+ functions: options.functions(versionId),
1218
+ policy: offline?.actions ?? "queue",
1219
+ limitMs: durationMs(offline?.limit ?? HOSTED_OFFLINE_LIMIT_DEFAULT),
1220
+ who: manifest?.hosted?.actions ?? "signed-in"
1221
+ };
1222
+ versions.set(versionId, version);
1223
+ return version;
1224
+ };
1225
+ const functionOf = (versionId, fnId) => {
1226
+ const version = versionOf(versionId);
1227
+ if (!version.functions.has(fnId)) throw failed("MOSTRA_ACTION_UNKNOWN_FUNCTION", `This version has no server function ${fnId.slice(0, 200)}.`);
1228
+ return version;
1229
+ };
1230
+ /**
1231
+ * D159: a relayed action runs on its owner's machine with its owner's secrets, so by default
1232
+ * only a signed-in viewer or an expected respondent (a link minted for a named person) may
1233
+ * trigger one; `hosted.actions: "link"` opens it to anyone holding a link with the scope.
1234
+ * Refused before anything is recorded or relayed.
1235
+ */
1236
+ const mayTrigger = (viewerId, version) => {
1237
+ if (version.who === "link") return;
1238
+ const viewer = interaction.viewer(viewerId);
1239
+ const named = viewer.kind === "token" && viewer.ref !== void 0 && !viewer.ref.startsWith("link:");
1240
+ if (viewer.kind === "account" || named) return;
1241
+ throw failed("MOSTRA_REMOTE_SIGN_IN_REQUIRED", "Only signed-in viewers can run this page's actions; sign in, or ask its owner for a link of your own.");
1242
+ };
1243
+ /** Each link's recent relayed runs and calls, for the per-link limit. */
1244
+ const linkUses = /* @__PURE__ */ new Map();
1245
+ /**
1246
+ * Counts a relayed run or call against its link (D159), refusing it past the limit with
1247
+ * `MOSTRA_REMOTE_RATE_LIMITED` and when to try again. A request that joins a run already
1248
+ * recorded (its client key, or its key) starts nothing, so it is never counted.
1249
+ */
1250
+ const limitLink = (tokenId, artifactId, input) => {
1251
+ const limit = options.perLink;
1252
+ if (!limit || tokenId === void 0) return;
1253
+ if (artifactId !== void 0 && input !== void 0) {
1254
+ if (ledger.read((db) => db.get("SELECT 1 FROM action_run WHERE artifact_id = ? AND (client_key = ? OR (key IS NOT NULL AND key = ? AND action = ?))", artifactId, input.clientKey, input.key ?? null, input.fnId) !== void 0)) return;
1255
+ }
1256
+ const at = now();
1257
+ const recent = (linkUses.get(tokenId) ?? []).filter((used) => at - used < limit.perMs);
1258
+ if (recent.length >= limit.count) {
1259
+ const retryAfter = Math.max(1, Math.ceil((recent[0] + limit.perMs - at) / 1e3));
1260
+ const error = failed("MOSTRA_REMOTE_RATE_LIMITED", `This link ran ${limit.count} actions recently; try again in ${retryAfter} s.`);
1261
+ error.retryAfter = retryAfter;
1262
+ linkUses.set(tokenId, recent);
1263
+ throw error;
1264
+ }
1265
+ recent.push(at);
1266
+ linkUses.set(tokenId, recent);
1267
+ };
1268
+ const checkArgs = (args) => {
1269
+ if (JSON.stringify(args).length > ACTION_ARGS_MAX) throw failed("MOSTRA_ACTION_TOO_LARGE", "The serialized arguments are larger than 16 MiB; pass less data, such as identifiers.");
1270
+ try {
1271
+ checkArgumentFrames(args);
1272
+ } catch (error) {
1273
+ throw failed("MOSTRA_ACTION_UNSERIALIZABLE", error.message);
1274
+ }
1275
+ };
1276
+ /** Tells a run's views what changed: the state as a delta from nothing held. */
1277
+ const publish = (state, artifactId) => bus.publishRun(artifactId, {
1278
+ kind: "run",
1279
+ run: {
1280
+ runId: state.runId,
1281
+ status: state.status,
1282
+ ...state.reason !== void 0 ? { reason: state.reason } : {},
1283
+ ...state.progress ? { progress: state.progress } : {},
1284
+ logFrom: state.logFrom ?? 0,
1285
+ log: state.log,
1286
+ batchFrom: state.batchFrom ?? 0,
1287
+ batches: state.batches,
1288
+ ...state.error ? { error: state.error } : {},
1289
+ ...state.finishedAt ? { finishedAt: state.finishedAt } : {}
1290
+ }
1291
+ });
1292
+ const relayRow = (db, runId) => db.get("SELECT * FROM relay_run WHERE run_id = ?", runId);
1293
+ const runRow = (db, runId) => db.get("SELECT * FROM action_run WHERE id = ?", runId);
1294
+ /** Whether the owner of a run's artifact is connected and reconciled. */
1295
+ const sessionFor = (linkId) => {
1296
+ const session = options.sessionOf(linkId);
1297
+ return session !== void 0 && ready.get(linkId) === session ? session : void 0;
1298
+ };
1299
+ /** The owner never heard the run: it ends `failed` with reason `owner-offline` (never sent). */
1300
+ const endOffline = (runId) => {
1301
+ const state = ledger.write((db) => {
1302
+ const row = runRow(db, runId);
1303
+ if (!row || isFinalRunStatus(row.status) || row.status === "unknown") return void 0;
1304
+ const ended = finishRun(db, runId, {
1305
+ status: "failed",
1306
+ reason: "owner-offline",
1307
+ error: {
1308
+ code: "MOSTRA_REMOTE_OWNER_OFFLINE",
1309
+ message: "The page's owner was offline, so the action never ran."
1310
+ }
1311
+ });
1312
+ return ended ? {
1313
+ state: runState(db, ended),
1314
+ artifactId: ended.artifact_id
1315
+ } : void 0;
1316
+ });
1317
+ if (state) publish(state.state, state.artifactId);
1318
+ };
1319
+ /** Sends one run to its owner; the answer records that the owner holds it. */
1320
+ const send = async (runId, session) => {
1321
+ if (sending.has(runId)) return;
1322
+ const prepared = ledger.write((db) => {
1323
+ const relay = relayRow(db, runId);
1324
+ const row = runRow(db, runId);
1325
+ if (!relay || !row || isFinalRunStatus(row.status) || row.status === "unknown") return void 0;
1326
+ if (relay.sent_at === null && Date.parse(relay.offline_limit_at) <= now()) return "expired";
1327
+ db.run("UPDATE relay_run SET attempt = attempt + 1, sent_at = COALESCE(sent_at, ?) WHERE run_id = ?", iso(now()), runId);
1328
+ return {
1329
+ relay,
1330
+ row
1331
+ };
1332
+ });
1333
+ if (!prepared) return;
1334
+ if (prepared === "expired") {
1335
+ endOffline(runId);
1336
+ return;
1337
+ }
1338
+ const { relay, row } = prepared;
1339
+ sending.add(runId);
1340
+ try {
1341
+ const viewer = row.viewer_id ? interaction.viewer(row.viewer_id) : void 0;
1342
+ await options.call(session, portRelayRunMethod.method, {
1343
+ runId,
1344
+ seq: relay.relay_seq,
1345
+ artifactId: row.artifact_id,
1346
+ versionId: row.version_id,
1347
+ fnId: row.action,
1348
+ args: JSON.parse(row.args_json),
1349
+ ...row.key !== null ? { key: row.key } : {},
1350
+ ...viewer ? { viewer: {
1351
+ id: viewer.id,
1352
+ ...viewer.name ? { name: viewer.name } : {}
1353
+ } } : {},
1354
+ ...row.view_id !== null ? { viewId: row.view_id } : {}
1355
+ }, PORT_CALL_MS);
1356
+ const at = iso(now());
1357
+ if (ledger.write((db) => {
1358
+ db.run("UPDATE relay_run SET accepted_at = COALESCE(accepted_at, ?), owner_heard_at = ? WHERE run_id = ?", at, at, runId);
1359
+ return relayRow(db, runId)?.cancel_requested_at ?? null;
1360
+ }) !== null) cancelOnOwner(runId, session);
1361
+ } catch (error) {
1362
+ const code = error instanceof RpcError ? error.diagnostic.code : void 0;
1363
+ if (code !== void 0 && !TRANSPORT_FAILURES.has(code)) refused(runId, error.diagnostic);
1364
+ else log.warn("relay.send_failed", {
1365
+ runId,
1366
+ error
1367
+ });
1368
+ } finally {
1369
+ lastTry.set(runId, now());
1370
+ sending.delete(runId);
1371
+ }
1372
+ };
1373
+ /** A run its owner refused before recording it ends failed, with the owner's diagnostic. */
1374
+ const refused = (runId, diagnostic) => {
1375
+ log.warn("relay.run_refused", {
1376
+ runId,
1377
+ code: diagnostic.code
1378
+ });
1379
+ const ended = ledger.write((db) => {
1380
+ const row = runRow(db, runId);
1381
+ if (!row || isFinalRunStatus(row.status) || row.status === "unknown") return void 0;
1382
+ const done = finishRun(db, runId, {
1383
+ status: "failed",
1384
+ reason: "owner-refused",
1385
+ error: {
1386
+ code: diagnostic.code,
1387
+ message: diagnostic.message
1388
+ }
1389
+ });
1390
+ return done ? {
1391
+ state: runState(db, done),
1392
+ artifactId: done.artifact_id
1393
+ } : void 0;
1394
+ });
1395
+ if (ended) publish(ended.state, ended.artifactId);
1396
+ };
1397
+ const cancelOnOwner = async (runId, session) => {
1398
+ try {
1399
+ await options.call(session, portRelayCancelMethod.method, { runId }, PORT_CALL_MS);
1400
+ ledger.write((db) => db.run("UPDATE relay_run SET cancel_requested_at = NULL WHERE run_id = ?", runId));
1401
+ } catch (error) {
1402
+ log.warn("relay.cancel_failed", {
1403
+ runId,
1404
+ error
1405
+ });
1406
+ }
1407
+ };
1408
+ /**
1409
+ * Applies a run's state as the owner reports it, from what the hosted home holds on: new log
1410
+ * lines and batches by position, `running`, and the end (which replaces `unknown` once).
1411
+ */
1412
+ const apply = (runId, report) => {
1413
+ const state = ledger.write((db) => {
1414
+ const row = runRow(db, runId);
1415
+ if (!row || isFinalRunStatus(row.status)) return void 0;
1416
+ db.run("UPDATE relay_run SET owner_heard_at = ? WHERE run_id = ?", iso(now()), runId);
1417
+ if (report.logFrom !== void 0 && report.logFrom > row.log_lines || report.batchFrom !== void 0 && report.batchFrom > row.batches) return "gap";
1418
+ if ((report.running || report.log || report.batches || report.end) && row.status !== "unknown") markRunning(db, runId);
1419
+ const lines = report.log ?? [];
1420
+ const linesFrom = report.logFrom ?? row.log_lines;
1421
+ const freshLines = linesFrom <= row.log_lines ? lines.slice(row.log_lines - linesFrom) : [];
1422
+ const batches = report.batches ?? [];
1423
+ const batchesFrom = report.batchFrom ?? row.batches;
1424
+ const freshBatches = batchesFrom <= row.batches ? batches.slice(row.batches - batchesFrom) : [];
1425
+ if (freshLines.length > 0 || freshBatches.length > 0 || report.progress) appendRunOutput(db, runId, {
1426
+ lines: freshLines,
1427
+ batches: freshBatches,
1428
+ ...report.progress ? { progress: report.progress } : {}
1429
+ });
1430
+ if (report.end) finishRun(db, runId, {
1431
+ status: report.end.status,
1432
+ ...report.end.reason !== void 0 ? { reason: report.end.reason } : {},
1433
+ ...report.end.error ? { error: report.end.error } : {}
1434
+ });
1435
+ const after = runRow(db, runId);
1436
+ return after ? {
1437
+ state: runState(db, after),
1438
+ artifactId: after.artifact_id
1439
+ } : void 0;
1440
+ });
1441
+ if (state === "gap") {
1442
+ log.warn("relay.update_gap", { runId });
1443
+ catchUp(runId);
1444
+ return;
1445
+ }
1446
+ if (state) publish(state.state, state.artifactId);
1447
+ };
1448
+ /** Runs being asked for again after a gap, so one gap asks once. */
1449
+ const catchingUp = /* @__PURE__ */ new Set();
1450
+ /** Asks the owner for one run's state from what this home holds (a reconcile of that run). */
1451
+ const catchUp = async (runId) => {
1452
+ if (catchingUp.has(runId)) return;
1453
+ catchingUp.add(runId);
1454
+ try {
1455
+ const entry = ledger.read((db) => {
1456
+ const relay = relayRow(db, runId);
1457
+ const run = runRow(db, runId);
1458
+ return relay && run ? {
1459
+ relay,
1460
+ run
1461
+ } : void 0;
1462
+ });
1463
+ if (!entry) return;
1464
+ const session = sessionFor(entry.relay.owner_link_id);
1465
+ if (session === void 0) return;
1466
+ const answer = await options.call(session, portRelayReconcileMethod.method, {
1467
+ runs: [runId],
1468
+ held: [{
1469
+ runId,
1470
+ log: entry.run.log_lines,
1471
+ batches: entry.run.batches
1472
+ }]
1473
+ }, PORT_CALL_MS);
1474
+ for (const reconciled of answer.runs) applyReconciled(reconciled);
1475
+ } catch (error) {
1476
+ log.warn("relay.catch_up_failed", {
1477
+ runId,
1478
+ error
1479
+ });
1480
+ } finally {
1481
+ catchingUp.delete(runId);
1482
+ }
1483
+ };
1484
+ /** Applies the owner's answer for one run of a reconcile. */
1485
+ const applyReconciled = (entry) => {
1486
+ if (entry.state === "unknown-to-owner") {
1487
+ unknown(entry.runId);
1488
+ return;
1489
+ }
1490
+ const state = entry.state;
1491
+ apply(entry.runId, {
1492
+ running: state.status !== "queued",
1493
+ ...state.progress ? { progress: state.progress } : {},
1494
+ log: state.log,
1495
+ logFrom: state.logFrom ?? 0,
1496
+ batches: state.batches,
1497
+ batchFrom: state.batchFrom ?? 0,
1498
+ ...state.status === "succeeded" || state.status === "failed" || state.status === "cancelled" ? { end: {
1499
+ status: state.status,
1500
+ ...state.reason !== void 0 ? { reason: state.reason } : {},
1501
+ ...state.error ? { error: state.error } : {}
1502
+ } } : {}
1503
+ });
1504
+ };
1505
+ /** Moves a run to `unknown`, and tells its views. */
1506
+ const unknown = (runId) => {
1507
+ const state = ledger.write((db) => {
1508
+ if (!markUnknown(db, runId)) return void 0;
1509
+ const row = runRow(db, runId);
1510
+ return row ? {
1511
+ state: runState(db, row),
1512
+ artifactId: row.artifact_id
1513
+ } : void 0;
1514
+ });
1515
+ if (state) publish(state.state, state.artifactId);
1516
+ };
1517
+ /**
1518
+ * The runs of a link the owner accepted and the hosted home holds no end for, and every run sent
1519
+ * that became `unknown` (its acknowledgement may have been lost): the owner's report replaces
1520
+ * `unknown` once, and asking starts nothing (Opus review of WP-29, 8).
1521
+ */
1522
+ const acceptedOpen = (linkId) => ledger.read((db) => db.all(`SELECT r.*, a.status FROM relay_run r JOIN action_run a ON a.id = r.run_id
1523
+ WHERE r.owner_link_id = ?
1524
+ AND ((r.accepted_at IS NOT NULL AND a.status IN ('queued', 'running', 'waiting'))
1525
+ OR (r.sent_at IS NOT NULL AND a.status = 'unknown'))
1526
+ ORDER BY r.relay_seq`, linkId).map((relay) => ({
1527
+ relay,
1528
+ run: runRow(db, relay.run_id)
1529
+ })));
1530
+ /** After a reconnect: reconcile, then resend, then drain the waiting runs in order (§18.3). */
1531
+ const resume = async (linkId, session, relayMark) => {
1532
+ try {
1533
+ const high = ledger.read((db) => db.get("SELECT MAX(relay_seq) AS high FROM relay_run WHERE owner_link_id = ? AND accepted_at IS NOT NULL", linkId)?.high ?? 0);
1534
+ if (relayMark < high) {
1535
+ const lost = ledger.read((db) => db.all(`SELECT r.run_id FROM relay_run r JOIN action_run a ON a.id = r.run_id
1536
+ WHERE r.owner_link_id = ? AND r.sent_at IS NOT NULL
1537
+ AND a.status IN ('queued', 'running', 'waiting')`, linkId).map((row) => row.run_id));
1538
+ log.warn("relay.owner_regressed", {
1539
+ linkId,
1540
+ relayMark,
1541
+ high,
1542
+ runs: lost.length
1543
+ });
1544
+ for (const runId of lost) unknown(runId);
1545
+ } else {
1546
+ const open = acceptedOpen(linkId);
1547
+ if (open.length > 0) {
1548
+ const answer = await options.call(session, portRelayReconcileMethod.method, {
1549
+ runs: open.map((entry) => entry.run.id),
1550
+ held: open.map((entry) => ({
1551
+ runId: entry.run.id,
1552
+ log: entry.run.log_lines,
1553
+ batches: entry.run.batches
1554
+ }))
1555
+ }, PORT_CALL_MS);
1556
+ for (const entry of answer.runs) applyReconciled(entry);
1557
+ for (const entry of open) if (entry.relay.cancel_requested_at !== null) cancelOnOwner(entry.run.id, session);
1558
+ }
1559
+ }
1560
+ if (options.sessionOf(linkId) !== session) return;
1561
+ ready.set(linkId, session);
1562
+ asked.clear();
1563
+ renewLive();
1564
+ const unacknowledged = ledger.read((db) => db.all(`SELECT r.run_id FROM relay_run r JOIN action_run a ON a.id = r.run_id
1565
+ WHERE r.owner_link_id = ? AND r.sent_at IS NOT NULL AND r.accepted_at IS NULL
1566
+ AND a.status IN ('queued', 'running', 'waiting') ORDER BY r.relay_seq`, linkId).map((row) => row.run_id));
1567
+ for (const runId of unacknowledged) await send(runId, session);
1568
+ retries.delete(session);
1569
+ drain(linkId);
1570
+ } catch (error) {
1571
+ log.warn("relay.resume_failed", {
1572
+ linkId,
1573
+ error
1574
+ });
1575
+ if (stopped || options.sessionOf(linkId) !== session) return;
1576
+ const attempt = (retries.get(session)?.attempt ?? 0) + 1;
1577
+ const timer = setTimeout(() => {
1578
+ if (options.sessionOf(linkId) === session && ready.get(linkId) !== session) resume(linkId, session, relayMark);
1579
+ }, Math.min(6e4, 1e3 * 2 ** (attempt - 1)));
1580
+ timer.unref();
1581
+ retries.set(session, {
1582
+ timer,
1583
+ attempt
1584
+ });
1585
+ }
1586
+ };
1587
+ /** Sends a link's waiting runs, oldest first, at most `drainPerSecond` a second per artifact. */
1588
+ const drain = async (linkId) => {
1589
+ if (draining.has(linkId)) return;
1590
+ draining.add(linkId);
1591
+ try {
1592
+ const sentAt = /* @__PURE__ */ new Map();
1593
+ for (;;) {
1594
+ if (stopped) return;
1595
+ const session = sessionFor(linkId);
1596
+ if (session === void 0) return;
1597
+ const next = ledger.read((db) => db.get(`SELECT r.run_id, a.artifact_id FROM relay_run r JOIN action_run a ON a.id = r.run_id
1598
+ WHERE r.owner_link_id = ? AND r.sent_at IS NULL
1599
+ AND a.status IN ('queued', 'waiting') ORDER BY r.relay_seq LIMIT 1`, linkId));
1600
+ if (!next) return;
1601
+ const times = (sentAt.get(next.artifact_id) ?? []).filter((at) => now() - at < 1e3);
1602
+ if (times.length >= drainPerSecond) {
1603
+ await new Promise((resolve) => setTimeout(resolve, 1e3 - (now() - times[0])));
1604
+ continue;
1605
+ }
1606
+ times.push(now());
1607
+ sentAt.set(next.artifact_id, times);
1608
+ await send(next.run_id, session);
1609
+ }
1610
+ } finally {
1611
+ draining.delete(linkId);
1612
+ }
1613
+ };
1614
+ /** Checks waiting and unacknowledged runs against their offline limit's two clocks. */
1615
+ const sweep = () => {
1616
+ const rows = ledger.read((db) => db.all(`SELECT r.*, a.status, a.version_id, a.started_at FROM relay_run r
1617
+ JOIN action_run a ON a.id = r.run_id WHERE a.status IN ('queued', 'running', 'waiting')`));
1618
+ const open = new Set(rows.map((row) => row.run_id));
1619
+ for (const id of lastTry.keys()) if (!open.has(id)) lastTry.delete(id);
1620
+ for (const row of rows) {
1621
+ if (sending.has(row.run_id)) continue;
1622
+ if (row.sent_at === null) {
1623
+ if (Date.parse(row.offline_limit_at) <= now()) endOffline(row.run_id);
1624
+ continue;
1625
+ }
1626
+ const session = sessionFor(row.owner_link_id);
1627
+ if (session !== void 0) {
1628
+ if (row.accepted_at === null && now() - (lastTry.get(row.run_id) ?? 0) >= RESEND_MS) send(row.run_id, session);
1629
+ continue;
1630
+ }
1631
+ if (Date.parse(row.owner_heard_at ?? row.sent_at) + versionOf(row.version_id).limitMs <= now()) unknown(row.run_id);
1632
+ }
1633
+ };
1634
+ const sweeper = setInterval(sweep, options.sweepMs ?? 1e3);
1635
+ sweeper.unref();
1636
+ /** What each artifact's owner was last asked to produce, so a source no one wants is stopped. */
1637
+ const asked = /* @__PURE__ */ new Map();
1638
+ /** Asks owners for the live sources viewers want now, and stops the ones no one does (§18.3). */
1639
+ const renewLive = (only) => {
1640
+ const wanted = /* @__PURE__ */ new Map();
1641
+ for (const entry of bus.liveInterest()) {
1642
+ if (entry.key.startsWith(TALLY_LIVE_PREFIX)) continue;
1643
+ const keys = wanted.get(entry.artifactId) ?? /* @__PURE__ */ new Set();
1644
+ keys.add(entry.key);
1645
+ wanted.set(entry.artifactId, keys);
1646
+ }
1647
+ const artifacts = /* @__PURE__ */ new Set([...wanted.keys(), ...asked.keys()]);
1648
+ for (const artifactId of artifacts) {
1649
+ if (only !== void 0 && artifactId !== only) continue;
1650
+ const owner = options.ownerOf(artifactId);
1651
+ const session = owner === void 0 ? void 0 : sessionFor(owner);
1652
+ const versionId = options.latestVersion?.(artifactId);
1653
+ if (session === void 0 || versionId === void 0) continue;
1654
+ const keys = wanted.get(artifactId) ?? /* @__PURE__ */ new Set();
1655
+ const stopped = [...asked.get(artifactId) ?? /* @__PURE__ */ new Set()].filter((key) => !keys.has(key));
1656
+ const send = (interest, list) => {
1657
+ if (list.length === 0) return;
1658
+ options.call(session, portRelayLiveMethod.method, {
1659
+ artifactId,
1660
+ versionId,
1661
+ interest,
1662
+ keys: list
1663
+ }, PORT_CALL_MS).catch((error) => log.warn("relay.live_interest_failed", {
1664
+ artifactId,
1665
+ error
1666
+ }));
1667
+ };
1668
+ send("renew", [...keys]);
1669
+ send("stop", stopped);
1670
+ if (keys.size > 0) asked.set(artifactId, keys);
1671
+ else asked.delete(artifactId);
1672
+ }
1673
+ };
1674
+ const liveRenewer = setInterval(() => renewLive(), options.liveRenewMs ?? 2e4);
1675
+ liveRenewer.unref();
1676
+ const decorate = (state, artifactId) => {
1677
+ if (state.status !== "running") return state;
1678
+ const owner = options.ownerOf(artifactId);
1679
+ return owner !== void 0 && sessionFor(owner) !== void 0 ? state : {
1680
+ ...state,
1681
+ ownerUnreachable: true
1682
+ };
1683
+ };
1684
+ return {
1685
+ async call(page, input, signal) {
1686
+ checkArgs(input.args);
1687
+ const versionId = interaction.viewVersion(page, input.viewId);
1688
+ mayTrigger(page.viewerId, functionOf(versionId, input.fnId));
1689
+ limitLink(page.tokenId);
1690
+ const owner = options.ownerOf(page.artifactId);
1691
+ const session = owner === void 0 ? void 0 : sessionFor(owner);
1692
+ if (session === void 0) throw failed("MOSTRA_REMOTE_OWNER_OFFLINE", "The page's owner is offline, so its server code can't answer now; try again later.");
1693
+ const callId = `call_${crypto.randomUUID()}`;
1694
+ const pending = {
1695
+ session,
1696
+ lines: [],
1697
+ ended: false,
1698
+ lastSeq: 0
1699
+ };
1700
+ calls.set(callId, pending);
1701
+ const viewer = interaction.viewer(page.viewerId);
1702
+ try {
1703
+ await options.call(session, portRelayCallMethod.method, {
1704
+ callId,
1705
+ artifactId: page.artifactId,
1706
+ versionId,
1707
+ fnId: input.fnId,
1708
+ args: input.args,
1709
+ viewer: {
1710
+ id: viewer.id,
1711
+ ...viewer.name ? { name: viewer.name } : {}
1712
+ },
1713
+ viewId: input.viewId
1714
+ }, PORT_CALL_MS);
1715
+ } catch (error) {
1716
+ calls.delete(callId);
1717
+ throw error instanceof RpcError ? failed("MOSTRA_REMOTE_OWNER_OFFLINE", `The page's owner couldn't take the call: ${error.diagnostic.message}`) : error;
1718
+ }
1719
+ const lines = async function* () {
1720
+ try {
1721
+ for (;;) {
1722
+ const line = pending.lines.shift();
1723
+ if (line) {
1724
+ yield line;
1725
+ if ("end" in line) return;
1726
+ continue;
1727
+ }
1728
+ if (pending.ended || signal.aborted) return;
1729
+ await new Promise((resolve) => {
1730
+ pending.wake = resolve;
1731
+ });
1732
+ }
1733
+ } finally {
1734
+ calls.delete(callId);
1735
+ }
1736
+ };
1737
+ return lines();
1738
+ },
1739
+ startRun(page, input) {
1740
+ checkArgs(input.args);
1741
+ const versionId = interaction.viewVersion(page, input.viewId);
1742
+ const version = functionOf(versionId, input.fnId);
1743
+ mayTrigger(page.viewerId, version);
1744
+ limitLink(page.tokenId, page.artifactId, input);
1745
+ const owner = options.ownerOf(page.artifactId);
1746
+ if (owner === void 0) throw failed("MOSTRA_REMOTE_OWNER_OFFLINE", "This page has no owner instance to run it.");
1747
+ const connected = sessionFor(owner) !== void 0;
1748
+ if (!connected && version.policy === "queue") {
1749
+ const waiting = ledger.read((db) => db.get("SELECT COUNT(*) AS n FROM action_run WHERE artifact_id = ? AND status = 'waiting'", page.artifactId)?.n ?? 0);
1750
+ const joins = ledger.read((db) => db.get(`SELECT id FROM action_run WHERE artifact_id = ? AND (client_key = ? OR (key IS NOT NULL AND key = ? AND action = ?))`, page.artifactId, input.clientKey, input.key ?? null, input.fnId) !== void 0);
1751
+ if (waiting >= cap && !joins) throw failed("MOSTRA_REMOTE_QUEUE_FULL", "Too many actions are waiting for this page's owner; try again once it is back.");
1752
+ }
1753
+ const { state, row, started } = interaction.startRun(page, input);
1754
+ bus.attachRuns(page.artifactId, input.viewId, [state.runId]);
1755
+ if (!started) return decorate(state, page.artifactId);
1756
+ const recorded = Date.parse(row.started_at);
1757
+ const waitingState = ledger.write((db) => {
1758
+ const seq = (db.get("SELECT MAX(relay_seq) AS high FROM relay_run WHERE owner_link_id = ?", owner)?.high ?? 0) + 1;
1759
+ const floor = Math.max(marks.get(owner) ?? 0, db.get("SELECT floor FROM relay_floor WHERE link_id = ?", owner)?.floor ?? 0);
1760
+ db.run("INSERT INTO relay_run (run_id, owner_link_id, relay_seq, offline_limit_at) VALUES (?, ?, ?, ?)", row.id, owner, Math.max(seq, floor + 1), iso(recorded + version.limitMs));
1761
+ if (connected) return void 0;
1762
+ markWaiting(db, row.id);
1763
+ const after = runRow(db, row.id);
1764
+ return after ? runState(db, after) : void 0;
1765
+ });
1766
+ if (connected) {
1767
+ const session = sessionFor(owner);
1768
+ if (session !== void 0) send(row.id, session);
1769
+ return state;
1770
+ }
1771
+ if (version.policy === "fail") {
1772
+ endOffline(row.id);
1773
+ return interaction.runState(row.id) ?? state;
1774
+ }
1775
+ if (waitingState) publish(waitingState, page.artifactId);
1776
+ return waitingState ?? state;
1777
+ },
1778
+ attach(page, input) {
1779
+ const states = interaction.runsFor(page, input);
1780
+ bus.attachRuns(page.artifactId, input.viewId, states.map((state) => state.runId));
1781
+ return states.map((state) => decorate(state, page.artifactId));
1782
+ },
1783
+ cancel(page, viewId, runId) {
1784
+ const row = interaction.runFor(page, viewId, runId);
1785
+ const relay = ledger.read((db) => relayRow(db, row.id));
1786
+ if (!relay || relay.sent_at === null) {
1787
+ if (!isFinalRunStatus(row.status) && row.status !== "unknown") {
1788
+ const ended = interaction.endRun(row.id, {
1789
+ status: "cancelled",
1790
+ reason: "cancelled"
1791
+ });
1792
+ if (ended) publish(ended, row.artifact_id);
1793
+ }
1794
+ return interaction.runState(row.id);
1795
+ }
1796
+ ledger.write((db) => db.run("UPDATE relay_run SET cancel_requested_at = ? WHERE run_id = ?", iso(now()), row.id));
1797
+ const session = sessionFor(relay.owner_link_id);
1798
+ if (session !== void 0 && relay.accepted_at !== null) cancelOnOwner(row.id, session);
1799
+ return decorate(interaction.runState(row.id), row.artifact_id);
1800
+ },
1801
+ methods() {
1802
+ return [
1803
+ handler(relayRunUpdateMethod, (params, session) => {
1804
+ const known = ledger.read((db) => relayRow(db, params.runId));
1805
+ if (!known || known.owner_link_id !== session.link?.instanceId) {
1806
+ log.warn("relay.update_dropped", { runId: params.runId });
1807
+ return {};
1808
+ }
1809
+ if (params.seq <= known.last_seq) return {};
1810
+ ledger.write((db) => db.run("UPDATE relay_run SET last_seq = ? WHERE run_id = ?", params.seq, params.runId));
1811
+ apply(params.runId, params);
1812
+ return {};
1813
+ }),
1814
+ handler(relayLiveValueMethod, (params, session) => {
1815
+ if (options.ownerOf(params.artifactId) !== session.link?.instanceId) throw failed("MOSTRA_REMOTE_NOT_OWNER_INSTANCE", "This instance doesn't own that artifact here.");
1816
+ return options.storeLive?.(params.artifactId, params.versionId, {
1817
+ key: params.key,
1818
+ ...params.value !== void 0 ? { value: params.value } : {},
1819
+ ...params.error !== void 0 ? { error: params.error } : {}
1820
+ }) ?? {};
1821
+ }),
1822
+ handler(relayEffectMethod, (params, session) => {
1823
+ if (options.ownerOf(params.artifactId) !== session.link?.instanceId) throw failed("MOSTRA_REMOTE_NOT_OWNER_INSTANCE", "This instance doesn't own that artifact here.");
1824
+ const row = params.runId !== void 0 ? ledger.read((db) => runRow(db, params.runId)) : void 0;
1825
+ if (params.runId !== void 0 && row?.artifact_id !== params.artifactId) throw failed("MOSTRA_ACTION_RUN_NOT_FOUND", "This home has no such run.");
1826
+ const viewerId = row?.viewer_id ?? void 0;
1827
+ const common = {
1828
+ ...params.payload !== void 0 ? { payload: params.payload } : {},
1829
+ ...params.runId !== void 0 ? { runId: params.runId } : {},
1830
+ ...viewerId !== void 0 ? { viewerId } : {}
1831
+ };
1832
+ if (params.kind === "signal") return { cursor: interaction.serverSignal(params.artifactId, {
1833
+ name: params.name,
1834
+ ...common
1835
+ }) };
1836
+ if (!/^host\.[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(params.name)) throw failed("MOSTRA_ACTION_EVENT_INVALID", `${params.name.slice(0, 80)} isn't a host event type.`);
1837
+ return { cursor: interaction.serverEmit(params.artifactId, {
1838
+ type: params.name,
1839
+ ...common
1840
+ }) };
1841
+ }),
1842
+ handler(relayCallBatchMethod, (params, session) => {
1843
+ const pending = calls.get(params.callId);
1844
+ if (!pending || pending.session !== session.id || params.seq <= pending.lastSeq) return {};
1845
+ pending.lastSeq = params.seq;
1846
+ for (const batch of params.batches ?? []) pending.lines.push({ batch: [...batch] });
1847
+ if (params.end) {
1848
+ pending.lines.push(params.end.status === "succeeded" ? { end: { status: "succeeded" } } : { end: {
1849
+ status: "failed",
1850
+ error: params.end.error ?? { message: "The call failed on its owner." }
1851
+ } });
1852
+ pending.ended = true;
1853
+ }
1854
+ pending.wake?.();
1855
+ return {};
1856
+ })
1857
+ ];
1858
+ },
1859
+ connected(session) {
1860
+ const linkId = session.link?.instanceId;
1861
+ if (linkId === void 0 || !session.ports.has("relay")) return;
1862
+ const mark = session.link?.relayMark ?? 0;
1863
+ marks.set(linkId, Math.max(marks.get(linkId) ?? 0, mark));
1864
+ sessionMarks.set(session.id, mark);
1865
+ resume(linkId, session.id, mark);
1866
+ },
1867
+ disconnected(session) {
1868
+ const linkId = session.link?.instanceId;
1869
+ sessionMarks.delete(session.id);
1870
+ const retry = retries.get(session.id);
1871
+ if (retry) clearTimeout(retry.timer);
1872
+ retries.delete(session.id);
1873
+ if (linkId !== void 0 && ready.get(linkId) === session.id) ready.delete(linkId);
1874
+ if (linkId !== void 0) {
1875
+ const live = options.sessionOf(linkId);
1876
+ if (live !== void 0 && live !== session.id && ready.get(linkId) !== live) resume(linkId, live, sessionMarks.get(live) ?? marks.get(linkId) ?? 0);
1877
+ }
1878
+ for (const [callId, pending] of calls) {
1879
+ if (pending.session !== session.id) continue;
1880
+ pending.lines.push({ end: {
1881
+ status: "failed",
1882
+ error: {
1883
+ code: "MOSTRA_REMOTE_OWNER_OFFLINE",
1884
+ message: "The page's owner went offline before the call ended."
1885
+ }
1886
+ } });
1887
+ pending.ended = true;
1888
+ pending.wake?.();
1889
+ calls.delete(callId);
1890
+ }
1891
+ },
1892
+ busy() {
1893
+ return calls.size > 0 || ledger.read((db) => (db.get("SELECT COUNT(*) AS n FROM action_run WHERE status IN ('queued', 'running', 'waiting')")?.n ?? 0) > 0);
1894
+ },
1895
+ liveWanted(artifactId) {
1896
+ const known = asked.get(artifactId);
1897
+ if (bus.liveInterest().some((entry) => entry.artifactId === artifactId && !entry.key.startsWith(TALLY_LIVE_PREFIX) && !(known?.has(entry.key) ?? false))) renewLive(artifactId);
1898
+ },
1899
+ ownerOffline(artifactId) {
1900
+ const owner = options.ownerOf(artifactId);
1901
+ return owner === void 0 || sessionFor(owner) === void 0;
1902
+ },
1903
+ stop() {
1904
+ stopped = true;
1905
+ for (const retry of retries.values()) clearTimeout(retry.timer);
1906
+ retries.clear();
1907
+ clearInterval(sweeper);
1908
+ clearInterval(liveRenewer);
1909
+ }
1910
+ };
1911
+ }
1912
+ //#endregion
1913
+ //#region src/server/hosted.ts
1914
+ /**
1915
+ * A hosted home (ARCHITECTURE §15.2, DATA_MODEL §7.2, D165): a Mostra home on a remote server with
1916
+ * the same ledger, registry, interaction core and events as a local one, and no sources, builds,
1917
+ * verify, workers, dependency store or secrets. Its versions arrive from the owner instance
1918
+ * (`hosted/push`): the client files the listing names, checked against `outputDigest`, never the
1919
+ * server files; its server code runs on the owner, through the relay.
1920
+ *
1921
+ * Its host protocol is served by a {@link ProtocolServer} of its own, reached over the network
1922
+ * binding (§18.2), so the owner instance is a host of its hosted home as any host is of an
1923
+ * instance (invariant 11): it registers `submissions`, and a submission's one delivery owner is its
1924
+ * artifact's owner link (D165, after the Opus review).
1925
+ */
1926
+ /** Lower-case Crockford base32, for route labels (one DNS label, 130 bits). */
1927
+ const LABEL_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
1928
+ /** A random route label: 26 lower-case Crockford base32 characters (INTERFACES §18.4). */
1929
+ /** A character no part of a listing's path may hold: a backslash, a colon, a control character. */
1930
+ const UNSAFE_PART = /[\\:\u0000-\u001f\u007f]/;
1931
+ /**
1932
+ * Whether a pushed listing's path is one a version can hold on every system the server runs on: `/`
1933
+ * between non-empty parts, none `.` or `..`, and no backslash, colon or control character, which
1934
+ * Windows reads as separators, drive or stream names, or refuses (Opus review of WP-29, 5); in NFC,
1935
+ * as listings are written (DATA_MODEL §2).
1936
+ */
1937
+ function safeListingPath(path) {
1938
+ if (path.length > 1024 || path.normalize("NFC") !== path) return false;
1939
+ return path.split("/").every((part) => part !== "" && part !== "." && part !== ".." && !UNSAFE_PART.test(part));
1940
+ }
1941
+ function randomLabel() {
1942
+ const bytes = randomBytes(26);
1943
+ let label = "";
1944
+ for (const byte of bytes) label += LABEL_ALPHABET[byte & 31];
1945
+ return label;
1946
+ }
1947
+ function refuse(code, message) {
1948
+ return new RpcError(createDiagnostic(code, { message }));
1949
+ }
1950
+ /** Opens the parts of a hosted home over its ledger. */
1951
+ async function openHostedHome(options) {
1952
+ const { id, dir, ledger, directory, log } = options;
1953
+ const registry = await openRegistry({
1954
+ home: dir,
1955
+ ledger
1956
+ });
1957
+ /** Pending pushes: version ID → the client files still missing. */
1958
+ const pending = /* @__PURE__ */ new Map();
1959
+ let incarnation = options.incarnation;
1960
+ const ownerLinkOf = (artifactId) => directory.read((db) => db.get("SELECT owner_link_id FROM artifact_route WHERE home_id = ? AND artifact_id = ?", id, artifactId)?.owner_link_id);
1961
+ const coverage = (() => {
1962
+ const cache = /* @__PURE__ */ new Map();
1963
+ return (versionId) => {
1964
+ let matcher = cache.get(versionId);
1965
+ if (!matcher) {
1966
+ matcher = coverageMatcher(readFieldCoverage(registry.store.versionDir(versionId)));
1967
+ if (cache.size >= 512) cache.delete(cache.keys().next().value);
1968
+ cache.set(versionId, matcher);
1969
+ }
1970
+ return matcher;
1971
+ };
1972
+ })();
1973
+ let protocol;
1974
+ const interaction = createInteraction({
1975
+ sentOnly: true,
1976
+ ledger,
1977
+ log,
1978
+ faults: noFaults,
1979
+ hosts: {
1980
+ registrants: (port) => protocol.registrants(port),
1981
+ call: (session, method, params, timeoutMs) => protocol.callSession(session, method, params, timeoutMs),
1982
+ notify: (session, method, params) => protocol.notify(session, method, params),
1983
+ drained: (session) => protocol.drained(session)
1984
+ },
1985
+ expectedHosts: () => [],
1986
+ artifacts: { resolve: (ref) => registry.get(canonicalRef(ref)).id },
1987
+ coverage,
1988
+ deliverSnapshots: true,
1989
+ deliveryOwners: (artifactId) => {
1990
+ const owner = ownerLinkOf(artifactId);
1991
+ return owner === void 0 ? void 0 : [owner];
1992
+ }
1993
+ });
1994
+ /** The route of an artifact on this home, minted on its first push by `link`. */
1995
+ const routeFor = (artifactId, link) => directory.write((db) => {
1996
+ const found = db.get("SELECT id, label, owner_link_id FROM artifact_route WHERE home_id = ? AND artifact_id = ?", id, artifactId);
1997
+ if (found) {
1998
+ if (found.owner_link_id !== link) throw refuse("MOSTRA_REMOTE_NOT_OWNER_INSTANCE", `The instance "${db.get("SELECT name FROM instance_link WHERE id = ?", found.owner_link_id)?.name ?? found.owner_link_id}" owns this hosted artifact; push it from there.`);
1999
+ return {
2000
+ routeId: found.id,
2001
+ label: found.label
2002
+ };
2003
+ }
2004
+ const routeId = RouteId.create();
2005
+ let label = randomLabel();
2006
+ while (db.get("SELECT 1 FROM label_issued WHERE label = ?", label)) label = randomLabel();
2007
+ const at = (/* @__PURE__ */ new Date()).toISOString();
2008
+ db.run("INSERT INTO label_issued (label, home_id, route_id, kind, issued_at) VALUES (?, ?, ?, 'server', ?)", label, id, routeId, at);
2009
+ db.run("INSERT INTO artifact_route (id, home_id, artifact_id, owner_link_id, label, created_at) VALUES (?, ?, ?, ?, ?, ?)", routeId, id, artifactId, link, label, at);
2010
+ log.info("server.route_minted", {
2011
+ home: id,
2012
+ artifactId,
2013
+ routeId
2014
+ });
2015
+ return {
2016
+ routeId,
2017
+ label
2018
+ };
2019
+ });
2020
+ const routeOf = (artifactId) => directory.read((db) => db.get("SELECT id, label FROM artifact_route WHERE home_id = ? AND artifact_id = ?", id, artifactId));
2021
+ const artifactOfRoute = (routeId) => directory.read((db) => db.get("SELECT artifact_id FROM artifact_route WHERE id = ? AND home_id = ?", routeId, id)?.artifact_id);
2022
+ const domains = [options.domains.active, ...options.domains.spares];
2023
+ const originOf = (host) => `${options.scheme}://${host}`;
2024
+ const capabilities = new Capabilities({
2025
+ ledger,
2026
+ log,
2027
+ key: capabilityKey(dir, log),
2028
+ now: () => Date.now(),
2029
+ shellOrigin: () => originOf(options.domains.active),
2030
+ servesShell: (origin) => domains.some((domain) => originOf(domain) === origin)
2031
+ });
2032
+ const addressing = {
2033
+ bindAddress: "",
2034
+ urlHost: options.domains.active,
2035
+ origin: () => originOf(options.domains.active),
2036
+ hosts: () => [],
2037
+ leased: () => void 0,
2038
+ leases: () => [],
2039
+ listen: () => Promise.reject(/* @__PURE__ */ new Error("A hosted home binds no listener.")),
2040
+ frameMode: () => "worker",
2041
+ listenFace: () => Promise.reject(/* @__PURE__ */ new Error("A hosted home binds no listener.")),
2042
+ releaseFace: () => void 0,
2043
+ faceLocal: () => ""
2044
+ };
2045
+ const bus = createEphemeralBus();
2046
+ const noPool = new Proxy({}, { get: () => {
2047
+ throw new Error("A hosted home runs no workers.");
2048
+ } });
2049
+ const live = createLive({
2050
+ ledger,
2051
+ log,
2052
+ bus,
2053
+ pool: noPool,
2054
+ interaction,
2055
+ latest: () => void 0,
2056
+ artifactsWithLive: () => [],
2057
+ version: () => void 0
2058
+ });
2059
+ const relay = createHostedRelay({
2060
+ ledger,
2061
+ interaction,
2062
+ bus,
2063
+ log,
2064
+ ownerOf: (artifactId) => ownerLinkOf(artifactId),
2065
+ sessionOf: (linkId) => protocol.registrants("relay").filter((entry) => entry.owner === linkId).at(-1)?.session,
2066
+ call: (session, method, params, timeoutMs) => protocol.callSession(session, method, params, timeoutMs),
2067
+ functions: (versionId) => readServerFunctions(registry.store.versionDir(versionId)),
2068
+ ...options.relay?.waitingRunsPerArtifact !== void 0 ? { waitingRunsPerArtifact: options.relay.waitingRunsPerArtifact } : {},
2069
+ ...options.relay?.drainPerSecond !== void 0 ? { drainPerSecond: options.relay.drainPerSecond } : {},
2070
+ ...options.relay?.sweepMs !== void 0 ? { sweepMs: options.relay.sweepMs } : {},
2071
+ ...options.relay?.liveRenewMs !== void 0 ? { liveRenewMs: options.relay.liveRenewMs } : {},
2072
+ ...options.relay?.perLink !== void 0 ? { perLink: options.relay.perLink } : {},
2073
+ latestVersion: (artifactId) => ledger.read((db) => db.get("SELECT latest_version_id FROM artifact WHERE id = ?", artifactId)?.latest_version_id ?? void 0),
2074
+ storeLive: (artifactId, versionId, produced) => live.relayed(artifactId, versionId, produced)
2075
+ });
2076
+ const gateway = createGateway({
2077
+ ledger,
2078
+ log,
2079
+ addressing,
2080
+ capabilities,
2081
+ artifacts: {
2082
+ get: (ref) => registry.get(canonicalRef(ref)),
2083
+ versionDir: (versionId) => registry.store.versionDir(versionId),
2084
+ damage: (versionId) => hostedDamage(registry.store.versionDir(versionId))
2085
+ },
2086
+ shellDir: options.shellDir,
2087
+ interaction,
2088
+ bus,
2089
+ actions: relay,
2090
+ live: { read(page, input) {
2091
+ const states = live.read(page, input);
2092
+ relay.liveWanted(page.artifactId);
2093
+ if (!relay.ownerOffline(page.artifactId)) return states;
2094
+ return states.map((state) => state.key.startsWith("$tally/") ? state : {
2095
+ ...state,
2096
+ ownerOffline: true
2097
+ });
2098
+ } },
2099
+ controls: async () => ({ submitChannels: ["shell", "artifact"] }),
2100
+ activated: () => void 0,
2101
+ hosted: {
2102
+ shellOrigin: () => originOf(options.domains.active),
2103
+ servesShell: (origin) => domains.some((domain) => originOf(domain) === origin),
2104
+ shellPath: (artifactId) => `/a/${routeOf(artifactId)?.id ?? artifactId}`,
2105
+ artifactOrigin: (artifactId, shellOrigin) => {
2106
+ const route = routeOf(artifactId);
2107
+ const domain = domains.find((candidate) => originOf(candidate) === shellOrigin);
2108
+ return route && domain ? originOf(`${route.label}.${domain}`) : void 0;
2109
+ }
2110
+ }
2111
+ });
2112
+ /** The faces of a domain: its shell, and a route's frames, opened when first asked for. */
2113
+ const shellSpec = (domain) => ({
2114
+ by: "hosted",
2115
+ group: `hosted:${domain}`,
2116
+ listener: "shell",
2117
+ via: "token",
2118
+ lease: false
2119
+ });
2120
+ const ensureShell = async (domain) => {
2121
+ const spec = shellSpec(domain);
2122
+ const handle = await gateway.openFace(spec);
2123
+ handle.setOrigin(originOf(domain));
2124
+ return handle.key;
2125
+ };
2126
+ const ensureFrame = async (domain, artifactId, label) => {
2127
+ await ensureShell(domain);
2128
+ const handle = await gateway.openFace({
2129
+ by: "hosted",
2130
+ group: `hosted:${domain}`,
2131
+ listener: "artifact",
2132
+ artifactId,
2133
+ via: "token",
2134
+ lease: false,
2135
+ mode: "worker"
2136
+ });
2137
+ handle.setOrigin(originOf(`${label}.${domain}`));
2138
+ return handle.key;
2139
+ };
2140
+ const notServed = (response) => {
2141
+ response.writeHead(404, {
2142
+ "content-type": "application/json",
2143
+ "cache-control": "no-store"
2144
+ });
2145
+ response.end(JSON.stringify(createDiagnostic("MOSTRA_HYGIENE_NOT_SERVED", { message: "Nothing is served at this path." })));
2146
+ };
2147
+ const serve = async (request, response, at) => {
2148
+ const artifactId = artifactOfRoute(at.routeId);
2149
+ const route = artifactId === void 0 ? void 0 : routeOf(artifactId);
2150
+ if (artifactId === void 0 || !route) {
2151
+ notServed(response);
2152
+ return;
2153
+ }
2154
+ if (at.kind === "shell") {
2155
+ const url = request.url ?? "/";
2156
+ const prefix = `/a/${at.routeId}`;
2157
+ if (!url.startsWith(prefix)) {
2158
+ notServed(response);
2159
+ return;
2160
+ }
2161
+ request.url = `/a/${artifactId}${url.slice(prefix.length)}`;
2162
+ const key = await ensureShell(at.domain);
2163
+ if (!gateway.dispatch(key, request, response)) notServed(response);
2164
+ return;
2165
+ }
2166
+ const key = await ensureFrame(at.domain, artifactId, route.label);
2167
+ if (!gateway.dispatch(key, request, response)) notServed(response);
2168
+ };
2169
+ /** The client files of a listing this home doesn't hold yet. */
2170
+ const missingOf = (files) => directory.read((db) => files.filter((sha) => !db.get("SELECT 1 FROM home_file WHERE home_id = ? AND sha256 = ?", id, sha)));
2171
+ const push = async (params, session) => {
2172
+ const link = session.link?.instanceId;
2173
+ if (link === void 0 || session.attributes["linkId"] !== link) throw refuse("MOSTRA_REMOTE_NOT_OWNER_INSTANCE", "Only an owner instance's binding pushes versions.");
2174
+ const version = params.version;
2175
+ if (versionIdFor(params.artifactId, version.sourceDigest, version.envDigest) !== version.versionId) throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed version's ID doesn't match its digests.");
2176
+ const listed = version.listing.map(([path, executable, sha256]) => ({
2177
+ path,
2178
+ executable,
2179
+ sha256
2180
+ }));
2181
+ if (listingDigest(listed) !== version.outputDigest) throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed listing doesn't match the output digest.");
2182
+ const registryEntry = version.listing.find(([path]) => path === "registry.json");
2183
+ if (!registryEntry || sha256Text(version.registry) !== registryEntry[2]) throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed registry.json isn't the one the listing names.");
2184
+ for (const [path] of version.listing) {
2185
+ if (!(path === "registry.json" || path.startsWith("client/") || path.startsWith("server/"))) throw refuse("MOSTRA_HOME_INTEGRITY", `The listing names ${path}, outside a version.`);
2186
+ if (!safeListingPath(path)) throw refuse("MOSTRA_HOME_INTEGRITY", `The listing names an unsafe path, ${JSON.stringify(path.slice(0, 300))}.`);
2187
+ }
2188
+ let manifestDoc;
2189
+ try {
2190
+ manifestDoc = JSON.parse(version.manifest);
2191
+ } catch {
2192
+ throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed manifest.json isn't JSON.");
2193
+ }
2194
+ if (manifestDoc.artifactId !== params.artifactId || manifestDoc.versionId !== version.versionId) throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed manifest.json names another version.");
2195
+ const manifest = ArtifactManifest.safeParse(manifestDoc.manifest);
2196
+ if (!manifest.success) throw refuse("MOSTRA_HOME_INTEGRITY", "The pushed artifact manifest isn't valid.");
2197
+ const route = routeFor(params.artifactId, link);
2198
+ if (registry.hasVersion(version.versionId)) {
2199
+ const known = registry.get({ artifactId: params.artifactId }).versions.find((v) => v.id === version.versionId);
2200
+ return {
2201
+ status: "complete",
2202
+ versionId: version.versionId,
2203
+ number: known?.number ?? version.number,
2204
+ route
2205
+ };
2206
+ }
2207
+ const clientFiles = version.listing.filter(([path]) => path.startsWith("client/"));
2208
+ const missing = missingOf([...new Set(clientFiles.map(([, , sha]) => sha))]);
2209
+ if (missing.length > 0) {
2210
+ pending.set(version.versionId, new Set(missing));
2211
+ return {
2212
+ status: "missing",
2213
+ files: missing,
2214
+ route
2215
+ };
2216
+ }
2217
+ pending.delete(version.versionId);
2218
+ const stage = join(registry.store.stagingDir, `${version.versionId}.push-${process.pid}-${Date.now()}`);
2219
+ await rm(stage, {
2220
+ recursive: true,
2221
+ force: true
2222
+ });
2223
+ mkdirSync(stage, {
2224
+ recursive: true,
2225
+ mode: 448
2226
+ });
2227
+ try {
2228
+ writeFileSync(join(stage, "manifest.json"), version.manifest);
2229
+ writeFileSync(join(stage, "registry.json"), version.registry);
2230
+ writeFileSync(join(stage, "lock.yaml"), version.lock);
2231
+ writeFileSync(join(stage, "listing.json"), JSON.stringify(version.listing));
2232
+ for (const [path, , sha] of clientFiles) {
2233
+ const target = join(stage, ...path.split("/"));
2234
+ if (relative(stage, target).startsWith("..") || isAbsolute(relative(stage, target))) throw refuse("MOSTRA_HOME_INTEGRITY", "The listing names a path outside the version.");
2235
+ mkdirSync(join(target, ".."), {
2236
+ recursive: true,
2237
+ mode: 448
2238
+ });
2239
+ const stored = join(options.filesDir, sha);
2240
+ try {
2241
+ linkSync(stored, target);
2242
+ } catch {
2243
+ await copyFile(stored, target);
2244
+ }
2245
+ }
2246
+ await registry.store.promote(stage, version.versionId);
2247
+ } catch (error) {
2248
+ await rm(stage, {
2249
+ recursive: true,
2250
+ force: true
2251
+ });
2252
+ throw error;
2253
+ }
2254
+ const committed = registry.commit({
2255
+ artifactId: params.artifactId,
2256
+ bindingPath: void 0,
2257
+ number: version.number,
2258
+ manifestId: params.artifactId,
2259
+ versionId: version.versionId,
2260
+ sourceDigest: version.sourceDigest,
2261
+ envDigest: version.envDigest,
2262
+ outputDigest: version.outputDigest,
2263
+ manifest: manifest.data,
2264
+ policy: version.policy,
2265
+ forcedCodes: [],
2266
+ stillClaims: () => false
2267
+ });
2268
+ directory.write((db) => {
2269
+ for (const sha of new Set(clientFiles.map(([, , file]) => file))) if (db.run("INSERT OR IGNORE INTO home_file (home_id, sha256) VALUES (?, ?)", id, sha).changes > 0) db.run("INSERT INTO file_ref (sha256, homes) VALUES (?, 1) ON CONFLICT (sha256) DO UPDATE SET homes = homes + 1, unreferenced_at = NULL", sha);
2270
+ });
2271
+ log.info("server.version_pushed", {
2272
+ home: id,
2273
+ artifactId: params.artifactId,
2274
+ versionId: version.versionId
2275
+ });
2276
+ return {
2277
+ status: "complete",
2278
+ versionId: version.versionId,
2279
+ number: committed.version,
2280
+ route
2281
+ };
2282
+ };
2283
+ const describe = () => {
2284
+ const head = ledger.read((db) => db.get("SELECT MAX(cursor) AS cursor FROM event")?.cursor ?? 0);
2285
+ return {
2286
+ version: options.runtimeVersion,
2287
+ home: `hosted:${id}`,
2288
+ platform: platformName(),
2289
+ pid: process.pid,
2290
+ mode: "hosted",
2291
+ incarnation,
2292
+ cursor: String(head)
2293
+ };
2294
+ };
2295
+ protocol = new ProtocolServer({
2296
+ log,
2297
+ describe,
2298
+ servesHome: () => false,
2299
+ supportedPorts: ["submissions", "relay"],
2300
+ notifications: ["events/notify"],
2301
+ admit: (session, params) => {
2302
+ const link = params.link;
2303
+ if (link !== void 0 && link.instanceId === session.attributes["linkId"]) {
2304
+ const marks = ledger.read((db) => ({
2305
+ head: db.get("SELECT MAX(cursor) AS head FROM event")?.head ?? 0,
2306
+ relayHigh: Math.max(db.get("SELECT MAX(relay_seq) AS high FROM relay_run WHERE owner_link_id = ?", link.instanceId)?.high ?? 0, db.get("SELECT floor FROM relay_floor WHERE link_id = ?", link.instanceId)?.floor ?? 0)
2307
+ }));
2308
+ const followedAhead = link.followed !== void 0 && link.followed.incarnation === incarnation && Number(link.followed.cursor) > marks.head;
2309
+ const relayAhead = link.relayMark > marks.relayHigh;
2310
+ if (followedAhead || relayAhead) {
2311
+ incarnation = rotateIncarnation(ledger);
2312
+ log.warn("server.home_rotated", {
2313
+ home: id,
2314
+ why: followedAhead ? "owner-cursor" : "owner-relay-mark"
2315
+ });
2316
+ }
2317
+ ledger.write((db) => db.run(`INSERT INTO relay_floor (link_id, floor) VALUES (?, ?)
2318
+ ON CONFLICT (link_id) DO UPDATE SET floor = MAX(floor, excluded.floor)`, link.instanceId, link.relayMark));
2319
+ }
2320
+ if (params.link !== void 0 && params.link.instanceId !== session.attributes["linkId"]) throw refuse("MOSTRA_REMOTE_NOT_OWNER_INSTANCE", "This binding's sign-in is for another instance link.");
2321
+ if (params.link === void 0 && params.ports.length > 0) throw refuse("MOSTRA_REMOTE_NOT_OWNER_INSTANCE", "A binding that registers ports must name its own instance link.");
2322
+ },
2323
+ onInitialized: (session) => {
2324
+ interaction.connected(session);
2325
+ relay.connected(session);
2326
+ },
2327
+ onClosed: (session) => {
2328
+ interaction.disconnected(session);
2329
+ relay.disconnected(session);
2330
+ },
2331
+ handlers: [
2332
+ ...interaction.methods(),
2333
+ handler(artifactListMethod, (params) => ({ artifacts: registry.list(params.filter ?? {}) })),
2334
+ handler(artifactGetMethod, (params) => registry.get(canonicalRef(params.artifact))),
2335
+ handler(hostedPushMethod, (params, session) => push(params, session)),
2336
+ handler(hostedSubmissionMethod, (params, session) => {
2337
+ const link = session.link?.instanceId;
2338
+ const envelope = link === void 0 ? void 0 : interaction.envelopeFor(params.submissionId, link);
2339
+ if (!envelope) throw refuse("MOSTRA_HOST_INVALID_PARAMS", `This home delivers no submission ${params.submissionId} to this instance.`);
2340
+ return envelope;
2341
+ }),
2342
+ ...gateway.methods(),
2343
+ ...relay.methods(),
2344
+ ...liveMethods(live, (ref) => registry.get(canonicalRef(ref)).id),
2345
+ handler(remoteTokenMethod, (params, session) => {
2346
+ const found = options.auth.authenticate(params.accessToken);
2347
+ if (!found || found.grantId !== session.attributes["grantId"]) throw refuse("MOSTRA_REMOTE_LOGIN_FAILED", "That access token isn't this binding's grant's.");
2348
+ const replace = session.attributes["replaceToken"];
2349
+ replace?.(found.expiresAt);
2350
+ return { expiresAt: new Date(found.expiresAt).toISOString() };
2351
+ })
2352
+ ]
2353
+ });
2354
+ interaction.start();
2355
+ live.start();
2356
+ return {
2357
+ id,
2358
+ dir,
2359
+ ledger,
2360
+ registry,
2361
+ interaction,
2362
+ protocol,
2363
+ incarnation: () => incarnation,
2364
+ wanted: (sha) => [...pending.values()].some((files) => files.has(sha)),
2365
+ uploaded(sha) {
2366
+ directory.write((db) => {
2367
+ if (db.run("INSERT OR IGNORE INTO home_file (home_id, sha256) VALUES (?, ?)", id, sha).changes > 0) db.run("INSERT INTO file_ref (sha256, homes) VALUES (?, 1) ON CONFLICT (sha256) DO UPDATE SET homes = homes + 1, unreferenced_at = NULL", sha);
2368
+ });
2369
+ for (const files of pending.values()) files.delete(sha);
2370
+ },
2371
+ busy: () => protocol.connections > 0 || bus.activeViews() > 0 || relay.busy(),
2372
+ serve,
2373
+ async stop() {
2374
+ relay.stop();
2375
+ live.stop();
2376
+ interaction.stop();
2377
+ await gateway.close();
2378
+ await protocol.close();
2379
+ bus.close?.();
2380
+ }
2381
+ };
2382
+ }
2383
+ /**
2384
+ * What is wrong with a hosted version's stored files (FAILURE_MODEL §3): its listing must be the
2385
+ * one its output digest names, and every client file it lists present with its bytes. Server files
2386
+ * are listed but never stored (D165 item 3).
2387
+ */
2388
+ async function hostedDamage(versionDir) {
2389
+ try {
2390
+ const manifest = JSON.parse(await readFile(join(versionDir, "manifest.json"), "utf8"));
2391
+ const listing = JSON.parse(await readFile(join(versionDir, "listing.json"), "utf8"));
2392
+ const listed = listing.map(([path, executable, sha256]) => ({
2393
+ path,
2394
+ executable,
2395
+ sha256
2396
+ }));
2397
+ if (listingDigest(listed) !== manifest.outputDigest) return "its listing doesn't match its digest";
2398
+ for (const [path, , sha256] of listing) {
2399
+ if (!path.startsWith("client/") && path !== "registry.json") continue;
2400
+ const bytes = await readFile(join(versionDir, ...path.split("/")));
2401
+ if (createHash("sha256").update(bytes).digest("hex") !== sha256) return `${path} was changed`;
2402
+ }
2403
+ return;
2404
+ } catch (error) {
2405
+ return `a file is missing (${error.code ?? "unreadable"})`;
2406
+ }
2407
+ }
2408
+ /** The SHA-256 of a text's UTF-8 bytes, lowercase hex. */
2409
+ function sha256Text(text) {
2410
+ return createHash("sha256").update(text, "utf8").digest("hex");
2411
+ }
2412
+ //#endregion
2413
+ //#region src/server/config.ts
2414
+ /**
2415
+ * The remote server's configuration (INTERFACES §18.1): a JSON file (`--config`) and
2416
+ * `MOSTRA_SERVER_<KEY>` variables, read before the server serves anything. A configuration it
2417
+ * can't use stops it, naming the key (`MOSTRA_REMOTE_CONFIG_INVALID`). Domains are configuration,
2418
+ * never code (D137, D165 item 0a): the dossier and this code name only `example` hosts.
2419
+ */
2420
+ /** A rate: `count` per `per` (a duration such as `1m`, as links' lifetimes are written). */
2421
+ const RateSchema = z.object({
2422
+ count: z.int().min(1),
2423
+ per: Duration
2424
+ });
2425
+ /** A host name a link can use: lower-case labels of letters, digits and hyphens. */
2426
+ const HostName = z.string().regex(/^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*(:\d{1,5})?$/, { message: "must be a lower-case host name, with a port only for a local test" });
2427
+ /**
2428
+ * An origin the server is reached at: `https:`, or `http:` for loopback and `*.localhost` (tests
2429
+ * and a self-hoster's first run).
2430
+ */
2431
+ const Origin = z.string().refine((value) => {
2432
+ try {
2433
+ const url = new URL(value);
2434
+ if (url.origin !== value) return false;
2435
+ if (url.protocol === "https:") return true;
2436
+ return url.protocol === "http:" && (url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname.endsWith(".localhost") || url.hostname === "[::1]");
2437
+ } catch {
2438
+ return false;
2439
+ }
2440
+ }, { message: "must be an https: origin (http: only on loopback), with no path" });
2441
+ /** The schema of {@link RemoteServerConfig}. */
2442
+ const Config = z.strictObject({
2443
+ apiOrigin: Origin,
2444
+ domains: z.strictObject({
2445
+ active: HostName,
2446
+ spares: z.array(HostName).optional()
2447
+ }),
2448
+ /**
2449
+ * The scheme the user-content domain is served on: `https` behind a TLS terminator, `http`
2450
+ * for a loopback test. Default `https`.
2451
+ */
2452
+ scheme: z.enum(["https", "http"]).optional(),
2453
+ trustedProxies: z.array(z.string()).optional(),
2454
+ identityProviders: z.array(z.strictObject({
2455
+ id: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/),
2456
+ kind: z.enum([
2457
+ "development",
2458
+ "oidc",
2459
+ "github"
2460
+ ]),
2461
+ label: z.string().min(1).optional(),
2462
+ issuer: z.string().optional(),
2463
+ clientId: z.string().optional(),
2464
+ clientSecretFile: z.string().optional()
2465
+ })).optional(),
2466
+ rateLimits: z.strictObject({
2467
+ perIp: z.strictObject({
2468
+ submissions: RateSchema.optional(),
2469
+ requests: RateSchema.optional()
2470
+ }).optional(),
2471
+ perLink: z.strictObject({
2472
+ submissions: RateSchema.optional(),
2473
+ relayedRuns: RateSchema.optional()
2474
+ }).optional(),
2475
+ ipv6Prefix: z.int().min(1).max(128).optional()
2476
+ }).optional(),
2477
+ ledger: z.strictObject({ walAutocheckpoint: z.int().min(0).optional() }).optional(),
2478
+ relay: z.strictObject({
2479
+ waitingRunsPerArtifact: z.int().min(1).optional(),
2480
+ drainPerSecond: z.number().positive().optional()
2481
+ }).optional(),
2482
+ homes: z.strictObject({ idleCloseMinutes: z.number().positive().optional() }).optional(),
2483
+ framing: z.strictObject({ frameAncestors: z.literal("'none'") }).optional(),
2484
+ operator: z.string().optional(),
2485
+ chatHosts: z.record(z.string(), z.unknown()).optional()
2486
+ });
2487
+ /** The configuration keys, and the variable each also comes from. */
2488
+ const KEYS = Object.keys(Config.shape);
2489
+ /** `apiOrigin` → `MOSTRA_SERVER_API_ORIGIN`. */
2490
+ function variableOf(key) {
2491
+ return `MOSTRA_SERVER_${key.replace(/[A-Z]/g, (letter) => `_${letter}`).toUpperCase()}`;
2492
+ }
2493
+ function invalid(message) {
2494
+ return new RpcError(createDiagnostic("MOSTRA_REMOTE_CONFIG_INVALID", { message }));
2495
+ }
2496
+ /**
2497
+ * Reads the configuration: the file, then each `MOSTRA_SERVER_<KEY>` (a string for a string key,
2498
+ * JSON for the others) over it. Throws `MOSTRA_REMOTE_CONFIG_INVALID` naming the first key it
2499
+ * can't use.
2500
+ */
2501
+ function readServerConfig(file, env) {
2502
+ let raw = {};
2503
+ if (file !== void 0) {
2504
+ let text;
2505
+ try {
2506
+ text = readFileSync(file, "utf8");
2507
+ } catch (error) {
2508
+ throw invalid(`The configuration file ${file} can't be read (${error.code ?? "error"}).`);
2509
+ }
2510
+ try {
2511
+ const parsed = JSON.parse(text);
2512
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("not an object");
2513
+ raw = parsed;
2514
+ } catch {
2515
+ throw invalid(`The configuration file ${file} isn't a JSON object.`);
2516
+ }
2517
+ }
2518
+ for (const key of KEYS) {
2519
+ const variable = variableOf(key);
2520
+ const value = env[variable];
2521
+ if (value === void 0 || value === "") continue;
2522
+ if (key === "apiOrigin" || key === "operator" || key === "scheme") raw[key] = value;
2523
+ else try {
2524
+ raw[key] = JSON.parse(value);
2525
+ } catch {
2526
+ throw invalid(`${variable} isn't JSON.`);
2527
+ }
2528
+ }
2529
+ const checked = Config.safeParse(raw);
2530
+ if (!checked.success) {
2531
+ const issue = checked.error.issues[0];
2532
+ throw invalid(`The configuration key \`${issue?.path.join(".") || "(configuration)"}\` can't be used: ${issue?.message ?? "invalid"}.`);
2533
+ }
2534
+ const config = checked.data;
2535
+ const domains = [config.domains.active, ...config.domains.spares ?? []];
2536
+ const api = new URL(config.apiOrigin).host;
2537
+ if (domains.some((domain) => domain === api || api.endsWith(`.${domain}`))) throw invalid("The configuration key `apiOrigin` can't be on a user-content domain: sign-in and the binding live apart from tenant pages (D165 item 7).");
2538
+ if (new Set(domains).size !== domains.length) throw invalid("The configuration key `domains` names one domain twice.");
2539
+ return config;
2540
+ }
2541
+ //#endregion
2542
+ //#region src/server/index.ts
2543
+ /**
2544
+ * The remote server (ARCHITECTURE §15, INTERFACES §18, D165): one process holding many hosted
2545
+ * homes behind one listener. It speaks plain HTTP behind a TLS terminator and routes every request
2546
+ * by its exact `Host`: the API origin (the network binding, version files, sign-in) or a
2547
+ * user-content domain (the hosted shell on its apex, an artifact's pages on its route's label).
2548
+ * It runs no artifact code: server code runs on each artifact's owner instance, through the relay.
2549
+ *
2550
+ * ```ts
2551
+ * const server = await startServer({ data: "/var/lib/mostra", config: readServerConfig(file, env), … });
2552
+ * // … mostra-runtime server serves until it is stopped
2553
+ * await server.close();
2554
+ * ```
2555
+ */
2556
+ /** An answer as JSON, with the headers every server answer carries. */
2557
+ function json(response, status, body) {
2558
+ const text = JSON.stringify(body);
2559
+ response.writeHead(status, {
2560
+ "content-type": "application/json; charset=utf-8",
2561
+ "content-length": Buffer.byteLength(text),
2562
+ "cache-control": "no-store",
2563
+ "cross-origin-resource-policy": "same-origin",
2564
+ "referrer-policy": "no-referrer",
2565
+ "x-content-type-options": "nosniff"
2566
+ });
2567
+ response.end(text);
2568
+ }
2569
+ function refusal$1(response, status, diagnostic) {
2570
+ json(response, status, diagnostic);
2571
+ }
2572
+ /** Splits `host:port`, with `[::1]:port` for IPv6. */
2573
+ function parseListen(listen) {
2574
+ const match = /^(\[[^\]]+\]|[^:]+):(\d{1,5})$/.exec(listen);
2575
+ if (!match) throw new RpcError(createDiagnostic("MOSTRA_REMOTE_CONFIG_INVALID", { message: `--listen ${listen} isn't host:port.` }));
2576
+ return {
2577
+ host: match[1].replace(/^\[|\]$/g, ""),
2578
+ port: Number(match[2])
2579
+ };
2580
+ }
2581
+ /** Starts the remote server: its data directory, then its listener. */
2582
+ async function startServer(options) {
2583
+ const { config, log } = options;
2584
+ let auth;
2585
+ const shellDir = locateShell(options.env);
2586
+ const data = await openDataDirectory({
2587
+ dir: options.data,
2588
+ runtimeVersion: options.runtimeVersion,
2589
+ owner: options.owner,
2590
+ log,
2591
+ env: options.env,
2592
+ assembler: {
2593
+ assemble: (home) => openHostedHome({
2594
+ id: home.id,
2595
+ dir: home.dir,
2596
+ ledger: home.ledger,
2597
+ incarnation: home.incarnation,
2598
+ directory: data.directory,
2599
+ filesDir: join(options.data, "files"),
2600
+ auth,
2601
+ runtimeVersion: options.runtimeVersion,
2602
+ log,
2603
+ scheme: config.scheme ?? "https",
2604
+ domains: {
2605
+ active: config.domains.active,
2606
+ spares: config.domains.spares ?? []
2607
+ },
2608
+ shellDir,
2609
+ relay: {
2610
+ waitingRunsPerArtifact: config.relay?.waitingRunsPerArtifact,
2611
+ drainPerSecond: config.relay?.drainPerSecond,
2612
+ ...config.rateLimits?.perLink?.relayedRuns ? { perLink: {
2613
+ count: config.rateLimits.perLink.relayedRuns.count,
2614
+ perMs: durationMs(config.rateLimits.perLink.relayedRuns.per)
2615
+ } } : {},
2616
+ ...options.env["MOSTRA_TEST_RELAY_LIVE_MS"] !== void 0 ? { liveRenewMs: Number(options.env["MOSTRA_TEST_RELAY_LIVE_MS"]) } : {},
2617
+ ...options.env["MOSTRA_TEST_RELAY_SWEEP_MS"] !== void 0 ? { sweepMs: Number(options.env["MOSTRA_TEST_RELAY_SWEEP_MS"]) } : {}
2618
+ }
2619
+ }),
2620
+ disassemble: (home) => home.stop(),
2621
+ incarnation: (home) => home.incarnation(),
2622
+ busy: (home) => home.busy()
2623
+ },
2624
+ ...options.restored !== void 0 ? { restored: options.restored } : {},
2625
+ ...config.homes?.idleCloseMinutes !== void 0 ? { idleCloseMs: config.homes.idleCloseMinutes * 6e4 } : {},
2626
+ ...config.ledger?.walAutocheckpoint !== void 0 ? { walAutocheckpoint: config.ledger.walAutocheckpoint } : {}
2627
+ });
2628
+ auth = createAuthorization({
2629
+ directory: data.directory,
2630
+ config,
2631
+ log,
2632
+ ...Number(options.env["MOSTRA_TEST_ACCESS_TTL_MS"]) > 0 ? { accessTtlMs: Number(options.env["MOSTRA_TEST_ACCESS_TTL_MS"]) } : {},
2633
+ linked: ({ homeId, linkId, name }) => {
2634
+ data.home(homeId).then((home) => home.assembled.ledger.write((db) => appendEvent(db, {
2635
+ artifactId: null,
2636
+ type: "instance.linked",
2637
+ actor: { kind: "mostra" },
2638
+ payload: {
2639
+ instanceId: linkId,
2640
+ name
2641
+ }
2642
+ })), (error) => log.error("server.linked_event_failed", {
2643
+ home: homeId,
2644
+ error
2645
+ }));
2646
+ }
2647
+ });
2648
+ const api = createApi({
2649
+ config,
2650
+ auth,
2651
+ log,
2652
+ filesDir: join(options.data, "files"),
2653
+ home: async (id) => (await data.home(id)).assembled,
2654
+ touch: (id) => data.touch(id),
2655
+ ...Number(options.env["MOSTRA_TEST_GRANT_RECHECK_MS"]) > 0 ? { recheckMs: Number(options.env["MOSTRA_TEST_GRANT_RECHECK_MS"]) } : {}
2656
+ });
2657
+ const apiHost = new URL(config.apiOrigin).host;
2658
+ const domains = /* @__PURE__ */ new Set([config.domains.active, ...config.domains.spares ?? []]);
2659
+ const onRequest = (request, response) => {
2660
+ const host = (request.headers.host ?? "").toLowerCase();
2661
+ delete request.headers.cookie;
2662
+ const path = (request.url ?? "/").split("?")[0] ?? "/";
2663
+ if (host === apiHost) {
2664
+ if (request.method === "GET" && path === "/health") {
2665
+ json(response, 200, {
2666
+ status: "ok",
2667
+ homes: data.open().length
2668
+ });
2669
+ return;
2670
+ }
2671
+ api.request(request, response, path).catch((error) => {
2672
+ log.error("server.api_failed", {
2673
+ path,
2674
+ error
2675
+ });
2676
+ if (!response.headersSent) refusal$1(response, 500, createDiagnostic("MOSTRA_HOST_INTERNAL_ERROR", { message: "The server failed to answer." }));
2677
+ else response.destroy();
2678
+ });
2679
+ return;
2680
+ }
2681
+ const domain = [...domains].find((candidate) => host === candidate || host.endsWith(`.${candidate}`));
2682
+ if (domain === void 0) {
2683
+ refusal$1(response, 421, createDiagnostic("MOSTRA_HYGIENE_HOST_REFUSED", { message: "This server serves no pages at this host." }));
2684
+ return;
2685
+ }
2686
+ response.setHeader("origin-agent-cluster", "?1");
2687
+ response.setHeader("x-robots-tag", "noindex");
2688
+ hosted(request, response, host, domain, path).catch((error) => {
2689
+ log.error("server.hosted_failed", { error });
2690
+ if (!response.headersSent) refusal$1(response, 500, createDiagnostic("MOSTRA_HOST_INTERNAL_ERROR", { message: "The server failed to answer." }));
2691
+ else response.destroy();
2692
+ });
2693
+ };
2694
+ const notServed = (response) => refusal$1(response, 404, createDiagnostic("MOSTRA_HYGIENE_NOT_SERVED", { message: "Nothing is served at this path." }));
2695
+ /** The shell's own files, the same on every domain's apex. */
2696
+ const assets = getRequestListener(async (request) => (shellDir === void 0 ? void 0 : await shellAssetResponse(shellDir, request)) ?? new Response(JSON.stringify(createDiagnostic("MOSTRA_HYGIENE_NOT_SERVED", { message: "No shell file at this path." })), {
2697
+ status: 404,
2698
+ headers: {
2699
+ "content-type": "application/json",
2700
+ "cache-control": "no-store"
2701
+ }
2702
+ }), { overrideGlobalObjects: false });
2703
+ /** A route of the directory: its home and ID, by ID or by label. */
2704
+ const routeBy = (column, value) => data.directory.read((db) => db.get(`SELECT id, home_id FROM artifact_route WHERE ${column} = ?`, value));
2705
+ /** A request on a user-content domain: the shell on its apex, a route's frames on its label. */
2706
+ const hosted = async (request, response, host, domain, path) => {
2707
+ if (host === domain) {
2708
+ if (path.startsWith("/_mostra/shell/assets/")) {
2709
+ await assets(request, response);
2710
+ return;
2711
+ }
2712
+ const match = /^\/a\/(rte_[0-9A-HJKMNP-TV-Z]{26})(?:\/|$)/.exec(path);
2713
+ const route = match?.[1] !== void 0 && RouteId.is(match[1]) ? routeBy("id", match[1]) : void 0;
2714
+ if (!route) {
2715
+ notServed(response);
2716
+ return;
2717
+ }
2718
+ await (await data.home(route.home_id)).assembled.serve(request, response, {
2719
+ kind: "shell",
2720
+ domain,
2721
+ routeId: route.id
2722
+ });
2723
+ return;
2724
+ }
2725
+ const label = host.slice(0, host.length - domain.length - 1);
2726
+ const route = /^[0-9a-hjkmnp-tv-z]{26}$/.test(label) ? routeBy("label", label) : void 0;
2727
+ if (!route) {
2728
+ refusal$1(response, 421, createDiagnostic("MOSTRA_HYGIENE_HOST_REFUSED", { message: "This server serves no pages at this host." }));
2729
+ return;
2730
+ }
2731
+ await (await data.home(route.home_id)).assembled.serve(request, response, {
2732
+ kind: "frame",
2733
+ domain,
2734
+ routeId: route.id
2735
+ });
2736
+ };
2737
+ const listener = createServer({ maxHeaderSize: 65536 }, onRequest);
2738
+ listener.keepAliveTimeout = 305e3;
2739
+ listener.headersTimeout = 3e4;
2740
+ listener.requestTimeout = 12e4;
2741
+ listener.on("upgrade", (request, socket, head) => {
2742
+ const host = (request.headers.host ?? "").toLowerCase();
2743
+ const path = (request.url ?? "/").split("?")[0] ?? "/";
2744
+ if (host === apiHost) {
2745
+ api.upgrade(request, socket, head, path);
2746
+ return;
2747
+ }
2748
+ socket.end("HTTP/1.1 404 Not Found\r\nconnection: close\r\ncontent-length: 0\r\n\r\n");
2749
+ });
2750
+ const { host, port } = parseListen(options.listen ?? "127.0.0.1:8080");
2751
+ try {
2752
+ await new Promise((resolve, reject) => {
2753
+ listener.once("error", reject);
2754
+ listener.listen(port, host, () => {
2755
+ listener.off("error", reject);
2756
+ resolve();
2757
+ });
2758
+ });
2759
+ } catch (error) {
2760
+ await data.close();
2761
+ throw new RpcError(createDiagnostic("MOSTRA_ENV_BIND_FAILED", { message: `The server can't listen on ${host}:${port}: ${error.code ?? error.message}.` }));
2762
+ }
2763
+ const bound = listener.address();
2764
+ const address = `http://${bound.family === "IPv6" ? `[${bound.address}]` : bound.address}:${bound.port}`;
2765
+ log.info("server.listening", {
2766
+ address,
2767
+ apiOrigin: config.apiOrigin,
2768
+ domains: [...domains]
2769
+ });
2770
+ let closing;
2771
+ return {
2772
+ address,
2773
+ config,
2774
+ close() {
2775
+ closing ??= (async () => {
2776
+ api.close();
2777
+ await new Promise((resolve) => {
2778
+ listener.close(() => resolve());
2779
+ listener.closeAllConnections();
2780
+ });
2781
+ await data.close();
2782
+ log.info("server.stopped", {});
2783
+ })();
2784
+ return closing;
2785
+ }
2786
+ };
2787
+ }
2788
+ //#endregion
8
2789
  //#region src/bin.ts
9
2790
  /**
10
2791
  * `mostra-runtime`, the runtime bundle's entry point (D85).
@@ -34,7 +2815,11 @@ const EXIT = {
34
2815
  usage: 2,
35
2816
  environment: 3
36
2817
  };
37
- const USAGE = ["usage: mostra-runtime <host|daemon> [--home <dir>] [--bind <address> [--url-host <name>]] [--always-on]", " mostra-runtime service <install|uninstall|status> [--home <dir>] [--no-start]"].join("\n");
2818
+ const USAGE = [
2819
+ "usage: mostra-runtime <host|daemon> [--home <dir>] [--bind <address> [--url-host <name>]] [--always-on]",
2820
+ " mostra-runtime service <install|uninstall|status> [--home <dir>] [--no-start]",
2821
+ " mostra-runtime server --data <dir> [--config <file>] [--listen <host:port>] [--restored <homeId|all>]"
2822
+ ].join("\n");
38
2823
  process.stdout.on("error", () => {});
39
2824
  process.stderr.on("error", () => {});
40
2825
  const mirror = (line) => {
@@ -99,7 +2884,7 @@ function handleSignals(instance) {
99
2884
  async function main(argv) {
100
2885
  let parsed;
101
2886
  try {
102
- parsed = parse(argv);
2887
+ parsed = parse$1(argv);
103
2888
  } catch (error) {
104
2889
  process.stderr.write(`${error.message}\n${USAGE}\n`);
105
2890
  return EXIT.usage;
@@ -111,6 +2896,12 @@ async function main(argv) {
111
2896
  }
112
2897
  const [mode, ...rest] = positionals;
113
2898
  if (mode === "service" && !values.help) return await service(rest, values.home, values["no-start"] === true);
2899
+ if (mode === "server" && !values.help && rest.length === 0) return await remoteServer({
2900
+ data: values.data,
2901
+ config: values.config,
2902
+ listen: values.listen,
2903
+ restored: values.restored ?? []
2904
+ });
114
2905
  if (values.help || mode !== "host" && mode !== "daemon" || rest.length > 0) {
115
2906
  (values.help ? process.stdout : process.stderr).write(`${USAGE}\n`);
116
2907
  return values.help ? EXIT.ok : EXIT.usage;
@@ -166,6 +2957,79 @@ async function main(argv) {
166
2957
  return exitCode;
167
2958
  }
168
2959
  }
2960
+ /**
2961
+ * `mostra-runtime server`: the remote server (INTERFACES §18.1). Prints one JSON line on stdout
2962
+ * (`{"status":"started","address",…}` or `{"status":"failed","diagnostic"}` with exit 3), then
2963
+ * serves until SIGTERM, SIGINT or Ctrl+Break, and stops cleanly: every hosted home is closed and
2964
+ * every lock released. Logs go to the data directory's `logs/`.
2965
+ */
2966
+ async function remoteServer(args) {
2967
+ if (args.data === void 0) {
2968
+ process.stderr.write(`mostra-runtime server needs --data <dir>.\n${USAGE}\n`);
2969
+ return EXIT.usage;
2970
+ }
2971
+ try {
2972
+ checkPlatform();
2973
+ mkdirSync(args.data, {
2974
+ recursive: true,
2975
+ mode: 448
2976
+ });
2977
+ const data = realPath(args.data);
2978
+ const config = readServerConfig(args.config, process.env);
2979
+ const me = await readProcess(process.pid);
2980
+ if (!me) throw new Error("Couldn't read this process's own start time.");
2981
+ const log = openFileLog({
2982
+ dir: join(data, "logs"),
2983
+ mirror
2984
+ });
2985
+ const server = await startServer({
2986
+ data,
2987
+ config,
2988
+ ...args.listen !== void 0 ? { listen: args.listen } : {},
2989
+ restored: args.restored,
2990
+ runtimeVersion: runtimeVersion(),
2991
+ owner: {
2992
+ pid: me.pid,
2993
+ startTime: me.startTime
2994
+ },
2995
+ log,
2996
+ env: process.env
2997
+ });
2998
+ process.stdout.write(`${JSON.stringify({
2999
+ status: "started",
3000
+ pid: process.pid,
3001
+ address: server.address,
3002
+ data
3003
+ })}\n`);
3004
+ return await new Promise((resolve) => {
3005
+ let stopping = false;
3006
+ const stop = () => {
3007
+ if (stopping) return;
3008
+ stopping = true;
3009
+ server.close().then(() => resolve(EXIT.ok), (error) => {
3010
+ log.error("server.stop_failed", { error });
3011
+ resolve(EXIT.failure);
3012
+ });
3013
+ };
3014
+ for (const signal of [
3015
+ "SIGTERM",
3016
+ "SIGINT",
3017
+ "SIGBREAK"
3018
+ ]) process.on(signal, stop);
3019
+ });
3020
+ } catch (error) {
3021
+ const diagnostic = diagnosticOf(error);
3022
+ process.stdout.write(`${JSON.stringify({
3023
+ status: "failed",
3024
+ diagnostic
3025
+ })}\n`);
3026
+ mirror(`${JSON.stringify({
3027
+ level: "error",
3028
+ diagnostic
3029
+ })}\n`);
3030
+ return error instanceof RpcError ? EXIT.environment : EXIT.failure;
3031
+ }
3032
+ }
169
3033
  /** `mostra-runtime service …`: the home's login service, as one JSON line (D62, RT-08). */
170
3034
  async function service(args, home, noStart) {
171
3035
  const [action, ...extra] = args;
@@ -221,7 +3085,7 @@ async function service(args, home, noStart) {
221
3085
  return EXIT.environment;
222
3086
  }
223
3087
  }
224
- function parse(argv) {
3088
+ function parse$1(argv) {
225
3089
  return parseArgs({
226
3090
  args: [...argv],
227
3091
  allowPositionals: true,
@@ -235,7 +3099,14 @@ function parse(argv) {
235
3099
  type: "boolean",
236
3100
  short: "h"
237
3101
  },
238
- version: { type: "boolean" }
3102
+ version: { type: "boolean" },
3103
+ data: { type: "string" },
3104
+ config: { type: "string" },
3105
+ listen: { type: "string" },
3106
+ restored: {
3107
+ type: "string",
3108
+ multiple: true
3109
+ }
239
3110
  }
240
3111
  });
241
3112
  }