@botiverse/porthole 0.14.4 → 0.14.6
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/CHANGELOG.md +71 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -1
- package/dist/compile/policy.d.ts +6 -0
- package/dist/compile/policy.js +6 -0
- package/dist/conformance/entry.d.ts +25 -6
- package/dist/conformance/entry.js +69 -18
- package/dist/conformance/harness/page.d.ts +12 -0
- package/dist/conformance/harness/page.js +95 -51
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +39 -13
- package/dist/conformance/served.js +140 -0
- package/dist/files/paths.d.ts +2 -2
- package/dist/files/paths.js +12 -2
- package/dist/host/client.d.ts +8 -0
- package/dist/host/client.js +47 -17
- package/dist/host/create-host.d.ts +10 -0
- package/dist/host/create-host.js +126 -10
- package/dist/host/door.d.ts +41 -0
- package/dist/host/door.js +55 -0
- package/dist/host/locate.js +2 -0
- package/dist/host/locator.d.ts +55 -3
- package/dist/host/locator.js +152 -42
- package/dist/host/outcome.d.ts +58 -1
- package/dist/host/outcome.js +74 -6
- package/dist/host/types.d.ts +20 -4
- package/dist/isolation/served.d.ts +1 -1
- package/dist/isolation/served.js +35 -0
- package/dist/isolation/types.d.ts +20 -2
- package/dist/isolation/types.js +2 -0
- package/dist/platform/types.d.ts +22 -0
- package/dist/platform/web.js +55 -12
- package/dist/react/frame.d.ts +2 -1
- package/dist/react/view.d.ts +13 -0
- package/dist/react/view.js +101 -2
- package/dist/server/files.d.ts +11 -0
- package/dist/server/files.js +26 -4
- package/dist/server/host.js +106 -28
- package/dist/server/index.d.ts +2 -1
- package/dist/server/index.js +6 -1
- package/dist/server/pages.d.ts +32 -0
- package/dist/server/pages.js +82 -6
- package/dist/server/server.js +140 -11
- package/dist/server/types.d.ts +15 -1
- package/dist/transport/post-message.d.ts +1 -9
- package/dist/transport/post-message.js +2 -8
- package/docs/ADOPTING.md +58 -0
- package/docs/DECISIONS.md +290 -0
- package/docs/DESIGN.md +24 -16
- package/docs/THREAT_MODEL.md +98 -3
- package/package.json +1 -1
- package/src/check/page.ts +6 -1
- package/src/compile/policy.ts +7 -0
- package/src/conformance/entry.ts +129 -24
- package/src/conformance/harness/page.ts +112 -49
- package/src/conformance/host-kit.ts +53 -16
- package/src/conformance/served.ts +175 -0
- package/src/files/paths.ts +11 -2
- package/src/host/client.ts +59 -22
- package/src/host/create-host.ts +146 -18
- package/src/host/door.ts +97 -0
- package/src/host/locate.ts +2 -0
- package/src/host/locator.ts +208 -57
- package/src/host/outcome.ts +88 -7
- package/src/host/types.ts +20 -4
- package/src/isolation/served.ts +40 -1
- package/src/isolation/types.ts +19 -2
- package/src/platform/types.ts +21 -0
- package/src/platform/web.ts +55 -20
- package/src/react/frame.tsx +2 -1
- package/src/react/view.tsx +149 -2
- package/src/server/files.ts +37 -5
- package/src/server/host.ts +131 -46
- package/src/server/index.ts +6 -1
- package/src/server/pages.ts +101 -6
- package/src/server/server.ts +186 -19
- package/src/server/types.ts +16 -1
- package/src/transport/post-message.ts +1 -9
|
@@ -30,12 +30,26 @@ function invoke(page, method, ...args) {
|
|
|
30
30
|
}, [method, args]);
|
|
31
31
|
}
|
|
32
32
|
/** The display's frame element's document, once it exists. */
|
|
33
|
+
/** A display's first outcome, once it has one (P040, P125). */
|
|
34
|
+
async function outcomeOf(page, id) {
|
|
35
|
+
let found = null;
|
|
36
|
+
await expect
|
|
37
|
+
.poll(async () => {
|
|
38
|
+
const events = await invoke(page, "events", id);
|
|
39
|
+
const each = events.find((event) => event.type === "outcome");
|
|
40
|
+
found = each === undefined ? null : each.detail;
|
|
41
|
+
return found !== null;
|
|
42
|
+
}, { message: "the display has an outcome", timeout: 15_000 })
|
|
43
|
+
.toBe(true);
|
|
44
|
+
return found;
|
|
45
|
+
}
|
|
33
46
|
async function frameIn(page, id) {
|
|
34
47
|
let found = null;
|
|
35
48
|
await expect
|
|
36
49
|
.poll(async () => {
|
|
37
50
|
const element = await page
|
|
38
|
-
|
|
51
|
+
// The display's own frame, never its door (P125), which is gone once it said its word.
|
|
52
|
+
.locator(`#porthole-display-${id} iframe:not([data-porthole-door])`)
|
|
39
53
|
.elementHandle({ timeout: 2_000 })
|
|
40
54
|
.catch(() => null);
|
|
41
55
|
found = (await element?.contentFrame()) ?? null;
|
|
@@ -223,24 +237,35 @@ export function hostConformance(options) {
|
|
|
223
237
|
: given.unknown,
|
|
224
238
|
}),
|
|
225
239
|
async frame(page, url) {
|
|
240
|
+
await ready(page);
|
|
241
|
+
if (options.issue === undefined) {
|
|
242
|
+
throw new Error("A clean address is framed through the app's issue endpoint ({ address }, P125): give defineHostConformance its issue");
|
|
243
|
+
}
|
|
244
|
+
const instance = await served.artifact("entry", "1");
|
|
245
|
+
const id = await invoke(page, "showAddress", configOf(instance), {
|
|
246
|
+
issue: options.issue.url,
|
|
247
|
+
...(options.issue.headers === undefined ? {} : { headers: options.issue.headers }),
|
|
248
|
+
}, url);
|
|
249
|
+
return {
|
|
250
|
+
frame: () => frameIn(page, id),
|
|
251
|
+
outcome: () => outcomeOf(page, id),
|
|
252
|
+
framed: () => invoke(page, "framed", id),
|
|
253
|
+
};
|
|
254
|
+
},
|
|
255
|
+
async frameDirectly(page, url) {
|
|
226
256
|
await ready(page);
|
|
227
257
|
const instance = await served.artifact("entry", "1");
|
|
228
258
|
const id = await invoke(page, "show", configOf(instance), instance, {
|
|
229
259
|
location: { url, origin: new URL(url).origin },
|
|
230
260
|
});
|
|
231
261
|
return {
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
await
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
found = each === undefined ? null : each.detail;
|
|
240
|
-
return found !== null;
|
|
241
|
-
}, { message: "the display has an outcome", timeout: 15_000 })
|
|
242
|
-
.toBe(true);
|
|
243
|
-
return found;
|
|
262
|
+
outcome: () => outcomeOf(page, id),
|
|
263
|
+
framed: () => invoke(page, "framed", id),
|
|
264
|
+
async hostErrors() {
|
|
265
|
+
const events = await invoke(page, "events", id);
|
|
266
|
+
return events.flatMap((event) => event.type === "hostError"
|
|
267
|
+
? [event.detail]
|
|
268
|
+
: []);
|
|
244
269
|
},
|
|
245
270
|
};
|
|
246
271
|
},
|
|
@@ -297,6 +322,7 @@ const DOMAIN_CASES = [
|
|
|
297
322
|
"served.domain.self-navigation",
|
|
298
323
|
...TAB_CASES,
|
|
299
324
|
"served.domain.frame-ancestors",
|
|
325
|
+
"served.domain.door",
|
|
300
326
|
"served.domain.egress",
|
|
301
327
|
];
|
|
302
328
|
/**
|
|
@@ -952,6 +952,146 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
952
952
|
expect(shown.origin, "probe: a foreign origin framed the content's origin").not.toBe(location.origin);
|
|
953
953
|
}
|
|
954
954
|
});
|
|
955
|
+
define("served.domain.door", "a served display's door is on its own origin, opaque, says open from null, is taken once, refuses the wrong ticket, and says what the content route says (P125)", async ({ page }) => {
|
|
956
|
+
const doorOf = (location) => {
|
|
957
|
+
expect(location.door, "probe: the server gives a door for a served display").toBeDefined();
|
|
958
|
+
return location.door.url;
|
|
959
|
+
};
|
|
960
|
+
// Land on a host-origin page first, so the door (framed by it) is within frame-ancestors.
|
|
961
|
+
await host.show(page, await host.shell("door-nav"), { content: SHELL_CONTENT });
|
|
962
|
+
// (1) The door is on the display's own origin, at Porthole's door path.
|
|
963
|
+
const first = await host.locate(await host.shell("door-shape"));
|
|
964
|
+
const door = new URL(doorOf(first));
|
|
965
|
+
expect(door.origin, "probe: the door is on the display's origin").toBe(first.origin);
|
|
966
|
+
expect(door.pathname, "probe: the door is at /__porthole/door/<key>").toMatch(/^\/__porthole\/door\/[A-Za-z0-9_-]+$/u);
|
|
967
|
+
// (2) Framed opaque (sandbox allow-scripts), it says `open` from the opaque origin within
|
|
968
|
+
// SETTLE_MS; (5) and a door on a tab of its own is an opaque origin too.
|
|
969
|
+
const said = await page.evaluate(async ({ url, settle }) => {
|
|
970
|
+
const frame = document.createElement("iframe");
|
|
971
|
+
// Opaque: scripts only (the probe frames the door as the host does, P125).
|
|
972
|
+
frame.sandbox.add("allow-scripts");
|
|
973
|
+
const got = new Promise((resolve) => {
|
|
974
|
+
const onMessage = (event) => {
|
|
975
|
+
if (event.source === frame.contentWindow) {
|
|
976
|
+
window.removeEventListener("message", onMessage);
|
|
977
|
+
resolve({ origin: event.origin, data: event.data });
|
|
978
|
+
}
|
|
979
|
+
};
|
|
980
|
+
window.addEventListener("message", onMessage);
|
|
981
|
+
setTimeout(() => resolve(null), settle);
|
|
982
|
+
});
|
|
983
|
+
frame.src = url;
|
|
984
|
+
document.body.append(frame);
|
|
985
|
+
const message = await got;
|
|
986
|
+
frame.remove();
|
|
987
|
+
return message;
|
|
988
|
+
}, { url: door.href, settle: SETTLE_MS + 2_000 });
|
|
989
|
+
expect(said, "probe: the door said nothing when framed opaque").not.toBeNull();
|
|
990
|
+
expect(said?.origin, "probe: the door spoke from an opaque origin").toBe("null");
|
|
991
|
+
expect(said?.data?.method, "probe: the door spoke a frame status").toBe("porthole/notifications/frame-status");
|
|
992
|
+
expect(said?.data?.params?.state, "probe: the door said open").toBe("open");
|
|
993
|
+
// (5) The door's own answer is sandboxed in its header too (opaque on a tab, and in a frame a
|
|
994
|
+
// host's platform forgot to sandbox): scripts alone, never its origin, and no cookie.
|
|
995
|
+
const headered = await host.locate(await host.shell("door-header"));
|
|
996
|
+
const doorAnswer = await page.request.get(doorOf(headered), { failOnStatusCode: false });
|
|
997
|
+
const doorCsp = doorAnswer.headers()["content-security-policy"] ?? "";
|
|
998
|
+
expect(doorAnswer.status(), "probe: a fresh door ticket opens the door").toBe(200);
|
|
999
|
+
expect(doorCsp
|
|
1000
|
+
.split(";")
|
|
1001
|
+
.map((each) => each.trim())
|
|
1002
|
+
.filter((each) => each.startsWith("sandbox")), "probe: the door's header sandboxes it with scripts alone, keeping no origin of its own").toEqual(["sandbox allow-scripts"]);
|
|
1003
|
+
expect(doorAnswer.headers()["set-cookie"], "probe: the door sets no cookie").toBeUndefined();
|
|
1004
|
+
// (3) The same door ticket again opens nothing: a used ticket is `session`.
|
|
1005
|
+
const again = await page.request.get(door.href, { failOnStatusCode: false });
|
|
1006
|
+
expect(again.status(), "probe: a used door ticket is 401 session").toBe(401);
|
|
1007
|
+
// (4) The door ticket at the content route, and the content ticket at the door, open
|
|
1008
|
+
// nothing; (6) a fresh door framed from a foreign origin hears nothing (frame-ancestors).
|
|
1009
|
+
const fresh = await host.locate(await host.shell("door-cross"));
|
|
1010
|
+
const freshDoor = new URL(doorOf(fresh));
|
|
1011
|
+
const freshContent = new URL(fresh.url);
|
|
1012
|
+
const key = freshDoor.pathname.split("/").at(-1) ?? "";
|
|
1013
|
+
const doorTicket = freshDoor.searchParams.get("ticket") ?? "";
|
|
1014
|
+
const contentTicket = freshContent.searchParams.get("ticket") ?? "";
|
|
1015
|
+
const doorTicketAtContent = `${fresh.origin}/__porthole/d/${key}?ticket=${doorTicket}`;
|
|
1016
|
+
const contentTicketAtDoor = `${fresh.origin}/__porthole/door/${key}?ticket=${contentTicket}`;
|
|
1017
|
+
for (const [what, url] of [
|
|
1018
|
+
["the door ticket at the content route", doorTicketAtContent],
|
|
1019
|
+
["the content ticket at the door", contentTicketAtDoor],
|
|
1020
|
+
]) {
|
|
1021
|
+
const response = await page.request.get(url, { failOnStatusCode: false });
|
|
1022
|
+
expect(response.status(), `probe: ${what} opens nothing`).toBe(401);
|
|
1023
|
+
}
|
|
1024
|
+
// (7) The door and the content route say the same block for the same grant (P125's
|
|
1025
|
+
// invariant): for one issue, its door ticket at the door and its content ticket at
|
|
1026
|
+
// `/__porthole/d/`, each from a browser with no cookie, answer the same status and reason.
|
|
1027
|
+
// `session`: each ticket already used once; `not-found`: a version that doesn't exist.
|
|
1028
|
+
const browser = page.context().browser();
|
|
1029
|
+
const wordOf = async (url) => {
|
|
1030
|
+
const isolated = await browser.newContext();
|
|
1031
|
+
try {
|
|
1032
|
+
const answer = await isolated.request.get(url, {
|
|
1033
|
+
failOnStatusCode: false,
|
|
1034
|
+
maxRedirects: 0,
|
|
1035
|
+
headers: { "sec-fetch-dest": "iframe" },
|
|
1036
|
+
});
|
|
1037
|
+
const body = await answer.text();
|
|
1038
|
+
return {
|
|
1039
|
+
status: answer.status(),
|
|
1040
|
+
reason: /data-porthole-reason="([a-z-]+)"/u.exec(body)?.[1] ?? null,
|
|
1041
|
+
};
|
|
1042
|
+
}
|
|
1043
|
+
finally {
|
|
1044
|
+
await isolated.close();
|
|
1045
|
+
}
|
|
1046
|
+
};
|
|
1047
|
+
const used = await host.locate(await host.shell("door-same-session"));
|
|
1048
|
+
await wordOf(doorOf(used));
|
|
1049
|
+
await wordOf(used.url);
|
|
1050
|
+
const usedDoor = await wordOf(doorOf(used));
|
|
1051
|
+
const usedContent = await wordOf(used.url);
|
|
1052
|
+
expect(usedDoor, "probe: a used door ticket says session").toEqual({
|
|
1053
|
+
status: 401,
|
|
1054
|
+
reason: "session",
|
|
1055
|
+
});
|
|
1056
|
+
expect(usedContent, "probe: the content route says what the door says (used)").toEqual(usedDoor);
|
|
1057
|
+
const page1 = await host.artifact("door-same-missing", "1");
|
|
1058
|
+
const missing = page1.document.kind === "artifact"
|
|
1059
|
+
? { ...page1, document: { ...page1.document, version: "porthole-no-such-version" } }
|
|
1060
|
+
: page1;
|
|
1061
|
+
let gone = null;
|
|
1062
|
+
try {
|
|
1063
|
+
gone = await host.locate(missing);
|
|
1064
|
+
}
|
|
1065
|
+
catch {
|
|
1066
|
+
// A host that refuses to issue for a version it doesn't have answers before any frame.
|
|
1067
|
+
info?.annotations.push({
|
|
1068
|
+
type: "measured",
|
|
1069
|
+
description: "the host refuses to issue for a missing version: not-found is never framed",
|
|
1070
|
+
});
|
|
1071
|
+
}
|
|
1072
|
+
if (gone !== null) {
|
|
1073
|
+
const goneDoor = await wordOf(doorOf(gone));
|
|
1074
|
+
const goneContent = await wordOf(gone.url);
|
|
1075
|
+
expect(goneDoor, "probe: a missing document's door says not-found").toEqual({
|
|
1076
|
+
status: 404,
|
|
1077
|
+
reason: "not-found",
|
|
1078
|
+
});
|
|
1079
|
+
expect(goneContent, "probe: the content route says what the door says (missing)").toEqual(goneDoor);
|
|
1080
|
+
}
|
|
1081
|
+
// (6) A fresh door from a foreign origin: frame-ancestors refuses it, so it says nothing.
|
|
1082
|
+
const foreignDoor = await host.locate(await host.shell("door-foreign"));
|
|
1083
|
+
await host.frameFromForeignOrigin(page, doorOf(foreignDoor));
|
|
1084
|
+
await page.waitForTimeout(SETTLE_MS);
|
|
1085
|
+
for (const frame of page.frames().slice(1)) {
|
|
1086
|
+
const reached = await Promise.race([
|
|
1087
|
+
frame
|
|
1088
|
+
.evaluate(() => document.querySelector("[data-porthole-door]") !== null)
|
|
1089
|
+
.catch(() => false),
|
|
1090
|
+
new Promise((resolve) => setTimeout(() => resolve(false), 2_000)),
|
|
1091
|
+
]);
|
|
1092
|
+
expect(reached, "probe: a foreign origin framed the door").toBe(false);
|
|
1093
|
+
}
|
|
1094
|
+
});
|
|
955
1095
|
define("served.domain.egress", "the CSP in the document's headers closes egress; only what the config opens to any https site (images, media) reaches it", async ({ page }) => {
|
|
956
1096
|
const display = await host.show(page, await host.shell("egress"), {
|
|
957
1097
|
content: SHELL_CONTENT,
|
package/dist/files/paths.d.ts
CHANGED
|
@@ -49,8 +49,8 @@ export interface FileSetProblem {
|
|
|
49
49
|
/**
|
|
50
50
|
* Checks a version's files before it is published (P081): every path by `filePathProblem`; no
|
|
51
51
|
* two paths that differ only in case, and no path that is both a file and a directory; the
|
|
52
|
-
* entry is one of them; the count, each size and the total
|
|
53
|
-
* `fileLimits`). Empty when it may be published.
|
|
52
|
+
* entry is one of them, and a page (`.html` or `.htm`, P125); the count, each size and the total
|
|
53
|
+
* within the limits (a config's, see `fileLimits`). Empty when it may be published.
|
|
54
54
|
*/
|
|
55
55
|
export declare function checkFileSet(files: Readonly<Record<string, FileSetEntryLike>>, options?: {
|
|
56
56
|
readonly entry?: string;
|
package/dist/files/paths.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { isPagePath } from "./types.js";
|
|
1
2
|
/**
|
|
2
3
|
* A version made of files (P081): the rules a published path follows, the limits a version is
|
|
3
4
|
* held to, and how a request's path finds its file. Pure: any runtime. A host checks a version
|
|
@@ -94,8 +95,8 @@ const sizeOf = (bytes) => bytes >= 1024 * 1024
|
|
|
94
95
|
/**
|
|
95
96
|
* Checks a version's files before it is published (P081): every path by `filePathProblem`; no
|
|
96
97
|
* two paths that differ only in case, and no path that is both a file and a directory; the
|
|
97
|
-
* entry is one of them; the count, each size and the total
|
|
98
|
-
* `fileLimits`). Empty when it may be published.
|
|
98
|
+
* entry is one of them, and a page (`.html` or `.htm`, P125); the count, each size and the total
|
|
99
|
+
* within the limits (a config's, see `fileLimits`). Empty when it may be published.
|
|
99
100
|
*/
|
|
100
101
|
export function checkFileSet(files, options = {}) {
|
|
101
102
|
const limits = options.limits ?? fileLimits();
|
|
@@ -169,6 +170,15 @@ export function checkFileSet(files, options = {}) {
|
|
|
169
170
|
message: `No ${JSON.stringify(entry)}: the page the version opens at is one of its files`,
|
|
170
171
|
});
|
|
171
172
|
}
|
|
173
|
+
else if (!isPagePath(entry)) {
|
|
174
|
+
// A version opens at a page (P125, P124-2): any other file is served inert, says nothing, and
|
|
175
|
+
// would show only Porthole's fallback.
|
|
176
|
+
problems.push({
|
|
177
|
+
path: entry,
|
|
178
|
+
code: "entry",
|
|
179
|
+
message: `${JSON.stringify(entry)} isn't a page: the version opens at an .html (or .htm) file of its own`,
|
|
180
|
+
});
|
|
181
|
+
}
|
|
172
182
|
return problems;
|
|
173
183
|
}
|
|
174
184
|
/**
|
package/dist/host/client.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { Displays } from "../displays/displays.ts";
|
|
3
3
|
import type { FrameLocation, InstanceLocator, InstanceRef } from "../isolation/types.ts";
|
|
4
|
+
import { type Resolved } from "./locator.ts";
|
|
4
5
|
import type { FrameOutcome } from "./types.ts";
|
|
5
6
|
/**
|
|
6
7
|
* The client half of the host kit (P072): what the app's page needs from its server's Porthole
|
|
@@ -60,6 +61,13 @@ export interface PortholeClient<N extends string = string> extends InstanceLocat
|
|
|
60
61
|
config(this: void, kind: N): PortholeConfig | null;
|
|
61
62
|
/** The same, for an instance's kind. */
|
|
62
63
|
configFor(this: void, instance: InstanceRef): PortholeConfig | null;
|
|
64
|
+
/**
|
|
65
|
+
* What a clean address names, for this viewer (P125): its instance and an issued location (a
|
|
66
|
+
* door, a ticket) for the caller's own first frame (`oneShot(location, locator)`), or the outcome
|
|
67
|
+
* the frame endpoint answered instead (signed out, denied, not found), with no frame built. A
|
|
68
|
+
* clean address is for a tab: never frame one directly (`checkFrameLocation` refuses it).
|
|
69
|
+
*/
|
|
70
|
+
resolve(this: void, address: string, signal?: AbortSignal): Promise<Resolved>;
|
|
63
71
|
/** An instance's clean address (`entry.pathOf` on the server), or null. */
|
|
64
72
|
link(this: void, instance: InstanceRef): Promise<string | null>;
|
|
65
73
|
/** The clean address if already known (from locating the instance), for rendering. */
|
package/dist/host/client.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { LocateError } from "./locator.js";
|
|
1
|
+
import { LocateError, locationOf, outcomeOfRefusal, refusalOf } from "./locator.js";
|
|
2
2
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
3
3
|
/**
|
|
4
4
|
* Whether a sign-in's `next` is the app's authorize route (P072): the open-redirect guard a
|
|
@@ -100,7 +100,7 @@ export function portholeClient(options) {
|
|
|
100
100
|
return null;
|
|
101
101
|
}
|
|
102
102
|
};
|
|
103
|
-
const
|
|
103
|
+
const askFrames = async (body, signal) => {
|
|
104
104
|
const headers = headersNow();
|
|
105
105
|
headers.set("content-type", "application/json");
|
|
106
106
|
headers.set("accept", "application/json");
|
|
@@ -109,29 +109,58 @@ export function portholeClient(options) {
|
|
|
109
109
|
headers,
|
|
110
110
|
credentials,
|
|
111
111
|
redirect: "error",
|
|
112
|
-
body: JSON.stringify(
|
|
112
|
+
body: JSON.stringify(body),
|
|
113
113
|
...(signal === undefined ? {} : { signal }),
|
|
114
114
|
});
|
|
115
115
|
const data = await answer.json().catch(() => null);
|
|
116
116
|
if (!answer.ok) {
|
|
117
|
-
const
|
|
118
|
-
|
|
119
|
-
if (code === "not-served") {
|
|
117
|
+
const refused = refusalOf(answer, data);
|
|
118
|
+
if (refused.code === "not-served") {
|
|
120
119
|
void refresh();
|
|
121
120
|
}
|
|
122
|
-
throw
|
|
123
|
-
|
|
124
|
-
|
|
121
|
+
throw refused;
|
|
122
|
+
}
|
|
123
|
+
return { status: answer.status, data };
|
|
124
|
+
};
|
|
125
|
+
/** A location as the frame endpoint gave it: its door (P125) passed on, as it came. */
|
|
126
|
+
const located = (status, data) => {
|
|
127
|
+
const { viewer: _viewer, ...location } = locationOf(status, data);
|
|
128
|
+
return location;
|
|
129
|
+
};
|
|
130
|
+
const issue = async (instance, signal) => {
|
|
131
|
+
const key = keyOf(instance);
|
|
132
|
+
const { status, data } = await askFrames({ instance }, signal);
|
|
133
|
+
const location = located(status, data);
|
|
134
|
+
links.set(key, isRecord(data) && typeof data.link === "string" ? data.link : null);
|
|
135
|
+
return location;
|
|
136
|
+
};
|
|
137
|
+
const resolve = async (address, signal) => {
|
|
138
|
+
let answer;
|
|
139
|
+
try {
|
|
140
|
+
answer = await askFrames({ address }, signal);
|
|
141
|
+
}
|
|
142
|
+
catch (error) {
|
|
143
|
+
// Signed out, denied, not found: the host's own answer, before any frame (P125).
|
|
144
|
+
const outcome = outcomeOfRefusal(error);
|
|
145
|
+
if (outcome !== null) {
|
|
146
|
+
return { outcome };
|
|
147
|
+
}
|
|
148
|
+
throw error;
|
|
125
149
|
}
|
|
126
|
-
|
|
127
|
-
|
|
150
|
+
const { status, data } = answer;
|
|
151
|
+
const instance = isRecord(data) ? data.instance : undefined;
|
|
152
|
+
if (!isRecord(instance) ||
|
|
153
|
+
typeof instance.scope !== "string" ||
|
|
154
|
+
!isRecord(instance.document) ||
|
|
155
|
+
typeof instance.document.kind !== "string") {
|
|
156
|
+
throw new LocateError("The app's frame endpoint resolved the address to no instance", status, "bad-location");
|
|
128
157
|
}
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
};
|
|
158
|
+
const found = instance;
|
|
159
|
+
const location = located(status, data);
|
|
160
|
+
// The location is the caller's, for its own first frame only (`oneShot`): never kept here,
|
|
161
|
+
// where another view of the same instance could take it.
|
|
162
|
+
links.set(keyOf(found), isRecord(data) && typeof data.link === "string" ? data.link : null);
|
|
163
|
+
return { instance: found, location };
|
|
135
164
|
};
|
|
136
165
|
let lastHandoff = 0;
|
|
137
166
|
const handoff = async () => {
|
|
@@ -187,6 +216,7 @@ export function portholeClient(options) {
|
|
|
187
216
|
config: (kind) => configOf(kind),
|
|
188
217
|
configFor: (instance) => configOf(options.displays.kindOf(instance)),
|
|
189
218
|
locate: issue,
|
|
219
|
+
resolve,
|
|
190
220
|
link,
|
|
191
221
|
knownLink: (instance) => links.get(keyOf(instance)) ?? null,
|
|
192
222
|
openInTab: (instance) => {
|
|
@@ -1,6 +1,16 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { AdapterConnection, ShellConnection } from "../protocol/adapter.ts";
|
|
3
3
|
import type { HostOptions, PortholeHost } from "./types.ts";
|
|
4
|
+
/** What the host is told of a served display located without its door (P125), once a mount. */
|
|
5
|
+
export declare const NO_DOOR = "A served display needs a door from issue (FrameLocation.door, P125), and this location has none, so no frame was made: upgrade the server (or content Worker) that issues it, and pass the door on from a locator of your own. A clean address is for a tab: to frame what it names, resolve it with client.resolve(address) or <PortholeView address>";
|
|
6
|
+
/**
|
|
7
|
+
* What the host is told when its locator gives a run the location an earlier run had (P125): its
|
|
8
|
+
* tickets were taken by that run, so its door says `blocked: session`. A locator issues anew for
|
|
9
|
+
* every run (a reload, a restart after the content navigated away).
|
|
10
|
+
*/
|
|
11
|
+
export declare const REUSED_LOCATION = "The locator gave this run a location an earlier run of this display already used (P125): its tickets are taken, so its door answers that the link has been used. A locator must issue anew for every run (InstanceLocator.locate is called for each one)";
|
|
12
|
+
/** What the host is told when its platform makes no doors (P125): no served frame is made. */
|
|
13
|
+
export declare const NO_DOOR_PLATFORM = "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
|
|
4
14
|
/** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
|
|
5
15
|
export declare const TRACKED_PER_SECOND = 60;
|
|
6
16
|
/**
|