@ignite-ember/extension-bridge 0.0.0-stage → 0.2.1

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 (69) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +5 -0
  3. package/README.md +364 -2
  4. package/dist/bridge.d.ts +37 -0
  5. package/dist/bridge.d.ts.map +1 -0
  6. package/dist/bridge.js +96 -0
  7. package/dist/bridge.js.map +1 -0
  8. package/dist/channel.d.ts +26 -0
  9. package/dist/channel.d.ts.map +1 -0
  10. package/dist/channel.js +36 -0
  11. package/dist/channel.js.map +1 -0
  12. package/dist/contract.d.ts +137 -0
  13. package/dist/contract.d.ts.map +1 -0
  14. package/dist/contract.js +9 -0
  15. package/dist/contract.js.map +1 -0
  16. package/dist/correlator.d.ts +37 -0
  17. package/dist/correlator.d.ts.map +1 -0
  18. package/dist/correlator.js +75 -0
  19. package/dist/correlator.js.map +1 -0
  20. package/dist/guestBridge.d.ts +63 -0
  21. package/dist/guestBridge.d.ts.map +1 -0
  22. package/dist/guestBridge.js +156 -0
  23. package/dist/guestBridge.js.map +1 -0
  24. package/dist/hostModel.d.ts +159 -0
  25. package/dist/hostModel.d.ts.map +1 -0
  26. package/dist/hostModel.generated.d.ts +2373 -0
  27. package/dist/hostModel.generated.d.ts.map +1 -0
  28. package/dist/hostModel.generated.js +1746 -0
  29. package/dist/hostModel.generated.js.map +1 -0
  30. package/dist/hostModel.js +172 -0
  31. package/dist/hostModel.js.map +1 -0
  32. package/dist/index.d.ts +12 -0
  33. package/dist/index.d.ts.map +1 -0
  34. package/dist/index.js +12 -0
  35. package/dist/index.js.map +1 -0
  36. package/dist/protocol.d.ts +348 -0
  37. package/dist/protocol.d.ts.map +1 -0
  38. package/dist/protocol.js +145 -0
  39. package/dist/protocol.js.map +1 -0
  40. package/dist/service.d.ts +168 -0
  41. package/dist/service.d.ts.map +1 -0
  42. package/dist/service.js +196 -0
  43. package/dist/service.js.map +1 -0
  44. package/dist/signals.d.ts +21 -0
  45. package/dist/signals.d.ts.map +1 -0
  46. package/dist/signals.js +52 -0
  47. package/dist/signals.js.map +1 -0
  48. package/dist/tokens.d.ts +101 -0
  49. package/dist/tokens.d.ts.map +1 -0
  50. package/dist/tokens.js +164 -0
  51. package/dist/tokens.js.map +1 -0
  52. package/dist/watchers.d.ts +12 -0
  53. package/dist/watchers.d.ts.map +1 -0
  54. package/dist/watchers.js +18 -0
  55. package/dist/watchers.js.map +1 -0
  56. package/package.json +53 -4
  57. package/src/bridge.ts +116 -0
  58. package/src/channel.ts +48 -0
  59. package/src/contract.ts +157 -0
  60. package/src/correlator.ts +88 -0
  61. package/src/guestBridge.ts +261 -0
  62. package/src/hostModel.generated.ts +3155 -0
  63. package/src/hostModel.ts +213 -0
  64. package/src/index.ts +11 -0
  65. package/src/protocol.ts +485 -0
  66. package/src/service.ts +278 -0
  67. package/src/signals.ts +65 -0
  68. package/src/tokens.ts +171 -0
  69. package/src/watchers.ts +18 -0
