@mostra/runtime 0.6.2 → 0.8.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.
@@ -7,7 +7,9 @@
7
7
  * 1. the `Origin` and content type its intent needs (`checkRequest`; the envelope was checked
8
8
  * before routing);
9
9
  * 2. the rate limit, on token paths;
10
- * 3. the session, bound to this origin, with a live token (401, 410);
10
+ * 3. the session, bound to this origin, with a live token (401, 410): its cookie in cookie mode,
11
+ * its frame header in worker mode (D70), or a single-use stream ticket on stream routes
12
+ * (D158 item 5);
11
13
  * 4. the session's CSRF token, on mutations;
12
14
  * 5. the scope.
13
15
  *
@@ -17,6 +19,7 @@
17
19
  import {
18
20
  type CapabilityScope,
19
21
  checkRequest,
22
+ FRAME_SESSION_HEADER,
20
23
  type Refusal,
21
24
  type RequestIntent,
22
25
  type RequestPolicy,
@@ -50,6 +53,11 @@ export interface RouteSpec {
50
53
  * action scope; the handler checks the exact function (D96).
51
54
  */
52
55
  readonly scope?: (params: Readonly<Record<string, string>>) => CapabilityScope | "any-action";
56
+ /**
57
+ * An event stream (SSE): refused on a face streams don't pass, and in worker mode without a
58
+ * ticket, so the page long-polls instead (D158 item 5).
59
+ */
60
+ readonly sse?: true;
53
61
  /** Serves the request. Absent: declared for a later package, answered with 501. */
54
62
  readonly handler?: (context: RouteContext) => Response | Promise<Response>;
55
63
  }
@@ -64,6 +72,8 @@ export interface RouteContext {
64
72
  readonly session?: ResolvedSession;
65
73
  /** Whether the client is navigating (answer with HTML rather than JSON). */
66
74
  readonly document: boolean;
75
+ /** The address of the connection's peer: on a face, the tunnel's own process (D158 item 2). */
76
+ readonly remote: string | undefined;
67
77
  }
68
78
 
69
79
  /** What a listener contributes to every route's checks. */
@@ -78,6 +88,13 @@ export interface ListenerChecks {
78
88
  readonly frameAncestors: () => string;
79
89
  /** The artifact a request is for: fixed on an artifact's listener, from the path on the shell. */
80
90
  readonly artifactOf: (params: Readonly<Record<string, string>>) => string | undefined;
91
+ /**
92
+ * How this listener's sessions authenticate (D70): `cookie` (the default), or `worker`, where a
93
+ * frame's service worker sends the session's secret as `X-Mostra-Frame`.
94
+ */
95
+ readonly mode?: () => "cookie" | "worker";
96
+ /** Whether event streams pass to this listener's browsers; `false` behind a quick tunnel. */
97
+ readonly streams?: () => boolean;
81
98
  }
82
99
 
83
100
  /** Logs a refusal without any of the request's capability material, and answers it. */
@@ -148,14 +165,41 @@ export function mount(
148
165
  const limited = checks.capabilities.limited(artifactId);
149
166
  if (limited) return refuse(checks, limited, meta);
150
167
  }
151
- // 3. The session.
168
+ // 3. The session: a stream ticket on a stream route, else the cookie, or the frame header
169
+ // in worker mode. An event stream only passes where streams do, and in worker mode only
170
+ // with a ticket: a stream through the service worker stalls in Firefox (VERIFIED_FACTS).
171
+ const mode = checks.mode?.() ?? "cookie";
172
+ const ticket = route.intent === "stream" ? url.searchParams.get("ticket") : null;
173
+ if (route.sse && (checks.streams?.() === false || (mode === "worker" && ticket === null))) {
174
+ return refuse(
175
+ checks,
176
+ refusal(
177
+ "MOSTRA_HYGIENE_NOT_SERVED",
178
+ checks.streams?.() === false
179
+ ? "Event streams don't pass this address; long-poll instead (events/poll)."
180
+ : "A worker-mode frame opens its event stream with a ticket; long-poll instead.",
181
+ 503,
182
+ ),
183
+ meta,
184
+ );
185
+ }
152
186
  let session: ResolvedSession | undefined;
153
187
  if (route.auth === "session" && artifactId !== undefined) {
154
- const resolved = checks.capabilities.session(
155
- cookieValues(request.headers.get("cookie"), checks.cookieName()),
156
- policy.origin,
157
- artifactId,
158
- );
188
+ const resolved =
189
+ ticket !== null
190
+ ? checks.capabilities.redeemStreamTicket(ticket, policy.origin, artifactId, "stream")
191
+ : mode === "worker"
192
+ ? checks.capabilities.session(
193
+ [request.headers.get(FRAME_SESSION_HEADER) ?? ""],
194
+ policy.origin,
195
+ artifactId,
196
+ "worker",
197
+ )
198
+ : checks.capabilities.session(
199
+ cookieValues(request.headers.get("cookie"), checks.cookieName()),
200
+ policy.origin,
201
+ artifactId,
202
+ );
159
203
  if (isRefusal(resolved)) return refuse(checks, resolved, meta);
160
204
  session = resolved;
161
205
  // 4. The CSRF token of this session.
@@ -189,6 +233,7 @@ export function mount(
189
233
  artifactId,
190
234
  ...(session ? { session } : {}),
191
235
  document,
236
+ remote: incoming.socket.remoteAddress,
192
237
  });
193
238
  };
