@mostra/protocol 0.6.1 → 0.7.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/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 +3 -3
- package/schemas/protocol.draft-07.json +535 -0
- package/schemas/protocol.schema.json +507 -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
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import * as z from "zod";
|
|
2
|
+
import { ArtifactRef } from "../../artifact.ts";
|
|
3
|
+
import { defineMethod, type MethodDefinition } from "../../method.ts";
|
|
4
|
+
import { wireRegistry } from "../../wire-registry.ts";
|
|
5
|
+
import { Share } from "./start.ts";
|
|
6
|
+
|
|
7
|
+
/** The params of `share/list` (D158). */
|
|
8
|
+
export interface ShareListParams {
|
|
9
|
+
/** Only this artifact's shares. */
|
|
10
|
+
readonly artifact?: ArtifactRef;
|
|
11
|
+
/** Shares that ended too, newest first; default: active shares only. */
|
|
12
|
+
readonly all?: boolean;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** The result of `share/list`. */
|
|
16
|
+
export interface ShareListResult {
|
|
17
|
+
/** Active shares first, each kind newest first. */
|
|
18
|
+
readonly shares: readonly Share[];
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
const params: z.ZodType<ShareListParams> = z
|
|
22
|
+
.object({ artifact: ArtifactRef.exactOptional(), all: z.boolean().exactOptional() })
|
|
23
|
+
.register(wireRegistry, { id: "ShareListParams" });
|
|
24
|
+
|
|
25
|
+
const result: z.ZodType<ShareListResult> = z
|
|
26
|
+
.object({ shares: z.array(Share).readonly() })
|
|
27
|
+
.register(wireRegistry, {
|
|
28
|
+
id: "ShareListResult",
|
|
29
|
+
description: "Shares with their links and state.",
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* `share/list`: the home's shares (D158), each with its tunnel, link, state and, once it ended,
|
|
34
|
+
* why: a tunnel that dropped and couldn't come back shows here.
|
|
35
|
+
*/
|
|
36
|
+
export const shareListMethod: MethodDefinition<ShareListParams, ShareListResult> = defineMethod({
|
|
37
|
+
method: "share/list",
|
|
38
|
+
direction: "client-to-instance",
|
|
39
|
+
mutating: false,
|
|
40
|
+
params,
|
|
41
|
+
result,
|
|
42
|
+
});
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import * as z from "zod";
|
|
2
|
+
import { ArtifactRef } from "../../artifact.ts";
|
|
3
|
+
import { CapabilityScope, Duration } from "../../capability.ts";
|
|
4
|
+
import { ArtifactId, ShareId, TokenId } from "../../ids.ts";
|
|
5
|
+
import { ViewerSpec } from "../../interaction.ts";
|
|
6
|
+
import { defineMethod, type MethodDefinition } from "../../method.ts";
|
|
7
|
+
import { wireRegistry } from "../../wire-registry.ts";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* How a share reaches its viewers (D158): `tailnet` through Tailscale Serve, to the people of the
|
|
11
|
+
* user's tailnet, who are known by name; `funnel` through Tailscale Funnel and `cloudflare`
|
|
12
|
+
* through a Cloudflare quick tunnel, both public, where the link is all that admits a viewer.
|
|
13
|
+
*/
|
|
14
|
+
export type ShareVia = "tailnet" | "funnel" | "cloudflare";
|
|
15
|
+
|
|
16
|
+
/** The Zod schema of the `ShareVia` type. */
|
|
17
|
+
export const ShareVia: z.ZodType<ShareVia> = z
|
|
18
|
+
.enum(["tailnet", "funnel", "cloudflare"])
|
|
19
|
+
.register(wireRegistry, {
|
|
20
|
+
id: "ShareVia",
|
|
21
|
+
description: "How a share reaches its viewers: tailnet, funnel or cloudflare.",
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
/** The longest a public share (Funnel or Cloudflare) may last: 7 days (D158). */
|
|
25
|
+
export const PUBLIC_SHARE_MAX_TTL_MS: number = 7 * 24 * 60 * 60 * 1000;
|
|
26
|
+
|
|
27
|
+
/** How long a public share lasts when its `ttl` isn't given: 1 hour (D63 item 5, D158). */
|
|
28
|
+
export const PUBLIC_SHARE_DEFAULT_TTL: Duration = "1h";
|
|
29
|
+
|
|
30
|
+
/** The params of `share/start` (INTERFACES §6, D158). */
|
|
31
|
+
export interface ShareStartParams {
|
|
32
|
+
/** The artifact to share; the link opens its latest version. */
|
|
33
|
+
readonly artifact: ArtifactRef;
|
|
34
|
+
/** The tunnel. A public one (`funnel`, `cloudflare`) is explicit: never a fallback. */
|
|
35
|
+
readonly via: ShareVia;
|
|
36
|
+
/**
|
|
37
|
+
* How long the share and its link last, such as `30m` or `24h`. Public shares: 1 hour by
|
|
38
|
+
* default, at most 7 days. Tailnet shares: until stopped, unless given.
|
|
39
|
+
*/
|
|
40
|
+
readonly ttl?: Duration;
|
|
41
|
+
/** What the share's link allows (D97). Default: every scope. */
|
|
42
|
+
readonly scopes?: readonly CapabilityScope[];
|
|
43
|
+
/**
|
|
44
|
+
* The person the share's link acts for (D104). Absent: whoever the tailnet or a host's identity
|
|
45
|
+
* port names, else the link's own viewer, never the home's local user (D158).
|
|
46
|
+
*/
|
|
47
|
+
readonly viewer?: ViewerSpec;
|
|
48
|
+
/** Makes retries idempotent: a repeated `requestId` returns the same share (H-03). */
|
|
49
|
+
readonly requestId?: string;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** A share, as `share/start` and `share/list` report it. */
|
|
53
|
+
export interface Share {
|
|
54
|
+
/** The share's ID, for `share/stop`. */
|
|
55
|
+
readonly shareId: string;
|
|
56
|
+
/** The artifact shared. */
|
|
57
|
+
readonly artifactId: string;
|
|
58
|
+
/** The tunnel. */
|
|
59
|
+
readonly via: ShareVia;
|
|
60
|
+
/**
|
|
61
|
+
* The share's capability URL, at the tunnel's address. Holding it is the authorization (D06);
|
|
62
|
+
* absent once the share ended, and in `share/list` when the home's key can no longer show it.
|
|
63
|
+
*/
|
|
64
|
+
readonly url?: string;
|
|
65
|
+
/** The tunnel's host name: the tailnet device's, or the quick tunnel's random one. */
|
|
66
|
+
readonly hostname: string;
|
|
67
|
+
/**
|
|
68
|
+
* The address the artifact's frame is served at over the tunnel, while the share is active:
|
|
69
|
+
* on a tailnet, the second port of this device that viewers must be allowed to reach.
|
|
70
|
+
*/
|
|
71
|
+
readonly artifactOrigin?: string;
|
|
72
|
+
/**
|
|
73
|
+
* How the artifact's frame authenticates over this tunnel (D70): `cookie` where the shell and
|
|
74
|
+
* the artifact are one site (Tailscale), `worker` where they are two (Cloudflare).
|
|
75
|
+
*/
|
|
76
|
+
readonly mode: "cookie" | "worker";
|
|
77
|
+
/** The share's link, for `view/rotate` and `view/revoke`. */
|
|
78
|
+
readonly tokenId: string;
|
|
79
|
+
/** When the share started (RFC 3339, UTC). */
|
|
80
|
+
readonly startedAt: string;
|
|
81
|
+
/** When the share and its link end, if they do. */
|
|
82
|
+
readonly expiresAt?: string;
|
|
83
|
+
/** `active` while it serves; `stopped` once it ended. */
|
|
84
|
+
readonly state: "active" | "stopped";
|
|
85
|
+
/** When it ended. */
|
|
86
|
+
readonly stoppedAt?: string;
|
|
87
|
+
/**
|
|
88
|
+
* Why it ended: `stopped` (`share/stop`), `expired` (its TTL), `tunnel` (its tunnel ended and
|
|
89
|
+
* couldn't be set up again), `restart` (a quick tunnel can't outlive its instance), or
|
|
90
|
+
* `revoked` (its link was revoked).
|
|
91
|
+
*/
|
|
92
|
+
readonly stopReason?: "stopped" | "expired" | "tunnel" | "restart" | "revoked" | (string & {});
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const shareShape = {
|
|
96
|
+
shareId: ShareId.schema,
|
|
97
|
+
artifactId: ArtifactId.schema,
|
|
98
|
+
via: ShareVia,
|
|
99
|
+
url: z.string().min(1).exactOptional(),
|
|
100
|
+
hostname: z.string().min(1),
|
|
101
|
+
artifactOrigin: z.string().min(1).exactOptional(),
|
|
102
|
+
mode: z.enum(["cookie", "worker"]),
|
|
103
|
+
tokenId: TokenId.schema,
|
|
104
|
+
startedAt: z.iso.datetime(),
|
|
105
|
+
expiresAt: z.iso.datetime().exactOptional(),
|
|
106
|
+
state: z.enum(["active", "stopped"]),
|
|
107
|
+
stoppedAt: z.iso.datetime().exactOptional(),
|
|
108
|
+
stopReason: z.string().min(1).exactOptional(),
|
|
109
|
+
};
|
|
110
|
+
|
|
111
|
+
/** The Zod schema of the `Share` type. */
|
|
112
|
+
export const Share: z.ZodType<Share> = z.object(shareShape).register(wireRegistry, {
|
|
113
|
+
id: "Share",
|
|
114
|
+
description: "A share: its tunnel, link, address, frame mode and lifetime.",
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
/** The result of `share/start`: the share, with its link. */
|
|
118
|
+
export type ShareStartResult = Share & { readonly url: string };
|
|
119
|
+
|
|
120
|
+
const params: z.ZodType<ShareStartParams> = z
|
|
121
|
+
.object({
|
|
122
|
+
artifact: ArtifactRef,
|
|
123
|
+
via: ShareVia,
|
|
124
|
+
ttl: Duration.exactOptional(),
|
|
125
|
+
scopes: z.array(CapabilityScope).min(1).readonly().exactOptional(),
|
|
126
|
+
viewer: ViewerSpec.exactOptional(),
|
|
127
|
+
requestId: z.string().min(1).exactOptional(),
|
|
128
|
+
})
|
|
129
|
+
.register(wireRegistry, { id: "ShareStartParams" });
|
|
130
|
+
|
|
131
|
+
const result: z.ZodType<ShareStartResult> = z
|
|
132
|
+
.object({ ...shareShape, url: z.string().min(1) })
|
|
133
|
+
.register(wireRegistry, {
|
|
134
|
+
id: "ShareStartResult",
|
|
135
|
+
description: "The share that started, with its capability URL.",
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* `share/start`: shares an artifact through a tunnel the instance drives (D158): Tailscale Serve
|
|
140
|
+
* for the tailnet, or Tailscale Funnel or a Cloudflare quick tunnel for anyone with the link. It
|
|
141
|
+
* answers once the tunnel serves, with a new link at the tunnel's address that works there only.
|
|
142
|
+
* A missing or unready tool is a `MOSTRA_SHARE_*` diagnostic saying what to do.
|
|
143
|
+
*/
|
|
144
|
+
export const shareStartMethod: MethodDefinition<ShareStartParams, ShareStartResult> = defineMethod({
|
|
145
|
+
method: "share/start",
|
|
146
|
+
direction: "client-to-instance",
|
|
147
|
+
mutating: true,
|
|
148
|
+
params,
|
|
149
|
+
result,
|
|
150
|
+
});
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import * as z from "zod";
|
|
2
|
+
import { ArtifactRef } from "../../artifact.ts";
|
|
3
|
+
import { ShareId } from "../../ids.ts";
|
|
4
|
+
import { defineMethod, type MethodDefinition } from "../../method.ts";
|
|
5
|
+
import { wireRegistry } from "../../wire-registry.ts";
|
|
6
|
+
import { Share } from "./start.ts";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* The params of `share/stop` (INTERFACES §6, D158): one share, or every active share of an
|
|
10
|
+
* artifact. Exactly one of the two is named; naming both or neither is `MOSTRA_HOST_INVALID_PARAMS`.
|
|
11
|
+
*/
|
|
12
|
+
export interface ShareStopParams {
|
|
13
|
+
/** The share to stop. */
|
|
14
|
+
readonly shareId?: string;
|
|
15
|
+
/** Stops every active share of this artifact instead. */
|
|
16
|
+
readonly artifact?: ArtifactRef;
|
|
17
|
+
/** Makes retries idempotent: stopping is idempotent by itself, so a retry changes nothing. */
|
|
18
|
+
readonly requestId?: string;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** The result of `share/stop`: the shares it ended (none when they had ended already). */
|
|
22
|
+
export interface ShareStopResult {
|
|
23
|
+
/** The shares this call ended. */
|
|
24
|
+
readonly stopped: readonly Share[];
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const params: z.ZodType<ShareStopParams> = z
|
|
28
|
+
.object({
|
|
29
|
+
shareId: ShareId.schema.exactOptional(),
|
|
30
|
+
artifact: ArtifactRef.exactOptional(),
|
|
31
|
+
requestId: z.string().min(1).exactOptional(),
|
|
32
|
+
})
|
|
33
|
+
.register(wireRegistry, { id: "ShareStopParams" });
|
|
34
|
+
|
|
35
|
+
const result: z.ZodType<ShareStopResult> = z
|
|
36
|
+
.object({ stopped: z.array(Share).readonly() })
|
|
37
|
+
.register(wireRegistry, { id: "ShareStopResult", description: "The shares that ended." });
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* `share/stop`: ends a share, or every active share of an artifact (D158): its link is revoked, so
|
|
41
|
+
* every session it gave answers 410, and its tunnel stops. Stopping a share that already ended
|
|
42
|
+
* succeeds and stops nothing; an unknown share is `MOSTRA_SHARE_NOT_FOUND`.
|
|
43
|
+
*/
|
|
44
|
+
export const shareStopMethod: MethodDefinition<ShareStopParams, ShareStopResult> = defineMethod({
|
|
45
|
+
method: "share/stop",
|
|
46
|
+
direction: "client-to-instance",
|
|
47
|
+
mutating: true,
|
|
48
|
+
params,
|
|
49
|
+
result,
|
|
50
|
+
});
|