@mostra/protocol 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.
- package/dist/actions.d.ts +12 -0
- package/dist/actions.d.ts.map +1 -1
- package/dist/actions.js.map +1 -1
- package/dist/bridge.d.ts +25 -0
- package/dist/bridge.d.ts.map +1 -1
- package/dist/bridge.js +32 -2
- package/dist/bridge.js.map +1 -1
- package/dist/browser.d.ts +76 -0
- package/dist/browser.d.ts.map +1 -1
- package/dist/browser.js +45 -2
- package/dist/browser.js.map +1 -1
- package/dist/diagnostics/codes/hygiene.d.ts +1 -1
- package/dist/diagnostics/codes/hygiene.d.ts.map +1 -1
- package/dist/diagnostics/codes/hygiene.js +12 -1
- package/dist/diagnostics/codes/hygiene.js.map +1 -1
- package/dist/diagnostics/codes/index.d.ts +3 -2
- package/dist/diagnostics/codes/index.d.ts.map +1 -1
- package/dist/diagnostics/codes/index.js +3 -1
- package/dist/diagnostics/codes/index.js.map +1 -1
- package/dist/diagnostics/codes/share.d.ts +8 -0
- package/dist/diagnostics/codes/share.d.ts.map +1 -0
- package/dist/diagnostics/codes/share.js +88 -0
- package/dist/diagnostics/codes/share.js.map +1 -0
- package/dist/hygiene.d.ts.map +1 -1
- package/dist/hygiene.js +2 -1
- package/dist/hygiene.js.map +1 -1
- package/dist/ids.d.ts +5 -1
- package/dist/ids.d.ts.map +1 -1
- package/dist/ids.js +3 -1
- package/dist/ids.js.map +1 -1
- package/dist/index.d.ts +10 -5
- package/dist/index.js +9 -4
- package/dist/methods/index.d.ts.map +1 -1
- package/dist/methods/index.js +9 -1
- package/dist/methods/index.js.map +1 -1
- package/dist/methods/instance/status.d.ts +24 -0
- package/dist/methods/instance/status.d.ts.map +1 -1
- package/dist/methods/instance/status.js +11 -2
- package/dist/methods/instance/status.js.map +1 -1
- package/dist/methods/port/addressing-external-base.d.ts +52 -0
- package/dist/methods/port/addressing-external-base.d.ts.map +1 -0
- package/dist/methods/port/addressing-external-base.js +61 -0
- package/dist/methods/port/addressing-external-base.js.map +1 -0
- package/dist/methods/share/list.d.ts +23 -0
- package/dist/methods/share/list.d.ts.map +1 -0
- package/dist/methods/share/list.js +29 -0
- package/dist/methods/share/list.js.map +1 -0
- package/dist/methods/share/start.d.ts +96 -0
- package/dist/methods/share/start.d.ts.map +1 -0
- package/dist/methods/share/start.js +73 -0
- package/dist/methods/share/start.js.map +1 -0
- package/dist/methods/share/stop.d.ts +29 -0
- package/dist/methods/share/stop.d.ts.map +1 -0
- package/dist/methods/share/stop.js +32 -0
- package/dist/methods/share/stop.js.map +1 -0
- package/package.json +2 -2
- package/schemas/protocol.draft-07.json +535 -0
- package/schemas/protocol.schema.json +507 -0
- package/src/actions.ts +12 -0
- package/src/bridge.ts +49 -0
- package/src/browser.ts +118 -0
- package/src/diagnostics/codes/hygiene.ts +12 -0
- package/src/diagnostics/codes/index.ts +6 -2
- package/src/diagnostics/codes/share.ts +100 -0
- package/src/hygiene.ts +1 -0
- package/src/ids.ts +9 -1
- package/src/index.ts +39 -0
- package/src/methods/index.ts +8 -0
- package/src/methods/instance/status.ts +38 -0
- package/src/methods/port/addressing-external-base.ts +113 -0
- package/src/methods/share/list.ts +42 -0
- package/src/methods/share/start.ts +150 -0
- package/src/methods/share/stop.ts +50 -0
package/src/browser.ts
CHANGED
|
@@ -231,6 +231,12 @@ export interface FrameTicket extends ViewContext {
|
|
|
231
231
|
* shell says so, and it is never a published version.
|
|
232
232
|
*/
|
|
233
233
|
readonly devPreview?: true;
|
|
234
|
+
/**
|
|
235
|
+
* `worker` when the shell and the artifact are two sites (a Cloudflare quick tunnel, a host's
|
|
236
|
+
* addresses on two hosts): the frame enters through the bootstrap page and a service worker
|
|
237
|
+
* (D70, D158 item 5). Absent: cookie mode.
|
|
238
|
+
*/
|
|
239
|
+
readonly mode?: "worker";
|
|
234
240
|
}
|
|
235
241
|
|
|
236
242
|
/** The Zod schema of the `FrameTicket` type. */
|
|
@@ -250,12 +256,124 @@ export const FrameTicket: z.ZodType<FrameTicket> = z
|
|
|
250
256
|
pinned: z.boolean(),
|
|
251
257
|
serverParked: z.literal(true).exactOptional(),
|
|
252
258
|
devPreview: z.literal(true).exactOptional(),
|
|
259
|
+
mode: z.literal("worker").exactOptional(),
|
|
253
260
|
})
|
|
254
261
|
.register(wireRegistry, {
|
|
255
262
|
id: "FrameTicket",
|
|
256
263
|
description: "A frame ticket: the view it opens, where to load it, and the view's controls.",
|
|
257
264
|
});
|
|
258
265
|
|
|
266
|
+
// ── Frame sessions in worker mode (WP-13, D70, D158 item 5) ───────────────────────────────
|
|
267
|
+
|
|
268
|
+
/**
|
|
269
|
+
* The header Mostra's service worker adds to every same-origin request of a worker-mode frame:
|
|
270
|
+
* its frame session's secret, which no cookie can carry across sites.
|
|
271
|
+
*/
|
|
272
|
+
export const FRAME_SESSION_HEADER = "x-mostra-frame";
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* `POST /_mostra/enter` on the artifact's origin: the bootstrap page exchanges the shell's
|
|
276
|
+
* single-use frame ticket, from `/_mostra/enter#t=…`, for a worker-mode frame session.
|
|
277
|
+
*/
|
|
278
|
+
export interface EnterRequest {
|
|
279
|
+
/** The frame ticket. */
|
|
280
|
+
readonly ticket: string;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/** The Zod schema of the `EnterRequest` type. */
|
|
284
|
+
export const EnterRequest: z.ZodType<EnterRequest> = z
|
|
285
|
+
.object({ ticket: z.string().min(1).max(64) })
|
|
286
|
+
.register(wireRegistry, { id: "EnterRequest", description: "A frame ticket to exchange." });
|
|
287
|
+
|
|
288
|
+
/** The answer to `EnterRequest`. */
|
|
289
|
+
export interface EnterResult {
|
|
290
|
+
/** The frame session's secret, which the service worker sends as `X-Mostra-Frame`. */
|
|
291
|
+
readonly session: string;
|
|
292
|
+
/** The shell's origin: the only page the bootstrap reports to. */
|
|
293
|
+
readonly shellOrigin: string;
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/** The Zod schema of the `EnterResult` type. */
|
|
297
|
+
export const EnterResult: z.ZodType<EnterResult> = z
|
|
298
|
+
.object({ session: z.string().min(1), shellOrigin: z.string().min(1) })
|
|
299
|
+
.register(wireRegistry, {
|
|
300
|
+
id: "EnterResult",
|
|
301
|
+
description: "A worker-mode frame session's secret and the shell's origin.",
|
|
302
|
+
});
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* `POST /_mostra/v/{rev}/ticket`: a single-use ticket that opens one event stream, long poll or
|
|
306
|
+
* WebSocket of this session without it (`?ticket=`), so the request can bypass the service
|
|
307
|
+
* worker (VERIFIED_FACTS: Firefox stalls on endless responses a worker passes on).
|
|
308
|
+
*/
|
|
309
|
+
export interface StreamTicketRequest {
|
|
310
|
+
/** What it opens: `stream` (events and polls, the default) or `socket` (a WebSocket). */
|
|
311
|
+
readonly purpose?: "stream" | "socket";
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
/** The Zod schema of the `StreamTicketRequest` type. */
|
|
315
|
+
export const StreamTicketRequest: z.ZodType<StreamTicketRequest> = z
|
|
316
|
+
.object({ purpose: z.enum(["stream", "socket"]).exactOptional() })
|
|
317
|
+
.register(wireRegistry, { id: "StreamTicketRequest" });
|
|
318
|
+
|
|
319
|
+
/** The answer to a `StreamTicketRequest`. */
|
|
320
|
+
export interface StreamTicket {
|
|
321
|
+
/** The ticket: 130 bits, single-use. */
|
|
322
|
+
readonly ticket: string;
|
|
323
|
+
/** When it stops working, 60 s after it was minted. */
|
|
324
|
+
readonly expiresAt: string;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
/** The Zod schema of the `StreamTicket` type. */
|
|
328
|
+
export const StreamTicket: z.ZodType<StreamTicket> = z
|
|
329
|
+
.object({ ticket: z.string().min(1), expiresAt: z.iso.datetime() })
|
|
330
|
+
.register(wireRegistry, {
|
|
331
|
+
id: "StreamTicket",
|
|
332
|
+
description: "A single-use ticket for one stream, poll or WebSocket.",
|
|
333
|
+
});
|
|
334
|
+
|
|
335
|
+
/**
|
|
336
|
+
* `GET /_mostra/session` on the artifact's origin: the frame session's facts for same-origin code.
|
|
337
|
+
*/
|
|
338
|
+
export interface FrameSessionFacts {
|
|
339
|
+
/** The CSRF token every mutation sends as `X-Mostra-CSRF`. */
|
|
340
|
+
readonly csrf: string;
|
|
341
|
+
/** The artifact the frame shows. */
|
|
342
|
+
readonly artifactId: string;
|
|
343
|
+
/** The shell's exact origin: the bridge's only peer. */
|
|
344
|
+
readonly shellOrigin: string;
|
|
345
|
+
/** The link's scopes. */
|
|
346
|
+
readonly scopes: readonly string[];
|
|
347
|
+
/** The viewer the page acts as (WP-07). */
|
|
348
|
+
readonly viewer?: Viewer;
|
|
349
|
+
/** The version the frame session entered. */
|
|
350
|
+
readonly version?: VersionRef;
|
|
351
|
+
/** How the frame authenticates (D70): absent means `cookie`. */
|
|
352
|
+
readonly mode?: "cookie" | "worker";
|
|
353
|
+
/**
|
|
354
|
+
* `false` where event streams don't pass (a Cloudflare quick tunnel holds responses back until
|
|
355
|
+
* they end): the page long-polls from the start (D47). Absent means streams pass.
|
|
356
|
+
*/
|
|
357
|
+
readonly streams?: boolean;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
/** The Zod schema of the `FrameSessionFacts` type. */
|
|
361
|
+
export const FrameSessionFacts: z.ZodType<FrameSessionFacts> = z
|
|
362
|
+
.object({
|
|
363
|
+
csrf: z.string().min(1),
|
|
364
|
+
artifactId: ArtifactId.schema,
|
|
365
|
+
shellOrigin: z.string().min(1),
|
|
366
|
+
scopes: z.array(z.string()).readonly(),
|
|
367
|
+
viewer: Viewer.exactOptional(),
|
|
368
|
+
version: VersionRef.exactOptional(),
|
|
369
|
+
mode: z.enum(["cookie", "worker"]).exactOptional(),
|
|
370
|
+
streams: z.boolean().exactOptional(),
|
|
371
|
+
})
|
|
372
|
+
.register(wireRegistry, {
|
|
373
|
+
id: "FrameSessionFacts",
|
|
374
|
+
description: "A frame session's CSRF token, shell origin, scopes, viewer, version and mode.",
|
|
375
|
+
});
|
|
376
|
+
|
|
259
377
|
// ── The shell's own routes (WP-07, on the shell origin) ──────────────────────────────────
|
|
260
378
|
|
|
261
379
|
/**
|
|
@@ -20,6 +20,7 @@ export const hygieneDiagnosticCodes = [
|
|
|
20
20
|
"MOSTRA_HYGIENE_NOT_SERVED",
|
|
21
21
|
"MOSTRA_HYGIENE_SESSION_CONFLICT",
|
|
22
22
|
"MOSTRA_HYGIENE_HEADERS_TOO_LARGE",
|
|
23
|
+
"MOSTRA_HYGIENE_FRAME_SESSION",
|
|
23
24
|
// gen:codes
|
|
24
25
|
] as const;
|
|
25
26
|
|
|
@@ -171,5 +172,16 @@ export const hygieneDiagnostics: AreaCatalog<HygieneDiagnosticCode> = {
|
|
|
171
172
|
fix: "Open the artifact's link again. If it keeps happening, find the page that sets the cookies: it runs on this host.",
|
|
172
173
|
},
|
|
173
174
|
},
|
|
175
|
+
MOSTRA_HYGIENE_FRAME_SESSION: {
|
|
176
|
+
severity: "error",
|
|
177
|
+
phase: "hygiene",
|
|
178
|
+
title: "Frame session couldn't start",
|
|
179
|
+
hint: "Open the artifact's tailnet or Funnel link, or this link in a normal window of another browser.",
|
|
180
|
+
docs: {
|
|
181
|
+
explanation:
|
|
182
|
+
"Where the shell and the artifact are two sites (a Cloudflare quick tunnel, or a host's addresses on two hosts), the artifact's frame can't use a cookie: it enters through a bootstrap page that installs Mostra's service worker at `/`, which signs every request of the frame (worker mode, D70). Mostra reports this code when that can't happen: the browser offers the frame no service worker (a private window, a setting that blocks third-party storage), refuses to install it, or the gateway refused the frame's entry. The client runtime reports it too when the artifact's own code registers another service worker at `/`, which would replace Mostra's and end the frame's session.",
|
|
183
|
+
fix: "Open the artifact through a tailnet or Funnel share, where the frame uses a cookie, or in a browser window that allows service workers in frames. An artifact that needs its own service worker registers it at a narrower scope than `/`.",
|
|
184
|
+
},
|
|
185
|
+
},
|
|
174
186
|
// gen:entries
|
|
175
187
|
};
|
|
@@ -8,7 +8,6 @@ import { type A11yDiagnosticCode, a11yDiagnostics } from "./a11y.ts";
|
|
|
8
8
|
import { type ActionDiagnosticCode, actionDiagnostics } from "./action.ts";
|
|
9
9
|
import { type ArtifactDiagnosticCode, artifactDiagnostics } from "./artifact.ts";
|
|
10
10
|
import { type BuildDiagnosticCode, buildDiagnostics } from "./build.ts";
|
|
11
|
-
// gen:area-imports
|
|
12
11
|
import { type CliDiagnosticCode, cliDiagnostics } from "./cli.ts";
|
|
13
12
|
import { type ConsoleDiagnosticCode, consoleDiagnostics } from "./console.ts";
|
|
14
13
|
import { type DepDiagnosticCode, depDiagnostics } from "./dep.ts";
|
|
@@ -25,6 +24,8 @@ import { type PublishDiagnosticCode, publishDiagnostics } from "./publish.ts";
|
|
|
25
24
|
import { type RegressionDiagnosticCode, regressionDiagnostics } from "./regression.ts";
|
|
26
25
|
import { type RuntimeDiagnosticCode, runtimeDiagnostics } from "./runtime.ts";
|
|
27
26
|
import { type SecretDiagnosticCode, secretDiagnostics } from "./secret.ts";
|
|
27
|
+
// gen:area-imports
|
|
28
|
+
import { type ShareDiagnosticCode, shareDiagnostics } from "./share.ts";
|
|
28
29
|
import { type SmokeDiagnosticCode, smokeDiagnostics } from "./smoke.ts";
|
|
29
30
|
import { type SubmitDiagnosticCode, submitDiagnostics } from "./submit.ts";
|
|
30
31
|
import { type TargetDiagnosticCode, targetDiagnostics } from "./target.ts";
|
|
@@ -35,7 +36,6 @@ export { type A11yDiagnosticCode, a11yDiagnosticCodes } from "./a11y.ts";
|
|
|
35
36
|
export { type ActionDiagnosticCode, actionDiagnosticCodes } from "./action.ts";
|
|
36
37
|
export { type ArtifactDiagnosticCode, artifactDiagnosticCodes } from "./artifact.ts";
|
|
37
38
|
export { type BuildDiagnosticCode, buildDiagnosticCodes } from "./build.ts";
|
|
38
|
-
// gen:area-exports
|
|
39
39
|
export { type CliDiagnosticCode, cliDiagnosticCodes } from "./cli.ts";
|
|
40
40
|
export { type ConsoleDiagnosticCode, consoleDiagnosticCodes } from "./console.ts";
|
|
41
41
|
export { type DepDiagnosticCode, depDiagnosticCodes } from "./dep.ts";
|
|
@@ -52,6 +52,8 @@ export { type PublishDiagnosticCode, publishDiagnosticCodes } from "./publish.ts
|
|
|
52
52
|
export { type RegressionDiagnosticCode, regressionDiagnosticCodes } from "./regression.ts";
|
|
53
53
|
export { type RuntimeDiagnosticCode, runtimeDiagnosticCodes } from "./runtime.ts";
|
|
54
54
|
export { type SecretDiagnosticCode, secretDiagnosticCodes } from "./secret.ts";
|
|
55
|
+
// gen:area-exports
|
|
56
|
+
export { type ShareDiagnosticCode, shareDiagnosticCodes } from "./share.ts";
|
|
55
57
|
export { type SmokeDiagnosticCode, smokeDiagnosticCodes } from "./smoke.ts";
|
|
56
58
|
export { type SubmitDiagnosticCode, submitDiagnosticCodes } from "./submit.ts";
|
|
57
59
|
export { type TargetDiagnosticCode, targetDiagnosticCodes } from "./target.ts";
|
|
@@ -61,6 +63,7 @@ export { type VerifyDiagnosticCode, verifyDiagnosticCodes } from "./verify.ts";
|
|
|
61
63
|
/** Every code in the catalog. Codes are semver surface and are never removed (AX-03). */
|
|
62
64
|
export type KnownDiagnosticCode =
|
|
63
65
|
// gen:area-codes
|
|
66
|
+
| ShareDiagnosticCode
|
|
64
67
|
| CliDiagnosticCode
|
|
65
68
|
| RegressionDiagnosticCode
|
|
66
69
|
| SmokeDiagnosticCode
|
|
@@ -90,6 +93,7 @@ export type KnownDiagnosticCode =
|
|
|
90
93
|
/** Every cataloged code with its severity, phase, title, default hint and docs text. */
|
|
91
94
|
export const diagnosticCatalog: Readonly<Record<KnownDiagnosticCode, DiagnosticSpec>> = {
|
|
92
95
|
// gen:area-spreads
|
|
96
|
+
...shareDiagnostics,
|
|
93
97
|
...cliDiagnostics,
|
|
94
98
|
...regressionDiagnostics,
|
|
95
99
|
...smokeDiagnostics,
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Diagnostic codes of the SHARE area.
|
|
3
|
+
*/
|
|
4
|
+
import type { AreaCatalog } from "../spec.ts";
|
|
5
|
+
|
|
6
|
+
/** The codes of the SHARE area, in the order they were added. */
|
|
7
|
+
export const shareDiagnosticCodes = [
|
|
8
|
+
"MOSTRA_SHARE_TOOL_MISSING",
|
|
9
|
+
"MOSTRA_SHARE_TOOL_NOT_READY",
|
|
10
|
+
"MOSTRA_SHARE_NOT_ENABLED",
|
|
11
|
+
"MOSTRA_SHARE_PORTS_EXHAUSTED",
|
|
12
|
+
"MOSTRA_SHARE_TUNNEL_FAILED",
|
|
13
|
+
"MOSTRA_SHARE_NOT_FOUND",
|
|
14
|
+
"MOSTRA_SHARE_TTL_INVALID",
|
|
15
|
+
// gen:codes
|
|
16
|
+
] as const;
|
|
17
|
+
|
|
18
|
+
/** The codes of the SHARE area. */
|
|
19
|
+
export type ShareDiagnosticCode = (typeof shareDiagnosticCodes)[number];
|
|
20
|
+
|
|
21
|
+
/** The SHARE area's catalog entries. */
|
|
22
|
+
export const shareDiagnostics: AreaCatalog<ShareDiagnosticCode> = {
|
|
23
|
+
MOSTRA_SHARE_TOOL_MISSING: {
|
|
24
|
+
severity: "error",
|
|
25
|
+
phase: "host",
|
|
26
|
+
title: "Sharing tool not installed",
|
|
27
|
+
hint: "Install the tool the message names, then run the share again.",
|
|
28
|
+
docs: {
|
|
29
|
+
explanation:
|
|
30
|
+
"A share drives a tunnel tool installed on this machine: `tailscale` for tailnet and Funnel shares, `cloudflared` for Cloudflare quick tunnels. Mostra never bundles or downloads them; it found none where it looks (`PATH`, the tool's usual install locations, or `MOSTRA_TAILSCALE` and `MOSTRA_CLOUDFLARED`). The message says how to install it on this system.",
|
|
31
|
+
fix: "Install the tool (Tailscale from tailscale.com/download, `cloudflared` from Cloudflare's downloads or a package manager), or point `MOSTRA_TAILSCALE` or `MOSTRA_CLOUDFLARED` at it, then share again.",
|
|
32
|
+
},
|
|
33
|
+
},
|
|
34
|
+
MOSTRA_SHARE_TOOL_NOT_READY: {
|
|
35
|
+
severity: "error",
|
|
36
|
+
phase: "host",
|
|
37
|
+
title: "Sharing tool not ready",
|
|
38
|
+
hint: "Do what the message says to the tool, then run the share again.",
|
|
39
|
+
docs: {
|
|
40
|
+
explanation:
|
|
41
|
+
"The tunnel tool is installed but can't serve yet: Tailscale isn't running or isn't signed in to a tailnet, or `cloudflared` exited before it opened a tunnel. The message quotes what the tool reported.",
|
|
42
|
+
fix: "Start Tailscale and sign in (`tailscale up`), or check that `cloudflared` runs and this machine reaches Cloudflare, then share again.",
|
|
43
|
+
},
|
|
44
|
+
},
|
|
45
|
+
MOSTRA_SHARE_NOT_ENABLED: {
|
|
46
|
+
severity: "error",
|
|
47
|
+
phase: "host",
|
|
48
|
+
title: "Sharing not enabled on the tailnet",
|
|
49
|
+
hint: "Open the address in the message as the tailnet's admin to turn the feature on, then run the share again.",
|
|
50
|
+
docs: {
|
|
51
|
+
explanation:
|
|
52
|
+
"Tailscale Serve needs HTTPS certificates turned on for the tailnet, and Funnel needs the Funnel permission for this device. Tailscale refused the share and gave an address where an admin of the tailnet turns the feature on; the message carries it.",
|
|
53
|
+
fix: "Open the address as an admin of the tailnet and approve, then share again. Without admin rights, ask the tailnet's admin, or share publicly through a Cloudflare quick tunnel (`mostra share <artifact> --public`).",
|
|
54
|
+
},
|
|
55
|
+
},
|
|
56
|
+
MOSTRA_SHARE_PORTS_EXHAUSTED: {
|
|
57
|
+
severity: "error",
|
|
58
|
+
phase: "host",
|
|
59
|
+
title: "No tunnel port free",
|
|
60
|
+
hint: "Stop a share you no longer need (`mostra share list`, then `mostra share stop <share>`), or share through a Cloudflare quick tunnel.",
|
|
61
|
+
docs: {
|
|
62
|
+
explanation:
|
|
63
|
+
"Tailscale Funnel listens only on ports 443, 8443 and 10000 of a device: Mostra gives 443 to the shell and the other two to one artifact each, so at most two artifacts are shared through Funnel at once. A port is also unavailable when this device's own Serve or Funnel configuration already uses it.",
|
|
64
|
+
fix: "Stop one of the Funnel shares, free the port in Tailscale's own configuration, or share this artifact through a Cloudflare quick tunnel.",
|
|
65
|
+
},
|
|
66
|
+
},
|
|
67
|
+
MOSTRA_SHARE_TUNNEL_FAILED: {
|
|
68
|
+
severity: "error",
|
|
69
|
+
phase: "host",
|
|
70
|
+
title: "Tunnel failed",
|
|
71
|
+
hint: "Run the share again; if it fails the same way, check the tool's message and this machine's network.",
|
|
72
|
+
docs: {
|
|
73
|
+
explanation:
|
|
74
|
+
"The tunnel tool started but didn't serve within its time, or stopped: the message quotes what it reported. A share whose tunnel ends and can't be set up again stops, and `mostra share list` shows why; a Cloudflare quick tunnel can't keep its address, so its share ends with it.",
|
|
75
|
+
fix: "Share again for a new link. A tailnet or Funnel share keeps its address across restarts of its tunnel; a Cloudflare quick tunnel gets a new one each time.",
|
|
76
|
+
},
|
|
77
|
+
},
|
|
78
|
+
MOSTRA_SHARE_NOT_FOUND: {
|
|
79
|
+
severity: "error",
|
|
80
|
+
phase: "host",
|
|
81
|
+
title: "Unknown share",
|
|
82
|
+
hint: "List the home's shares with `mostra share list` and name one of them.",
|
|
83
|
+
docs: {
|
|
84
|
+
explanation: "No share of this home has the ID given, or the artifact has no share.",
|
|
85
|
+
fix: "Use a share ID from `mostra share list`.",
|
|
86
|
+
},
|
|
87
|
+
},
|
|
88
|
+
MOSTRA_SHARE_TTL_INVALID: {
|
|
89
|
+
severity: "error",
|
|
90
|
+
phase: "host",
|
|
91
|
+
title: "Share lifetime refused",
|
|
92
|
+
hint: "Give a public share a lifetime of at most 7 days, such as `--ttl 24h`.",
|
|
93
|
+
docs: {
|
|
94
|
+
explanation:
|
|
95
|
+
"A public share (Funnel or Cloudflare) admits anyone holding its link, so it lasts 1 hour unless `ttl` says otherwise, and at most 7 days. Tailnet shares have no limit.",
|
|
96
|
+
fix: "Use a `ttl` of 7 days or less, and share again when it ends, or share inside the tailnet.",
|
|
97
|
+
},
|
|
98
|
+
},
|
|
99
|
+
// gen:entries
|
|
100
|
+
};
|
package/src/hygiene.ts
CHANGED
|
@@ -76,6 +76,7 @@ const STATUS: Readonly<Record<HygieneDiagnosticCode, number>> = {
|
|
|
76
76
|
MOSTRA_HYGIENE_NOT_SERVED: 404,
|
|
77
77
|
MOSTRA_HYGIENE_SESSION_CONFLICT: 409,
|
|
78
78
|
MOSTRA_HYGIENE_HEADERS_TOO_LARGE: 431,
|
|
79
|
+
MOSTRA_HYGIENE_FRAME_SESSION: 403,
|
|
79
80
|
};
|
|
80
81
|
|
|
81
82
|
/** Builds a refusal with the status the code's HTTP mapping gives (FAILURE_MODEL §8). */
|
package/src/ids.ts
CHANGED
|
@@ -28,7 +28,8 @@ export type IdPrefix =
|
|
|
28
28
|
| "thr"
|
|
29
29
|
| "cmt"
|
|
30
30
|
| "tok"
|
|
31
|
-
| "mut"
|
|
31
|
+
| "mut"
|
|
32
|
+
| "shr";
|
|
32
33
|
|
|
33
34
|
/**
|
|
34
35
|
* A branded ID string. The brand exists only at the type level, so an `Id<"art">` is a plain
|
|
@@ -242,6 +243,13 @@ export const MutationId: GeneratedIdKind<"mut"> = generated(
|
|
|
242
243
|
defineKind("mut", "mutation", "ulid", "MutationId"),
|
|
243
244
|
);
|
|
244
245
|
|
|
246
|
+
/** A share ID (`shr_` + ULID): one share of an artifact through a tunnel (D158). */
|
|
247
|
+
export type ShareId = Id<"shr">;
|
|
248
|
+
/** Share IDs. */
|
|
249
|
+
export const ShareId: GeneratedIdKind<"shr"> = generated(
|
|
250
|
+
defineKind("shr", "share", "ulid", "ShareId"),
|
|
251
|
+
);
|
|
252
|
+
|
|
245
253
|
/**
|
|
246
254
|
* An event cursor: the decimal string of a home-wide event position (INTERFACES §1). Decimal
|
|
247
255
|
* strings keep 64-bit positions exact in JavaScript.
|
package/src/index.ts
CHANGED
|
@@ -66,11 +66,14 @@ export {
|
|
|
66
66
|
type FieldRegistration,
|
|
67
67
|
type FieldsParams,
|
|
68
68
|
type FlushResult,
|
|
69
|
+
type FrameSessionFailedParams,
|
|
69
70
|
MCP_APPS_PROTOCOL_VERSION,
|
|
70
71
|
mostraControlsRequest,
|
|
71
72
|
mostraFieldFocus,
|
|
72
73
|
mostraFields,
|
|
73
74
|
mostraFlush,
|
|
75
|
+
mostraFrameSessionEntered,
|
|
76
|
+
mostraFrameSessionFailed,
|
|
74
77
|
mostraPage,
|
|
75
78
|
mostraReady,
|
|
76
79
|
mostraVersionAvailable,
|
|
@@ -92,8 +95,12 @@ export {
|
|
|
92
95
|
ChooseRequest,
|
|
93
96
|
type DeliveryTarget,
|
|
94
97
|
DocumentSnapshot,
|
|
98
|
+
EnterRequest,
|
|
99
|
+
EnterResult,
|
|
95
100
|
FieldsRequest,
|
|
96
101
|
FollowRequest,
|
|
102
|
+
FRAME_SESSION_HEADER,
|
|
103
|
+
FrameSessionFacts,
|
|
97
104
|
FrameTicket,
|
|
98
105
|
OrphanedField,
|
|
99
106
|
PollResult,
|
|
@@ -103,6 +110,8 @@ export {
|
|
|
103
110
|
SIGNAL_PAYLOAD_MAX_BYTES,
|
|
104
111
|
SignalRequest,
|
|
105
112
|
StreamSnapshot,
|
|
113
|
+
StreamTicket,
|
|
114
|
+
StreamTicketRequest,
|
|
106
115
|
SubmitRequest,
|
|
107
116
|
VersionRef,
|
|
108
117
|
ViewContext,
|
|
@@ -178,9 +187,11 @@ export {
|
|
|
178
187
|
regressionDiagnosticCodes,
|
|
179
188
|
runtimeDiagnosticCodes,
|
|
180
189
|
type SecretDiagnosticCode,
|
|
190
|
+
type ShareDiagnosticCode,
|
|
181
191
|
type SmokeDiagnosticCode,
|
|
182
192
|
type SubmitDiagnosticCode,
|
|
183
193
|
secretDiagnosticCodes,
|
|
194
|
+
shareDiagnosticCodes,
|
|
184
195
|
smokeDiagnosticCodes,
|
|
185
196
|
submitDiagnosticCodes,
|
|
186
197
|
type TargetDiagnosticCode,
|
|
@@ -233,6 +244,7 @@ export {
|
|
|
233
244
|
type IdPrefix,
|
|
234
245
|
MutationId,
|
|
235
246
|
RunId,
|
|
247
|
+
ShareId,
|
|
236
248
|
SubmissionId,
|
|
237
249
|
ThreadId,
|
|
238
250
|
TokenId,
|
|
@@ -370,6 +382,7 @@ export {
|
|
|
370
382
|
export {
|
|
371
383
|
ChildProcessStatus,
|
|
372
384
|
DeliveryCounts,
|
|
385
|
+
type FaceStatus,
|
|
373
386
|
GatewayStatus,
|
|
374
387
|
type InstanceStatusParams,
|
|
375
388
|
type InstanceStatusResult,
|
|
@@ -395,6 +408,13 @@ export {
|
|
|
395
408
|
type MostraShutdownResult,
|
|
396
409
|
mostraShutdownMethod,
|
|
397
410
|
} from "./methods/mostra/shutdown.ts";
|
|
411
|
+
export {
|
|
412
|
+
ExternalBase,
|
|
413
|
+
OriginString,
|
|
414
|
+
type PortAddressingExternalBaseParams,
|
|
415
|
+
type PortAddressingExternalBaseResult,
|
|
416
|
+
portAddressingExternalBaseMethod,
|
|
417
|
+
} from "./methods/port/addressing-external-base.ts";
|
|
398
418
|
export {
|
|
399
419
|
DraftMirror,
|
|
400
420
|
type DraftsMirrorResult,
|
|
@@ -448,6 +468,25 @@ export {
|
|
|
448
468
|
type SecretSetResult,
|
|
449
469
|
secretSetMethod,
|
|
450
470
|
} from "./methods/secret/set.ts";
|
|
471
|
+
export {
|
|
472
|
+
type ShareListParams,
|
|
473
|
+
type ShareListResult,
|
|
474
|
+
shareListMethod,
|
|
475
|
+
} from "./methods/share/list.ts";
|
|
476
|
+
export {
|
|
477
|
+
PUBLIC_SHARE_DEFAULT_TTL,
|
|
478
|
+
PUBLIC_SHARE_MAX_TTL_MS,
|
|
479
|
+
Share,
|
|
480
|
+
type ShareStartParams,
|
|
481
|
+
type ShareStartResult,
|
|
482
|
+
ShareVia,
|
|
483
|
+
shareStartMethod,
|
|
484
|
+
} from "./methods/share/start.ts";
|
|
485
|
+
export {
|
|
486
|
+
type ShareStopParams,
|
|
487
|
+
type ShareStopResult,
|
|
488
|
+
shareStopMethod,
|
|
489
|
+
} from "./methods/share/stop.ts";
|
|
451
490
|
export { type StateGetParams, type StateGetResult, stateGetMethod } from "./methods/state/get.ts";
|
|
452
491
|
export {
|
|
453
492
|
type StatePatchParams,
|
package/src/methods/index.ts
CHANGED
|
@@ -22,6 +22,7 @@ import { instanceStatusMethod } from "./instance/status.ts";
|
|
|
22
22
|
import { livePushMethod } from "./live/push.ts";
|
|
23
23
|
import { mostraInitializeMethod } from "./mostra/initialize.ts";
|
|
24
24
|
import { mostraShutdownMethod } from "./mostra/shutdown.ts";
|
|
25
|
+
import { portAddressingExternalBaseMethod } from "./port/addressing-external-base.ts";
|
|
25
26
|
import { portDraftsMirrorMethod } from "./port/drafts-mirror.ts";
|
|
26
27
|
import { portIdentityResolveMethod } from "./port/identity-resolve.ts";
|
|
27
28
|
import { portSecretsGetMethod } from "./port/secrets-get.ts";
|
|
@@ -32,6 +33,9 @@ import { resultsGetMethod } from "./results/get.ts";
|
|
|
32
33
|
import { secretDeleteMethod } from "./secret/delete.ts";
|
|
33
34
|
import { secretListMethod } from "./secret/list.ts";
|
|
34
35
|
import { secretSetMethod } from "./secret/set.ts";
|
|
36
|
+
import { shareListMethod } from "./share/list.ts";
|
|
37
|
+
import { shareStartMethod } from "./share/start.ts";
|
|
38
|
+
import { shareStopMethod } from "./share/stop.ts";
|
|
35
39
|
import { stateGetMethod } from "./state/get.ts";
|
|
36
40
|
import { statePatchMethod } from "./state/patch.ts";
|
|
37
41
|
import { viewDefaultMethod } from "./view/default.ts";
|
|
@@ -80,6 +84,10 @@ export const hostMethods: readonly AnyMethod[] = [
|
|
|
80
84
|
devStartMethod,
|
|
81
85
|
devStopMethod,
|
|
82
86
|
portIdentityResolveMethod,
|
|
87
|
+
shareStartMethod,
|
|
88
|
+
shareStopMethod,
|
|
89
|
+
shareListMethod,
|
|
90
|
+
portAddressingExternalBaseMethod,
|
|
83
91
|
// gen:methods
|
|
84
92
|
];
|
|
85
93
|
|
|
@@ -2,6 +2,7 @@ import * as z from "zod";
|
|
|
2
2
|
import { defineMethod, type MethodDefinition } from "../../method.ts";
|
|
3
3
|
import { wireRegistry } from "../../wire-registry.ts";
|
|
4
4
|
import { InstanceInfo } from "../mostra/initialize.ts";
|
|
5
|
+
import { Share } from "../share/start.ts";
|
|
5
6
|
|
|
6
7
|
/** The params of `instance/status` (INTERFACES §6): none. */
|
|
7
8
|
export type InstanceStatusParams = Record<string, never>;
|
|
@@ -26,6 +27,25 @@ export interface GatewayStatus {
|
|
|
26
27
|
readonly shell: string;
|
|
27
28
|
/** The artifact origins it is serving now, one per opened artifact. */
|
|
28
29
|
readonly artifacts: readonly { readonly artifactId: string; readonly origin: string }[];
|
|
30
|
+
/**
|
|
31
|
+
* The gateway's external addresses (D158 item 1): a share's tunnel addresses and a host's
|
|
32
|
+
* external bases, each a listener of its own on loopback (WP-13).
|
|
33
|
+
*/
|
|
34
|
+
readonly faces?: readonly FaceStatus[];
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** One external address of the gateway (D158 item 1). */
|
|
38
|
+
export interface FaceStatus {
|
|
39
|
+
/** The origin browsers use. */
|
|
40
|
+
readonly origin: string;
|
|
41
|
+
/** The loopback origin the tunnel or the host forwards it to. */
|
|
42
|
+
readonly local: string;
|
|
43
|
+
/** Which listener it fronts: the shell, or one artifact's frame. */
|
|
44
|
+
readonly listener: "shell" | "artifact";
|
|
45
|
+
/** The artifact, for an artifact's face. */
|
|
46
|
+
readonly artifactId?: string;
|
|
47
|
+
/** Who keeps it: a share's tunnel (`tailnet`, `funnel`, `cloudflare`) or a host (`host`). */
|
|
48
|
+
readonly by: "tailnet" | "funnel" | "cloudflare" | "host" | (string & {});
|
|
29
49
|
}
|
|
30
50
|
|
|
31
51
|
/**
|
|
@@ -51,6 +71,11 @@ export interface InstanceStatusResult {
|
|
|
51
71
|
readonly workers?: readonly WorkerStatus[];
|
|
52
72
|
/** When the daemon exits for lack of work, if it will (WP-08, RT-08); absent: it won't. */
|
|
53
73
|
readonly idleExitAt?: string;
|
|
74
|
+
/**
|
|
75
|
+
* The active shares (WP-13, D158), which keep a daemon from its idle exit. Their `url` is left
|
|
76
|
+
* out here, since status is printed where a link's secret mustn't appear: `share/list` gives it.
|
|
77
|
+
*/
|
|
78
|
+
readonly shares?: readonly Share[];
|
|
54
79
|
}
|
|
55
80
|
|
|
56
81
|
/** One artifact version's worker (RT-03, D62). */
|
|
@@ -127,6 +152,18 @@ export const GatewayStatus: z.ZodType<GatewayStatus> = z
|
|
|
127
152
|
bind: z.string(),
|
|
128
153
|
shell: z.string(),
|
|
129
154
|
artifacts: z.array(z.object({ artifactId: z.string(), origin: z.string() })).readonly(),
|
|
155
|
+
faces: z
|
|
156
|
+
.array(
|
|
157
|
+
z.object({
|
|
158
|
+
origin: z.string(),
|
|
159
|
+
local: z.string(),
|
|
160
|
+
listener: z.enum(["shell", "artifact"]),
|
|
161
|
+
artifactId: z.string().exactOptional(),
|
|
162
|
+
by: z.string(),
|
|
163
|
+
}),
|
|
164
|
+
)
|
|
165
|
+
.readonly()
|
|
166
|
+
.exactOptional(),
|
|
130
167
|
})
|
|
131
168
|
.register(wireRegistry, { id: "GatewayStatus", description: "Where the gateway listens." });
|
|
132
169
|
|
|
@@ -158,6 +195,7 @@ const result: z.ZodType<InstanceStatusResult> = z
|
|
|
158
195
|
deliveries: z.array(DeliveryCounts).readonly().exactOptional(),
|
|
159
196
|
workers: z.array(WorkerStatus).readonly().exactOptional(),
|
|
160
197
|
idleExitAt: z.string().exactOptional(),
|
|
198
|
+
shares: z.array(Share).readonly().exactOptional(),
|
|
161
199
|
})
|
|
162
200
|
.register(wireRegistry, { id: "InstanceStatusResult" });
|
|
163
201
|
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import * as z from "zod";
|
|
2
|
+
import { ArtifactId } from "../../ids.ts";
|
|
3
|
+
import { defineMethod, type MethodDefinition } from "../../method.ts";
|
|
4
|
+
import { wireRegistry } from "../../wire-registry.ts";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* An origin as browsers write it (`https://host.example`, `http://host:8080`): a scheme, a lower
|
|
8
|
+
* case host and a port only when it isn't the scheme's default, with no path, query or fragment.
|
|
9
|
+
*/
|
|
10
|
+
export const OriginString: z.ZodType<string> = z
|
|
11
|
+
.string()
|
|
12
|
+
.max(2048)
|
|
13
|
+
.regex(originPattern(), {
|
|
14
|
+
message: "An origin: http: or https:, a lower case host and a port only when not the default.",
|
|
15
|
+
})
|
|
16
|
+
.register(wireRegistry, {
|
|
17
|
+
id: "OriginString",
|
|
18
|
+
description: "A web origin: scheme, host and a port only when it isn't the default.",
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* An origin exactly as browsers serialize one, as one regular expression, so JSON Schema and the
|
|
23
|
+
* Rust crate check what Zod checks: a lower case DNS name or bracketed IPv6 literal, a port of 1
|
|
24
|
+
* to 65535, and never the scheme's default port written out.
|
|
25
|
+
*/
|
|
26
|
+
function originPattern(): RegExp {
|
|
27
|
+
const label = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
|
|
28
|
+
const host = `(?:${label}(?:\\.${label})*|\\[[0-9a-f:.]+\\])`;
|
|
29
|
+
const port =
|
|
30
|
+
"(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])";
|
|
31
|
+
return new RegExp(`^(?!http://[^/]*:80$)(?!https://[^/]*:443$)https?://${host}(?::${port})?$`);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** The params of `port/addressing.externalBase` (INTERFACES §7, D158 item 6). */
|
|
35
|
+
export interface PortAddressingExternalBaseParams {
|
|
36
|
+
/** The artifact whose links or frame this address serves. */
|
|
37
|
+
readonly artifactId: string;
|
|
38
|
+
/**
|
|
39
|
+
* Which of Mostra's listeners the address fronts: `shell` for the artifact's links (the shell
|
|
40
|
+
* that opens them), `artifact` for the artifact's own frame.
|
|
41
|
+
*/
|
|
42
|
+
readonly listener: "shell" | "artifact";
|
|
43
|
+
/**
|
|
44
|
+
* The loopback origin the host forwards this address to, such as `http://127.0.0.1:23456`: a
|
|
45
|
+
* port leased for this face, the same across restarts while the face exists.
|
|
46
|
+
*/
|
|
47
|
+
readonly local: string;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* The host's answer: the origin browsers use for this listener, and optionally how the artifact's
|
|
52
|
+
* frame authenticates there (`worker` by default whenever the shell's and the artifact's hosts
|
|
53
|
+
* differ, D70); `null` when the host offers no external address, so links stay on loopback.
|
|
54
|
+
*/
|
|
55
|
+
export type PortAddressingExternalBaseResult = ExternalBase | null;
|
|
56
|
+
|
|
57
|
+
const params: z.ZodType<PortAddressingExternalBaseParams> = z
|
|
58
|
+
.object({
|
|
59
|
+
artifactId: ArtifactId.schema,
|
|
60
|
+
listener: z.enum(["shell", "artifact"]),
|
|
61
|
+
local: z.string().min(1),
|
|
62
|
+
})
|
|
63
|
+
.register(wireRegistry, {
|
|
64
|
+
id: "PortAddressingExternalBaseParams",
|
|
65
|
+
description:
|
|
66
|
+
"Which listener of which artifact needs an external address, and where it listens.",
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
/** One external address a host gives a listener (D158 item 6). */
|
|
70
|
+
export interface ExternalBase {
|
|
71
|
+
/** The origin browsers use for the listener, such as `https://host.example.com`. */
|
|
72
|
+
readonly origin: string;
|
|
73
|
+
/**
|
|
74
|
+
* How the frame authenticates there (D70): `cookie` where the shell and the artifact are one
|
|
75
|
+
* site, `worker` where they are two. Absent: `cookie` for one host name, `worker` for two.
|
|
76
|
+
*/
|
|
77
|
+
readonly mode?: "cookie" | "worker";
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** The schema of the `ExternalBase` type. */
|
|
81
|
+
export const ExternalBase: z.ZodType<ExternalBase> = z
|
|
82
|
+
.object({ origin: OriginString, mode: z.enum(["cookie", "worker"]).exactOptional() })
|
|
83
|
+
.register(wireRegistry, {
|
|
84
|
+
id: "ExternalBase",
|
|
85
|
+
description: "The origin browsers use for a listener, and how its frame authenticates there.",
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
const result: z.ZodType<PortAddressingExternalBaseResult> = ExternalBase.nullable().register(
|
|
89
|
+
wireRegistry,
|
|
90
|
+
{
|
|
91
|
+
id: "PortAddressingExternalBaseResult",
|
|
92
|
+
description: "The external origin a host gives a listener, or null for loopback.",
|
|
93
|
+
},
|
|
94
|
+
);
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* `port/addressing.externalBase`: Mostra asks the host that registered the `addressing` port for
|
|
98
|
+
* the external address of one of its listeners (HO-10, D158 item 6), with 5 seconds to answer,
|
|
99
|
+
* when it mints a link for an artifact and when the shell at such an address opens the artifact's
|
|
100
|
+
* frame. The answer joins the Host allowlist and the links Mostra mints; `null`, or another
|
|
101
|
+
* origin, withdraws the address given before, whose links stop working. A host that fails or
|
|
102
|
+
* answers something the schema refuses leaves links on loopback.
|
|
103
|
+
*/
|
|
104
|
+
export const portAddressingExternalBaseMethod: MethodDefinition<
|
|
105
|
+
PortAddressingExternalBaseParams,
|
|
106
|
+
PortAddressingExternalBaseResult
|
|
107
|
+
> = defineMethod({
|
|
108
|
+
method: "port/addressing.externalBase",
|
|
109
|
+
direction: "instance-to-host",
|
|
110
|
+
mutating: false,
|
|
111
|
+
params,
|
|
112
|
+
result,
|
|
113
|
+
});
|