194
239
  if (route.method === "GET") app.get(route.path, handle);
@@ -0,0 +1,204 @@
1
+ /**
2
+ * Worker-mode frame sessions (D70, D158 item 5): where the shell and the artifact are two sites,
3
+ * no cookie reaches the artifact's frame (VERIFIED_FACTS, cross-site frames). The frame enters
4
+ * through a bootstrap page instead: it exchanges the shell's single-use ticket for a frame
5
+ * session, installs Mostra's service worker at `/`, and enters the version, whose every
6
+ * same-origin request then carries the session in a header. Event streams, polls and WebSockets
7
+ * bypass the worker with single-use tickets, since Firefox stalls on endless responses a worker
8
+ * passes on.
9
+ *
10
+ * This module holds the two documents the browser runs: the bootstrap page and the worker. Both
11
+ * are plain scripts with no imports, served by the gateway from the artifact's origin.
12
+ */
13
+ import { FRAME_SESSION_HEADER } from "@mostra/protocol";
14
+
15
+ /** Where the service worker is served; its registration's scope is `/`. */
16
+ export const SERVICE_WORKER_PATH = "/_mostra/sw.js";
17
+
18
+ /** The IndexedDB the frame session's secret is kept in, per artifact origin and top-level site. */
19
+ const DB = "mostra-frame";
20
+
21
+ /**
22
+ * The service worker (D70): it adds the frame session's header to every same-origin request but
23
+ * its own script, the bootstrap's, and ticketed ones (`?ticket=`: streams, polls and sockets),
24
+ * and keeps the secret in IndexedDB, since a browser stops idle workers and their memory goes.
25
+ * A request a header can't be added to as made (a `no-cors` script or image, a navigation) is
26
+ * sent again as a same-origin request, which carries it.
27
+ */
28
+ export const SERVICE_WORKER_SOURCE: string = `// Mostra's frame-session worker (D70). It signs this origin's requests for the artifact's frame.
29
+ "use strict";
30
+ const HEADER = ${JSON.stringify(FRAME_SESSION_HEADER)};
31
+ const DB = ${JSON.stringify(DB)};
32
+ const STORE = "session";
33
+ let secret;
34
+ function store(mode, act) {
35
+ return new Promise((resolve, reject) => {
36
+ const open = indexedDB.open(DB, 1);
37
+ open.onupgradeneeded = () => open.result.createObjectStore(STORE);
38
+ open.onerror = () => reject(open.error);
39
+ open.onsuccess = () => {
40
+ const db = open.result;
41
+ const tx = db.transaction(STORE, mode);
42
+ const request = act(tx.objectStore(STORE));
43
+ tx.oncomplete = () => { db.close(); resolve(request.result); };
44
+ tx.onerror = tx.onabort = () => { db.close(); reject(tx.error); };
45
+ };
46
+ });
47
+ }
48
+ async function current() {
49
+ if (secret === undefined) {
50
+ try { secret = await store("readonly", (s) => s.get("secret")); } catch { secret = undefined; }
51
+ }
52
+ return secret;
53
+ }
54
+ self.addEventListener("install", () => { self.skipWaiting(); });
55
+ self.addEventListener("activate", (event) => { event.waitUntil(self.clients.claim()); });
56
+ self.addEventListener("message", (event) => {
57
+ const data = event.data;
58
+ if (!data || data.type !== "mostra/frame-session" || typeof data.secret !== "string") return;
59
+ secret = data.secret;
60
+ const port = event.ports[0];
61
+ event.waitUntil(
62
+ store("readwrite", (s) => s.put(data.secret, "secret")).then(
63
+ () => port && port.postMessage({ ok: true }),
64
+ (error) => port && port.postMessage({ ok: false, message: String(error) }),
65
+ ),
66
+ );
67
+ });
68
+ self.addEventListener("fetch", (event) => {
69
+ const request = event.request;
70
+ const url = new URL(request.url);
71
+ if (url.origin !== self.location.origin) return;
72
+ if (url.pathname === ${JSON.stringify(SERVICE_WORKER_PATH)} || url.pathname === "/_mostra/enter") return;
73
+ if (url.searchParams.has("ticket")) return;
74
+ event.respondWith(signed(request));
75
+ });
76
+ async function signed(request) {
77
+ const value = await current();
78
+ if (!value) return fetch(request);
79
+ const headers = new Headers(request.headers);
80
+ headers.set(HEADER, value);
81
+ const navigate = request.mode === "navigate";
82
+ // Sent on, a navigation is an ordinary request: the gateway learns it was one from this header.
83
+ if (navigate) headers.set("x-mostra-navigation", "1");
84
+ const init = {
85
+ method: request.method,
86
+ headers,
87
+ mode: navigate || request.mode === "no-cors" ? "same-origin" : request.mode,
88
+ credentials: request.credentials,
89
+ cache: request.cache === "only-if-cached" ? "default" : request.cache,
90
+ redirect: navigate ? "manual" : request.redirect,
91
+ referrerPolicy: request.referrerPolicy,
92
+ integrity: request.integrity,
93
+ keepalive: request.keepalive,
94
+ signal: request.signal,
95
+ };
96
+ if (request.method !== "GET" && request.method !== "HEAD") init.body = await request.arrayBuffer();
97
+ return fetch(new Request(request.url, init));
98
+ }
99
+ `;
100
+
101
+ /**
102
+ * The bootstrap page at `/_mostra/enter#t=<ticket>` (D70): it takes the ticket from the fragment
103
+ * (so no server, log or `Referer` sees it), exchanges it at `POST /_mostra/enter` (sending the
104
+ * session it kept, so a frame that re-enters keeps its session and switches version), installs
105
+ * the worker at `/`, hands it the secret, tells the shell (`mostra/frameSession.entered`) and
106
+ * enters the version at `/`. Whatever stops it is reported to the shell as
107
+ * `mostra/frameSession.failed` with `MOSTRA_HYGIENE_FRAME_SESSION`.
108
+ */
109
+ export const BOOTSTRAP_PAGE: string = `<!doctype html>
110
+ <html lang="en">
111
+ <head>
112
+ <meta charset="utf-8">
113
+ <meta name="referrer" content="no-referrer">
114
+ <meta name="viewport" content="width=device-width, initial-scale=1">
115
+ <title>Mostra</title>
116
+ <style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:flex;justify-content:center;align-items:center;padding:2rem;text-align:center;color-scheme:light dark;opacity:.8}</style>
117
+ </head>
118
+ <body>
119
+ <script>
120
+ (async () => {
121
+ "use strict";
122
+ const HEADER = ${JSON.stringify(FRAME_SESSION_HEADER)};
123
+ let shell = "*";
124
+ const fail = (reason, message) => {
125
+ document.body.textContent = message;
126
+ parent.postMessage(
127
+ { jsonrpc: "2.0", method: "mostra/frameSession.failed",
128
+ params: { code: "MOSTRA_HYGIENE_FRAME_SESSION", reason, message } },
129
+ shell,
130
+ );
131
+ };
132
+ const kept = () => new Promise((resolve) => {
133
+ try {
134
+ const open = indexedDB.open(${JSON.stringify(DB)}, 1);
135
+ open.onupgradeneeded = () => open.result.createObjectStore("session");
136
+ open.onerror = () => resolve(undefined);
137
+ open.onsuccess = () => {
138
+ const db = open.result;
139
+ try {
140
+ const read = db.transaction("session", "readonly").objectStore("session").get("secret");
141
+ read.onsuccess = () => { db.close(); resolve(typeof read.result === "string" ? read.result : undefined); };
142
+ read.onerror = () => { db.close(); resolve(undefined); };
143
+ } catch { db.close(); resolve(undefined); }
144
+ };
145
+ } catch { resolve(undefined); }
146
+ });
147
+ const ticket = new URLSearchParams(location.hash.slice(1)).get("t");
148
+ history.replaceState(null, "", location.pathname);
149
+ if (!ticket) return fail("refused", "This frame was opened without a ticket.");
150
+ if (!("serviceWorker" in navigator) || typeof indexedDB === "undefined") {
151
+ return fail("unsupported", "This browser offers the artifact's frame no service worker here, which this link needs.");
152
+ }
153
+ let answer;
154
+ try {
155
+ const previous = await kept();
156
+ const response = await fetch("/_mostra/enter", {
157
+ method: "POST",
158
+ credentials: "omit",
159
+ cache: "no-store",
160
+ headers: { "content-type": "application/json", ...(previous ? { [HEADER]: previous } : {}) },
161
+ body: JSON.stringify({ ticket }),
162
+ });
163
+ answer = await response.json().catch(() => ({}));
164
+ if (!response.ok) return fail("refused", answer.message || "The frame's entry was refused.");
165
+ } catch (error) {
166
+ return fail("refused", "The frame couldn't reach Mostra: " + error);
167
+ }
168
+ shell = answer.shellOrigin;
169
+ try {
170
+ const found = await navigator.serviceWorker.getRegistration("/");
171
+ const script = found && (found.active || found.waiting || found.installing);
172
+ if (script && new URL(script.scriptURL).pathname !== ${JSON.stringify(SERVICE_WORKER_PATH)}) {
173
+ console.warn("Mostra replaced another service worker at / on this origin: a worker-mode frame needs its own there (MOSTRA_HYGIENE_FRAME_SESSION).");
174
+ }
175
+ const registration = await navigator.serviceWorker.register(${JSON.stringify(SERVICE_WORKER_PATH)}, { scope: "/", updateViaCache: "none" });
176
+ const worker = registration.installing || registration.waiting || registration.active;
177
+ if (!worker) throw new Error("no worker");
178
+ if (worker.state !== "activated") {
179
+ await new Promise((resolve, reject) => {
180
+ const timer = setTimeout(() => reject(new Error("the worker didn't activate in 20 s")), 20000);
181
+ worker.addEventListener("statechange", () => {
182
+ if (worker.state === "activated") { clearTimeout(timer); resolve(); }
183
+ if (worker.state === "redundant") { clearTimeout(timer); reject(new Error("the worker was replaced")); }
184
+ });
185
+ });
186
+ }
187
+ const stored = await new Promise((resolve) => {
188
+ const channel = new MessageChannel();
189
+ const timer = setTimeout(() => resolve({ ok: false, message: "no answer" }), 10000);
190
+ channel.port1.onmessage = (event) => { clearTimeout(timer); resolve(event.data); };
191
+ worker.postMessage({ type: "mostra/frame-session", secret: answer.session }, [channel.port2]);
192
+ });
193
+ if (!stored || !stored.ok) throw new Error(stored && stored.message);
194
+ } catch (error) {
195
+ return fail("blocked", "This browser didn't let the artifact's frame install the service worker this link needs (" + error + ").");
196
+ }
197
+ // The shell waits for the page from here: this page's own load wasn't the page's.
198
+ parent.postMessage({ jsonrpc: "2.0", method: "mostra/frameSession.entered", params: {} }, shell);
199
+ location.replace("/");
200
+ })();
201
+ </script>
202
+ </body>
203
+ </html>
204
+ `;
@@ -24,6 +24,7 @@ import {
24
24
  type JsonRpcParams,
25
25
  type MostraInitializeResult,
26
26
  type PortTrustedControlsActivatedParams,
27
+ portAddressingExternalBaseMethod,
27
28
  portIdentityResolveMethod,
28
29
  portSecretsGetMethod,
29
30
  portTrustedControlsActivatedMethod,
@@ -100,6 +101,7 @@ import {
100
101
  import { openRegistry } from "../registry/index.ts";
101
102
  import { openSecrets, secretMethods } from "../secrets/index.ts";
102
103
  import { hasLoginService, type IdleWatch, watchIdle } from "../service/index.ts";
104
+ import { createShares, type Shares, shareCacheDir } from "../share/index.ts";
103
105
  import {
104
106
  collectVerifyCaches,
105
107
  createRunnerClient,
@@ -216,8 +218,12 @@ export const SUPPORTED_PORTS: readonly string[] = [
216
218
  "drafts",
217
219
  "trustedControls",
218
220
  "secrets",
221
+ "addressing",
219
222
  ];
220
223
 
224
+ /** How long a host's `addressing` port has to answer: a page or a minted link waits (D158). */
225
+ const ADDRESSING_TIMEOUT_MS = 5_000;
226
+
221
227
  /**
222
228
  * Starts an instance for a home (RT-06): the platform gate, then the home's lock, migrations,
223
229
  * reaping, the socket and `instance.json`. A daemon starter that finds the home owned attaches
@@ -423,6 +429,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
423
429
  // Tests move the gateway's clock to check link lifetimes (LL-05, HY-03).
424
430
  now: () => Date.now() + clockOffset,
425
431
  shellOrigin: () => gateway.shellOrigin(),
432
+ // Launch tickets only for links whose shell address the gateway serves now (D158).
433
+ servesShell: (origin) => gateway.servesShell(origin),
426
434
  });
427
435
  // The interaction core (WP-06): drafts, state, submissions, the outbox, events and waits. Its
428
436
  // host connections are the protocol server's, built below.
@@ -613,6 +621,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
613
621
  log.warn("gateway.shell_missing", { code: "MOSTRA_ENV_SHELL_MISSING" });
614
622
  const traceRequests = Boolean(environment["MOSTRA_TEST_REQUEST_LOG"]);
615
623
  if (traceRequests) log.warn("instance.test_request_log", {});
624
+ // Shares run the local fakes instead of Tailscale and cloudflared (tests and the kit only).
625
+ if (environment["MOSTRA_TEST_TUNNELS"]) log.warn("instance.test_tunnels", {});
616
626
  const gateway: Gateway = createGateway({
617
627
  ledger: home.ledger,
618
628
  log,
@@ -668,6 +678,40 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
668
678
  IDENTITY_TIMEOUT_MS,
669
679
  ),
670
680
  }),
681
+ // A host's external addresses for an artifact's links and frame (HO-10, D158 item 6).
682
+ externalBase: {
683
+ registered: () => server.registrants("addressing").length > 0,
684
+ ask: async (input) => {
685
+ const registrant = server.registrants("addressing").at(-1);
686
+ if (!registrant) return { kind: "away" };
687
+ try {
688
+ const answer = await server.callSession(
689
+ registrant.session,
690
+ portAddressingExternalBaseMethod.method,
691
+ input as unknown as JsonRpcParams,
692
+ ADDRESSING_TIMEOUT_MS,
693
+ );
694
+ const parsed = portAddressingExternalBaseMethod.result.safeParse(answer);
695
+ if (!parsed.success) {
696
+ log.warn("gateway.addressing_invalid", {
697
+ owner: registrant.owner,
698
+ artifactId: input.artifactId,
699
+ });
700
+ return { kind: "failed" };
701
+ }
702
+ return parsed.data === null
703
+ ? { kind: "none" }
704
+ : { kind: "base", base: parsed.data, owner: registrant.owner };
705
+ } catch (error) {
706
+ log.warn("gateway.addressing_failed", {
707
+ owner: registrant.owner,
708
+ artifactId: input.artifactId,
709
+ error: (error as Error).message,
710
+ });
711
+ return { kind: "failed" };
712
+ }
713
+ },
714
+ },
671
715
  activated: (event) => {
672
716
  // Best effort and never retried, like draft mirrors (D105, D108): the change is durable.
673
717
  for (const registrant of server.registrants("trustedControls")) {
@@ -694,6 +738,26 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
694
738
  }
695
739
  },
696
740
  });
741
+ // Shares (WP-13, D158): tunnels to the gateway's faces, each with a link of its own.
742
+ const shares: Shares = createShares({
743
+ ledger: home.ledger,
744
+ log,
745
+ gateway,
746
+ capabilities,
747
+ interaction,
748
+ artifacts: { get: (ref) => registry.get(canonicalRef(ref)) },
749
+ processes: manager,
750
+ environment,
751
+ toolEnvironment: artifactEnvironment(environment),
752
+ cacheDir: shareCacheDir(home.path),
753
+ now: () => Date.now() + clockOffset,
754
+ ...(environment["MOSTRA_TEST_SHARE_PROBE_MS"] !== undefined
755
+ ? { probeMs: Number(environment["MOSTRA_TEST_SHARE_PROBE_MS"]) }
756
+ : {}),
757
+ ...(environment["MOSTRA_TEST_SHARE_SWEEP_MS"] !== undefined
758
+ ? { sweepMs: Number(environment["MOSTRA_TEST_SHARE_SWEEP_MS"]) }
759
+ : {}),
760
+ });
697
761
  let gatewayStarted = false;
698
762
  let idle: IdleWatch | undefined;
699
763
  const info: InstanceInfo = {
@@ -785,6 +849,7 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
785
849
  }),
786
850
  ...dev.methods(),
787
851
  ...gateway.methods(),
852
+ ...shares.methods(),
788
853
  ...interaction.methods(),
789
854
  ...secretMethods(secrets, (ref) => registry.get(canonicalRef(ref)).id),
790
855
  ...gcMethods(
@@ -819,8 +884,10 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
819
884
  artifactId,
820
885
  origin,
821
886
  })),
887
+ faces: [...gateway.faces()],
822
888
  }
823
889
  : undefined,
890
+ shares: () => shares.active(),
824
891
  deliveries: () => interaction.deliveries(),
825
892
  workers: () => pool.status(),
826
893
  idleExitAt: () => idle?.exitAt(),
@@ -856,6 +923,7 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
856
923
  // the answers already sent (the `mostra/shutdown` reply among them) before it exits.
857
924
  await server.close();
858
925
  await dev.stopAll();
926
+ await shares.close();
859
927
  await gateway.close();
860
928
  await pool.stopAll();
861
929
  await runner?.close();
@@ -905,6 +973,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
905
973
  interaction.start();
906
974
  // Producers that `always` run, and those hosts subscribe to, start now (LL-04).
907
975
  live.start();
976
+ // Tailnet and Funnel shares come back; what can't continue ends, with its reason (D158).
977
+ void shares.recover().catch((error: unknown) => log.error("share.recover_failed", { error }));
908
978
  home.publish(options.mode, server.socketPath ?? home.socketPath);
909
979
  // A host-spawned instance marks its home as a host's (D140 item 4).
910
980
  if (options.mode === "host" && markHostConfigured(home.path, "mostra-runtime host"))
@@ -935,6 +1005,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
935
1005
  producers: live.activity(),
936
1006
  subscriptions: interaction.subscriptionCount(),
937
1007
  devSessions: dev.count(),
1008
+ // An active share keeps a daemon from its idle exit (D133, WP-13).
1009
+ shares: shares.count(),
938
1010
  // A home with a login service is always-on, whoever started its daemon (D133).
939
1011
  loginService: hasLoginService(home.path, environment) ? 1 : 0,
940
1012
  }),
@@ -91,7 +91,9 @@ import {
91
91
  viewControls,
92
92
  viewer,
93
93
  viewerForHost,
94
+ viewerForLink,
94
95
  viewerForSpec,
96
+ viewerForTailnet,
95
97
  viewFor,
96
98
  } from "./viewers.ts";
97
99
  import { waitFor } from "./wait.ts";
@@ -157,6 +159,10 @@ export interface Interaction {
157
159
  viewerForSpec(db: LedgerDb, spec: ViewerSpec): string;
158
160
  /** The viewer a host's identity port named (D143 item 2), in a transaction of its own. */
159
161
  viewerForHost(spec: ViewerSpec): string;
162
+ /** A tailnet person by login (D158 item 2), in a transaction of its own. */
163
+ viewerForTailnet(spec: ViewerSpec): string;
164
+ /** A link's own viewer, for a tunnel visitor nobody named (D158 item 2). */
165
+ viewerForLink(tokenId: string, name: string): string;
160
166
  /** Records a frame load of a version (D104), with the controls in force (D108); returns its ID. */
161
167
  openView(input: {
162
168
  readonly artifactId: string;
@@ -504,6 +510,8 @@ export function createInteraction(options: InteractionOptions): Interaction {
504
510
  viewer: (viewerId) => ledger.read((db) => viewer(db, viewerId)),
505
511
  viewerForSpec,
506
512
  viewerForHost: (spec) => ledger.write((db) => viewerForHost(db, spec)),
513
+ viewerForTailnet: (spec) => ledger.write((db) => viewerForTailnet(db, spec)),
514
+ viewerForLink: (tokenId, name) => ledger.write((db) => viewerForLink(db, tokenId, name)),
507
515
  openView(input) {
508
516
  return ledger.write((db) => openView(db, input));
509
517
  },
@@ -54,7 +54,9 @@ function viewerOf(row: ViewerRow): Viewer {
54
54
  id: row.id,
55
55
  kind: row.kind,
56
56
  ...(row.name !== null ? { name: row.name } : {}),
57
- ...(row.kind === "token" || row.kind === "host" ? { ref: row.external_ref } : {}),
57
+ ...(row.kind === "token" || row.kind === "host" || row.kind === "tailnet"
58
+ ? { ref: row.external_ref }
59
+ : {}),
58
60
  };
59
61
  }
60
62
 
@@ -91,7 +93,24 @@ export function viewerForHost(db: LedgerDb, spec: ViewerSpec): string {
91
93
  return viewerByRef(db, "host", spec);
92
94
  }
93
95
 
94
- function viewerByRef(db: LedgerDb, kind: "token" | "host", spec: ViewerSpec): string {
96
+ /**
97
+ * A tailnet person (D158 item 2): one viewer of kind `tailnet` per Tailscale login, named by the
98
+ * display name Tailscale Serve sends.
99
+ */
100
+ export function viewerForTailnet(db: LedgerDb, spec: ViewerSpec): string {
101
+ return viewerByRef(db, "tailnet", spec);
102
+ }
103
+
104
+ /**
105
+ * A link's own viewer (D158 item 2): whoever opens a link over a tunnel without being named (a
106
+ * public share, a tagged tailnet device) acts as one viewer per link, never as the home's local
107
+ * user, so a visitor's answers never mix into the owner's draft.
108
+ */
109
+ export function viewerForLink(db: LedgerDb, tokenId: string, name: string): string {
110
+ return viewerByRef(db, "token", { ref: `link:${tokenId}`, name });
111
+ }
112
+
113
+ function viewerByRef(db: LedgerDb, kind: "token" | "host" | "tailnet", spec: ViewerSpec): string {
95
114
  const found = db.get<ViewerRow>(
96
115
  "SELECT * FROM viewer WHERE kind = ? AND external_ref = ?",
97
116
  kind,
@@ -593,4 +593,65 @@ export const MIGRATIONS: readonly Migration[] = [
593
593
  `);
594
594
  },
595
595
  },
596
+ {
597
+ version: 11,
598
+ name: "shares and faces",
599
+ up(db) {
600
+ // D158. A face (an external address of the gateway: a tailnet or Funnel address, a quick
601
+ // tunnel's, a host's external base) is a listener of its own on loopback; a face that must
602
+ // keep its port across restarts (a tailnet address is `https://<device>:<port>`, a host's
603
+ // tunnel forwards to a port it was told) leases it like the shell and the artifacts do, under
604
+ // the purpose `face`. SQLite can't change a CHECK, so `port_lease` is rebuilt with its rows.
605
+ // `share` records each share (DATA_MODEL §3) with its plan, the addresses it set up, so a
606
+ // restart sets tailnet and Funnel shares up again; its row only ever ends (a trigger).
607
+ // `external_base` keeps the faces a host's addressing port gave, so their links work after
608
+ // a restart before the host answers again.
609
+ db.exec(`
610
+ CREATE TABLE port_lease_new (
611
+ port INTEGER PRIMARY KEY CHECK (port BETWEEN 1 AND 65535),
612
+ purpose TEXT NOT NULL CHECK (purpose IN ('shell', 'artifact', 'demo', 'face')),
613
+ owner_ref TEXT NOT NULL,
614
+ leased_at TEXT NOT NULL,
615
+ UNIQUE (purpose, owner_ref)
616
+ );
617
+ INSERT INTO port_lease_new (port, purpose, owner_ref, leased_at)
618
+ SELECT port, purpose, owner_ref, leased_at FROM port_lease;
619
+ DROP TABLE port_lease;
620
+ ALTER TABLE port_lease_new RENAME TO port_lease;
621
+ CREATE TABLE share (
622
+ id TEXT PRIMARY KEY,
623
+ artifact_id TEXT NOT NULL REFERENCES artifact(id),
624
+ via TEXT NOT NULL CHECK (via IN ('tailnet', 'funnel', 'cloudflare')),
625
+ hostname TEXT NOT NULL,
626
+ token_id TEXT NOT NULL REFERENCES token(id),
627
+ mode TEXT NOT NULL CHECK (mode IN ('cookie', 'worker')),
628
+ plan_json TEXT NOT NULL,
629
+ started_at TEXT NOT NULL,
630
+ expires_at TEXT,
631
+ stopped_at TEXT,
632
+ stop_reason TEXT,
633
+ CHECK ((stopped_at IS NULL) = (stop_reason IS NULL))
634
+ );
635
+ CREATE INDEX share_artifact ON share (artifact_id);
636
+ CREATE INDEX share_active ON share (stopped_at) WHERE stopped_at IS NULL;
637
+ CREATE TRIGGER share_ends_once BEFORE UPDATE ON share
638
+ WHEN OLD.stopped_at IS NOT NULL OR NEW.id IS NOT OLD.id
639
+ OR NEW.artifact_id IS NOT OLD.artifact_id OR NEW.via IS NOT OLD.via
640
+ OR NEW.token_id IS NOT OLD.token_id OR NEW.started_at IS NOT OLD.started_at
641
+ OR NEW.expires_at IS NOT OLD.expires_at
642
+ BEGIN
643
+ SELECT RAISE(ABORT, 'a share only ever ends, once');
644
+ END;
645
+ CREATE TABLE external_base (
646
+ key TEXT PRIMARY KEY,
647
+ listener TEXT NOT NULL CHECK (listener IN ('shell', 'artifact')),
648
+ artifact_id TEXT NOT NULL REFERENCES artifact(id),
649
+ origin TEXT NOT NULL,
650
+ mode TEXT CHECK (mode IN ('cookie', 'worker')),
651
+ client TEXT NOT NULL,
652
+ updated_at TEXT NOT NULL
653
+ );
654
+ `);
655
+ },
656
+ },
596
657
  ];
package/src/live/index.ts CHANGED
@@ -275,7 +275,13 @@ export function createLive(options: LiveOptions): Live {
275
275
  try {
276
276
  const handle = await pool.acquire(version);
277
277
  described.set(versionId, handle.started.live);
278
- if (!handle.started.live.some((source) => source.key === key)) return;
278
+ const source = handle.started.live.find((info) => info.key === key);
279
+ if (!source) return;
280
+ // A page that read it before its worker said may be waiting for a first load that won't
281
+ // come: a source that only streams. (A worker that doesn't say counts as loading, as
282
+ // `stateOf` reads it.)
283
+ if (source.load === false)
284
+ bus.publishLive(artifactId, { kind: "live", live: { key, awaiting: false } });
279
285
  // Known before it starts: its first value can arrive before the start's answer.
280
286
  running.set(id, { artifactId, key, versionId, handle });
281
287
  try {
@@ -379,6 +385,12 @@ export function createLive(options: LiveOptions): Live {
379
385
  key,
380
386
  );
381
387
  const failure = failures.get(keyOf(artifactId, key));
388
+ // Its first load is on its way when the latest version defines it and, once its worker said,
389
+ // has a `load` (a stream's first value may never come). A key only pushes write isn't.
390
+ const latest = options.latest(artifactId);
391
+ const producing =
392
+ latest?.sources.some((source) => source.key === key) === true &&
393
+ (described.get(latest.versionId)?.find((source) => source.key === key)?.load ?? true);
382
394
  const ring =
383
395
  window === undefined
384
396
  ? undefined
@@ -406,6 +418,7 @@ export function createLive(options: LiveOptions): Live {
406
418
  : {}),
407
419
  ...(ring ? { ring } : {}),
408
420
  ...(failure ? { error: failure } : {}),
421
+ ...(!row && !failure && producing ? { awaiting: true } : {}),
409
422
  };
410
423
  };
411
424
 
@@ -51,3 +51,4 @@ export {
51
51
  } from "./helper.ts";
52
52
  export { isSameProcess, listProcesses, readProcess } from "./identity.ts";
53
53
  export { adoptable, launch, reapRecorded } from "./launch.ts";
54
+ export { installHint, type ToolCommand, toolCommand } from "./tools.ts";