package/dist/bridge.js ADDED
@@ -0,0 +1,96 @@
1
+ /**
2
+ * The guest half: what an extension's page imports to reach igni.
3
+ *
4
+ * This is the file that becomes a published package. Nothing in it
5
+ * imports from the rest of the app, and nothing in it is trusted by
6
+ * the host — every check is on the other side. What it owes an
7
+ * extension author is an object that behaves like the client they
8
+ * would have had if their panel were part of the app, so that porting
9
+ * one is not a rewrite.
10
+ *
11
+ * The shape it presents is `rpc(method, args, timeoutMs)`, which is
12
+ * the whole surface the first panel ported behind it used. Everything else here —
13
+ * navigate, close, theme, params — is what a panel needed from the
14
+ * app around it and used to get by being inside it.
15
+ */
16
+ import { HostChannel } from "./channel.js";
17
+ import { DEFAULT_TIMEOUT_MS, GuestBridge } from "./guestBridge.js";
18
+ import { isHostMessage, } from "./protocol.js";
19
+ /**
20
+ * Wait for the host's `hello`, then hand back the bridge.
21
+ *
22
+ * Connecting is asynchronous because the host issues the nonce, and
23
+ * without one there is nothing to say. An extension that renders
24
+ * before awaiting this is rendering before it knows which extension
25
+ * it is.
26
+ *
27
+ * `P` and `S` name the extension's own launch parameters and settings;
28
+ * the bridge passes on what the host sent without checking it against
29
+ * them.
30
+ *
31
+ * @param options — how long to wait for the host's `hello` before
32
+ * giving up: `timeoutMs`, in milliseconds, and thirty seconds by
33
+ * default.
34
+ */
35
+ export function connect(options = {}) {
36
+ const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
37
+ const host = window.parent;
38
+ if (host === window) {
39
+ return Promise.reject(new Error("igni bridge: this page is not framed by a host, so there is nothing to connect to"));
40
+ }
41
+ return new Promise((resolve, reject) => {
42
+ const timer = setTimeout(() => {
43
+ window.removeEventListener("message", onHello);
44
+ reject(new Error(`igni bridge: no hello from the host within ${timeoutMs}ms`));
45
+ }, timeoutMs);
46
+ function onHello(event) {
47
+ if (event.source !== host)
48
+ return;
49
+ if (!isHostMessage(event.data) || event.data.kind !== "hello")
50
+ return;
51
+ clearTimeout(timer);
52
+ window.removeEventListener("message", onHello);
53
+ const channel = new HostChannel(host, event.data.nonce);
54
+ const bridge = new GuestBridge(channel, event.data);
55
+ window.addEventListener("message", (message) => {
56
+ if (!channel.isFrom(message) || !isHostMessage(message.data))
57
+ return;
58
+ bridge.receive(message.data);
59
+ });
60
+ resolve(expose(bridge));
61
+ }
62
+ window.addEventListener("message", onHello);
63
+ });
64
+ }
65
+ /**
66
+ * The bridge as the page holds it: a plain object whose members close
67
+ * over the one that does the work. So `const { rpc } = bridge`,
68
+ * `onClick={bridge.close}` and `{ ...bridge }` behave as they did before
69
+ * the bridge was a class, and nothing the page did not ask for — the
70
+ * nonce, the requests in flight — is one of its properties.
71
+ */
72
+ function expose(bridge) {
73
+ return {
74
+ extensionId: bridge.extensionId,
75
+ host: bridge.host,
76
+ service: bridge.service,
77
+ on: (signal, fn, onRefused) => bridge.on(signal, fn, onRefused),
78
+ get params() {
79
+ return bridge.params;
80
+ },
81
+ settings: bridge.settings,
82
+ get theme() {
83
+ return bridge.theme;
84
+ },
85
+ get tokens() {
86
+ return bridge.tokens;
87
+ },
88
+ rpc: (method, args, timeoutMs) => bridge.rpc(method, args, timeoutMs),
89
+ navigate: (to) => bridge.navigate(to),
90
+ close: () => bridge.close(),
91
+ onTheme: (fn) => bridge.onTheme(fn),
92
+ onParams: (fn) => bridge.onParams(fn),
93
+ setLocation: (state) => bridge.setLocation(state),
94
+ };
95
+ }
96
+ //# sourceMappingURL=bridge.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,26 @@
1
+ /**
2
+ * The guest's line to the window it is framed in: who that window is,
3
+ * and the nonce every message to it must carry.
4
+ */
5
+ import { type GuestMessage } from "./protocol.js";
6
+ /** A guest message without the envelope `HostChannel` adds. */
7
+ export type GuestBody = {
8
+ [K in GuestMessage["kind"]]: Omit<Extract<GuestMessage, {
9
+ kind: K;
10
+ }>, "igni" | "nonce">;
11
+ }[GuestMessage["kind"]];
12
+ export declare class HostChannel {
13
+ private readonly host;
14
+ private readonly nonce;
15
+ constructor(host: Window, nonce: string);
16
+ /**
17
+ * Did this event come from the host? The host is the only window that
18
+ * can reach this frame's parent slot, so the source is the check that
19
+ * matters. The origin is not pinned: the guest does not know which
20
+ * origin the app is served from, and learning it from the message
21
+ * would make the check circular.
22
+ */
23
+ isFrom(event: MessageEvent): boolean;
24
+ post(body: GuestBody): void;
25
+ }
26
+ //# sourceMappingURL=channel.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAElE,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG;KACrB,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI,CAC/B,OAAO,CAAC,YAAY,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,EAClC,MAAM,GAAG,OAAO,CACjB;CACF,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;AAExB,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM;IAGhC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAIpC,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;CAe5B"}
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The guest's line to the window it is framed in: who that window is,
3
+ * and the nonce every message to it must carry.
4
+ */
5
+ import { BRIDGE_VERSION } from "./protocol.js";
6
+ export class HostChannel {
7
+ host;
8
+ nonce;
9
+ constructor(host, nonce) {
10
+ this.host = host;
11
+ this.nonce = nonce;
12
+ }
13
+ /**
14
+ * Did this event come from the host? The host is the only window that
15
+ * can reach this frame's parent slot, so the source is the check that
16
+ * matters. The origin is not pinned: the guest does not know which
17
+ * origin the app is served from, and learning it from the message
18
+ * would make the check circular.
19
+ */
20
+ isFrom(event) {
21
+ return event.source === this.host;
22
+ }
23
+ post(body) {
24
+ // Targeted at "*" deliberately: the guest does not know the host's
25
+ // origin, and guessing one would mean a message silently going
26
+ // nowhere the first time the app is served from somewhere else.
27
+ // Nothing secret travels in this direction — the host authorises,
28
+ // the guest only asks.
29
+ // `kind` before `nonce`, as the guest always posted them: the fields
30
+ // are the same either way, but a host or a log that compares the
31
+ // serialised message sees the order.
32
+ const { kind, ...rest } = body;
33
+ this.host.postMessage({ igni: BRIDGE_VERSION, kind, nonce: this.nonce, ...rest }, "*");
34
+ }
35
+ }
36
+ //# sourceMappingURL=channel.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAqB,MAAM,eAAe,CAAC;AAUlE,MAAM,OAAO,WAAW;IAEH;IACA;IAFnB,YACmB,IAAY,EACZ,KAAa;QADb,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;IAC7B,CAAC;IAEJ;;;;;;OAMG;IACH,MAAM,CAAC,KAAmB;QACxB,OAAO,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,IAAI,CAAC;IACpC,CAAC;IAED,IAAI,CAAC,IAAe;QAClB,mEAAmE;QACnE,+DAA+D;QAC/D,gEAAgE;QAChE,kEAAkE;QAClE,uBAAuB;QACvB,qEAAqE;QACrE,iEAAiE;QACjE,qCAAqC;QACrC,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,WAAW,CACnB,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,EAAE,EAC1D,GAAG,CACJ,CAAC;IACJ,CAAC;CACF"}
@@ -0,0 +1,137 @@
1
+ /**
2
+ * What an extension's page is handed by `connect()`.
3
+ *
4
+ * `P` and `S` are the extension's own launch parameters and settings:
5
+ * the host sends whatever the extension's links and manifest put there,
6
+ * so the extension is the one that can name them.
7
+ */
8
+ import type { HostError, Signal } from "./hostModel.js";
9
+ import type { Host } from "./hostModel.generated.js";
10
+ import type { ExtensionSettings, LaunchParams, LocationState, RpcArgs } from "./protocol.js";
11
+ import type { ServiceBridge } from "./service.js";
12
+ import type { ThemeTokens } from "./tokens.js";
13
+ /** What an extension's page is handed. */
14
+ export interface Bridge<P extends LaunchParams = LaunchParams, S extends ExtensionSettings = ExtensionSettings> {
15
+ /** The id this frame is, as the host named it. */
16
+ readonly extensionId: string;
17
+ /** Launch parameters, as the host passed them. */
18
+ readonly params: P;
19
+ /**
20
+ * What `contributes.settings` is configured to.
21
+ *
22
+ * Fixed for the life of this frame — a change applies at the next
23
+ * mount, so there is no `onSettings`. Separate from {@link params}
24
+ * because that is *where you are* and this is *how you are set
25
+ * up*; one namespace for both would make a setting and a query
26
+ * key with the same name the same thing.
27
+ */
28
+ readonly settings: S;
29
+ /** The host's theme now. Use `onTheme` to follow it. */
30
+ readonly theme: string;
31
+ /**
32
+ * The published design tokens, already applied to this document's
33
+ * root. Here as a reading for anything that needs a value rather
34
+ * than a CSS variable — a canvas, a chart library.
35
+ */
36
+ readonly tokens: ThemeTokens;
37
+ /**
38
+ * Call a backend RPC. Rejects with the host's refusal, as a sentence.
39
+ *
40
+ * @param method — the method to call, as `ext.<extension-id>.<method>`
41
+ * names it.
42
+ * @param args — the method's arguments, by name.
43
+ * @param timeoutMs — how long to wait for the answer before giving up,
44
+ * in milliseconds. The host has a timeout of its own, and the
45
+ * shorter of the two is the one that fires.
46
+ */
47
+ rpc<T = unknown>(method: string, args?: RpcArgs, timeoutMs?: number): Promise<T>;
48
+ /**
49
+ * Ask the host app to navigate. It decides whether to.
50
+ *
51
+ * @param to — the page to go to; the host decides whether it exists.
52
+ */
53
+ navigate(to: string): void;
54
+ /** Tell the host this surface is finished. */
55
+ close(): void;
56
+ /**
57
+ * Follow the host's theme. Returns an unsubscribe.
58
+ *
59
+ * @param fn — called with the theme whenever it changes.
60
+ */
61
+ onTheme(fn: (theme: string) => void): () => void;
62
+ /**
63
+ * Follow the launch parameters.
64
+ *
65
+ * They arrive in `hello` and can change afterwards — a link
66
+ * resolved while this frame was already mounted, or the host
67
+ * restoring a saved location. Without this the host would have to
68
+ * rebuild the frame to deliver a changed parameter, losing
69
+ * whatever state it held.
70
+ *
71
+ * Fires only on change, never for the initial value; read
72
+ * {@link params} for that.
73
+ *
74
+ * @param fn — called with the parameters whenever they change.
75
+ */
76
+ onParams(fn: (params: P) => void): () => void;
77
+ /**
78
+ * Tell the host where inside this extension the user now is.
79
+ *
80
+ * Not a navigation — {@link navigate} is that. This says "still
81
+ * here, and here is now this". The host folds it into its own URL
82
+ * and replays it in the next `hello`, which is the only way an
83
+ * extension can be linked to or restored: the frame cannot write
84
+ * the address bar, and its `localStorage` dies with the ephemeral
85
+ * port it was served from.
86
+ *
87
+ * Strings only, and keep it small — it ends up in the host's URL.
88
+ * Call it when the user lands somewhere worth returning to, not on
89
+ * every keystroke.
90
+ *
91
+ * @param state — where inside the extension the user is now, in
92
+ * strings, for the host to fold into its own URL.
93
+ */
94
+ setLocation(state: LocationState): void;
95
+ /**
96
+ * igni, as this extension sees it: the host object model
97
+ * (igni-core's `docs/HOST_OBJECT_MODEL.md` (https://github.com/ignite-ember/igni-core/blob/main/docs/HOST_OBJECT_MODEL.md)). The same model the
98
+ * extension's process reaches as `ext.host`.
99
+ *
100
+ * const busy = await bridge.host.chat.processing.get();
101
+ * await bridge.host.chat.post("Two issues in the files you changed.");
102
+ *
103
+ * A page's `host.ui` is the window it is framed in. Every object needs
104
+ * its grant in the manifest's `permissions.host`; one that is not
105
+ * granted rejects with a `HostError` whose `code` is `not_granted`.
106
+ */
107
+ readonly host: Host;
108
+ /**
109
+ * Handle a host signal: `bridge.on(bridge.host.chat.run_completed, fn)`.
110
+ *
111
+ * The first handler of a signal subscribes to it; removing the last
112
+ * one unsubscribes. A signal whose object is not granted never
113
+ * arrives; the refusal goes to `onRefused`, or to the console when
114
+ * there is none. Returns an unsubscribe.
115
+ *
116
+ * @param signal — the host signal to follow.
117
+ * @param fn — called with the signal's value each time it arrives.
118
+ * @param onRefused — called with the refusal when the host will not
119
+ * grant the signal; without one the refusal goes to the console.
120
+ */
121
+ on<T>(signal: Signal<T>, fn: (value: T) => void, onRefused?: (error: HostError) => void): () => void;
122
+ /**
123
+ * The extension's own service, reached directly, as the signed-in
124
+ * person.
125
+ *
126
+ * const res = await bridge.service.fetch("/v1/notes");
127
+ * const socket = await bridge.service.websocket("/v1/rooms/a");
128
+ *
129
+ * The host fetches a token whose audience is this extension's service
130
+ * and nothing else; it is kept and renewed before it expires. No
131
+ * `permissions.host` grant: having a service is the grant — see
132
+ * igni-core's `docs/HOST_OBJECT_MODEL.md` (https://github.com/ignite-ember/igni-core/blob/main/docs/HOST_OBJECT_MODEL.md). `url` is `null` when the
133
+ * extension has none.
134
+ */
135
+ readonly service: ServiceBridge;
136
+ }
137
+ //# sourceMappingURL=contract.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,OAAO,EACR,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,0CAA0C;AAC1C,MAAM,WAAW,MAAM,CACrB,CAAC,SAAS,YAAY,GAAG,YAAY,EACrC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB;IAE/C,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;;;;;;;OASG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,8CAA8C;IAC9C,KAAK,IAAI,IAAI,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACjD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC9C;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAExC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAEpB;;;;;;;;;;;;OAYG;IACH,EAAE,CAAC,CAAC,EACF,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EACtB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GACrC,MAAM,IAAI,CAAC;IAEd;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * What an extension's page is handed by `connect()`.
3
+ *
4
+ * `P` and `S` are the extension's own launch parameters and settings:
5
+ * the host sends whatever the extension's links and manifest put there,
6
+ * so the extension is the one that can name them.
7
+ */
8
+ export {};
9
+ //# sourceMappingURL=contract.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Requests the guest sent and is waiting on, matched to their replies by
3
+ * id.
4
+ *
5
+ * Each kind of request the guest makes — an RPC call, a host-model
6
+ * request, a service token — has its own `Correlator`, so a reply of
7
+ * one kind can never settle a request of another.
8
+ */
9
+ export declare class Correlator {
10
+ private readonly prefix;
11
+ private readonly nextNumber;
12
+ private readonly waiting;
13
+ /**
14
+ * `prefix` tells this correlator's ids apart from another's in a log;
15
+ * `nextNumber` numbers them. A bridge's correlators share one counter,
16
+ * so its ids run 1, h2, s3 across every kind, as they always have.
17
+ */
18
+ constructor(prefix: string, nextNumber: () => number);
19
+ /**
20
+ * Send one request and wait for its reply.
21
+ *
22
+ * `timeoutMs` null waits for as long as the reply takes; otherwise the
23
+ * request is given up on with `timedOut()` and a late reply is ignored.
24
+ */
25
+ send<T>(timeoutMs: number | null, timedOut: () => Error, post: (id: string) => void): Promise<T>;
26
+ /** The reply to `id` succeeded. */
27
+ resolve(id: string, value: unknown): void;
28
+ /** The reply to `id` refused. */
29
+ reject(id: string, error: Error): void;
30
+ /**
31
+ * Stop waiting on `id`. An id nobody is waiting on is either a late
32
+ * reply to something that timed out, or noise; either way there is no
33
+ * one to tell.
34
+ */
35
+ private take;
36
+ }
37
+ //# sourceMappingURL=correlator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"correlator.d.ts","sourceRoot":"","sources":["../src/correlator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,qBAAa,UAAU;IASnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAT7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD;;;;OAIG;gBAEgB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,MAAM;IAG3C;;;;;OAKG;IACH,IAAI,CAAC,CAAC,EACJ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,QAAQ,EAAE,MAAM,KAAK,EACrB,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GACzB,OAAO,CAAC,CAAC,CAAC;IA0Bb,mCAAmC;IACnC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAIzC,iCAAiC;IACjC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAItC;;;;OAIG;IACH,OAAO,CAAC,IAAI;CAOb"}
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Requests the guest sent and is waiting on, matched to their replies by
3
+ * id.
4
+ *
5
+ * Each kind of request the guest makes — an RPC call, a host-model
6
+ * request, a service token — has its own `Correlator`, so a reply of
7
+ * one kind can never settle a request of another.
8
+ */
9
+ export class Correlator {
10
+ prefix;
11
+ nextNumber;
12
+ waiting = new Map();
13
+ /**
14
+ * `prefix` tells this correlator's ids apart from another's in a log;
15
+ * `nextNumber` numbers them. A bridge's correlators share one counter,
16
+ * so its ids run 1, h2, s3 across every kind, as they always have.
17
+ */
18
+ constructor(prefix, nextNumber) {
19
+ this.prefix = prefix;
20
+ this.nextNumber = nextNumber;
21
+ }
22
+ /**
23
+ * Send one request and wait for its reply.
24
+ *
25
+ * `timeoutMs` null waits for as long as the reply takes; otherwise the
26
+ * request is given up on with `timedOut()` and a late reply is ignored.
27
+ */
28
+ send(timeoutMs, timedOut, post) {
29
+ const id = `${this.prefix}${this.nextNumber()}`;
30
+ return new Promise((resolve, reject) => {
31
+ const timer = timeoutMs === null
32
+ ? undefined
33
+ : setTimeout(() => {
34
+ this.waiting.delete(id);
35
+ reject(timedOut());
36
+ }, timeoutMs);
37
+ this.waiting.set(id, {
38
+ resolve: resolve,
39
+ reject,
40
+ timer,
41
+ });
42
+ try {
43
+ post(id);
44
+ }
45
+ catch (error) {
46
+ // Nothing was sent, so no reply will come: do not leave the
47
+ // waiter and its timer behind for a request that never left.
48
+ this.take(id);
49
+ throw error;
50
+ }
51
+ });
52
+ }
53
+ /** The reply to `id` succeeded. */
54
+ resolve(id, value) {
55
+ this.take(id)?.resolve(value);
56
+ }
57
+ /** The reply to `id` refused. */
58
+ reject(id, error) {
59
+ this.take(id)?.reject(error);
60
+ }
61
+ /**
62
+ * Stop waiting on `id`. An id nobody is waiting on is either a late
63
+ * reply to something that timed out, or noise; either way there is no
64
+ * one to tell.
65
+ */
66
+ take(id) {
67
+ const waiter = this.waiting.get(id);
68
+ if (waiter === undefined)
69
+ return undefined;
70
+ this.waiting.delete(id);
71
+ clearTimeout(waiter.timer);
72
+ return waiter;
73
+ }
74
+ }
75
+ //# sourceMappingURL=correlator.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"correlator.js","sourceRoot":"","sources":["../src/correlator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,MAAM,OAAO,UAAU;IASF;IACA;IATF,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAErD;;;;OAIG;IACH,YACmB,MAAc,EACd,UAAwB;QADxB,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAc;IACxC,CAAC;IAEJ;;;;;OAKG;IACH,IAAI,CACF,SAAwB,EACxB,QAAqB,EACrB,IAA0B;QAE1B,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QAChD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,KAAK,GACT,SAAS,KAAK,IAAI;gBAChB,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE;oBACd,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;oBACxB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACrB,CAAC,EAAE,SAAS,CAAC,CAAC;YACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE;gBACnB,OAAO,EAAE,OAAmC;gBAC5C,MAAM;gBACN,KAAK;aACN,CAAC,CAAC;YACH,IAAI,CAAC;gBACH,IAAI,CAAC,EAAE,CAAC,CAAC;YACX,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,4DAA4D;gBAC5D,6DAA6D;gBAC7D,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACd,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,mCAAmC;IACnC,OAAO,CAAC,EAAU,EAAE,KAAc;QAChC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,iCAAiC;IACjC,MAAM,CAAC,EAAU,EAAE,KAAY;QAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACK,IAAI,CAAC,EAAU;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxB,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}
@@ -0,0 +1,63 @@
1
+ /**
2
+ * The bridge an extension's page holds once the host has said hello.
3
+ *
4
+ * It owns everything the page learned from the host — params, theme,
5
+ * tokens — and the three kinds of request it can be waiting on, each
6
+ * with its own {@link Correlator}. Messages from the host are routed by
7
+ * kind through one table, {@link GuestBridge.handlers}.
8
+ */
9
+ import type { HostChannel } from "./channel.js";
10
+ import type { Bridge } from "./contract.js";
11
+ import { HostError, type Signal } from "./hostModel.js";
12
+ import { Host } from "./hostModel.generated.js";
13
+ import type { ExtensionSettings, HelloMessage, HostMessage, LaunchParams, LocationState, RpcArgs } from "./protocol.js";
14
+ import { ServiceLink } from "./service.js";
15
+ import { type ThemeTokens } from "./tokens.js";
16
+ /** How long a request waits before giving up. The host has its own. */
17
+ export declare const DEFAULT_TIMEOUT_MS = 30000;
18
+ export declare class GuestBridge<P extends LaunchParams, S extends ExtensionSettings> implements Bridge<P, S> {
19
+ private readonly channel;
20
+ readonly extensionId: string;
21
+ readonly settings: S;
22
+ readonly host: Host;
23
+ readonly service: ServiceLink;
24
+ private currentParams;
25
+ private currentTheme;
26
+ private currentTokens;
27
+ private readonly themeWatchers;
28
+ private readonly paramWatchers;
29
+ /** One numbering for every request, whatever its kind. */
30
+ private requestCount;
31
+ private readonly nextRequest;
32
+ private readonly calls;
33
+ private readonly hostRequests;
34
+ private readonly tokenRequests;
35
+ private readonly signals;
36
+ private readonly handlers;
37
+ /**
38
+ * `params` and `settings` are the extension's to name (`P`, `S`): the
39
+ * host sends what the extension's own links and manifest put there.
40
+ */
41
+ constructor(channel: HostChannel, hello: HelloMessage);
42
+ get params(): P;
43
+ get theme(): string;
44
+ get tokens(): ThemeTokens;
45
+ /** Act on one message the host sent. */
46
+ receive(message: HostMessage): void;
47
+ rpc<T = unknown>(method: string, args?: RpcArgs, timeoutMs?: number): Promise<T>;
48
+ navigate(to: string): void;
49
+ close(): void;
50
+ onTheme(fn: (theme: string) => void): () => void;
51
+ onParams(fn: (params: P) => void): () => void;
52
+ setLocation(state: LocationState): void;
53
+ on<T>(signal: Signal<T>, fn: (value: T) => void, onRefused?: (error: HostError) => void): () => void;
54
+ private applyTheme;
55
+ private applyParams;
56
+ private hostRequest;
57
+ /** One token request to the host, which asks igni as this extension. */
58
+ private askForToken;
59
+ private settleCall;
60
+ private settleHostRequest;
61
+ private settleTokenRequest;
62
+ }
63
+ //# sourceMappingURL=guestBridge.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guestBridge.d.ts","sourceRoot":"","sources":["../src/guestBridge.ts"],"names":[],"mappings":"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"}