@botiverse/porthole 0.3.0 → 0.3.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.
- package/README.md +3 -2
- package/dist/check/check.d.ts +18 -1
- package/dist/check/check.js +84 -6
- package/dist/check/drivers.d.ts +25 -6
- package/dist/check/drivers.js +99 -28
- package/dist/check/index.d.ts +2 -2
- package/dist/check/index.js +1 -1
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.d.ts +2 -40
- package/dist/check/page.js +63 -43
- package/dist/conformance/host-kit.d.ts +18 -5
- package/dist/conformance/host-kit.js +38 -21
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/reporter.d.ts +14 -0
- package/dist/conformance/reporter.js +28 -0
- package/dist/host/client.d.ts +33 -15
- package/dist/host/client.js +39 -24
- package/dist/node/index.d.ts +6 -2
- package/dist/node/index.js +53 -8
- package/dist/react/frame.d.ts +13 -5
- package/dist/react/frame.js +67 -27
- package/dist/react/index.d.ts +1 -1
- package/dist/react/view.js +6 -1
- package/dist/server/host.d.ts +5 -3
- package/dist/server/host.js +41 -12
- package/docs/ADOPTING.md +108 -25
- package/docs/DECISIONS.md +134 -0
- package/docs/DESIGN.md +36 -12
- package/examples/app.mjs +23 -17
- package/examples/conformance/playwright.config.mjs +2 -1
- package/examples/conformance/porthole.spec.mjs +2 -1
- package/examples/displays.mjs +2 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +5 -1
- package/src/check/check.ts +116 -8
- package/src/check/drivers.ts +137 -39
- package/src/check/index.ts +8 -1
- package/src/check/instrument.ts +138 -0
- package/src/check/page.ts +94 -68
- package/src/conformance/host-kit.ts +65 -19
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/host/client.ts +65 -34
- package/src/node/index.ts +56 -10
- package/src/react/frame.tsx +89 -33
- package/src/react/index.ts +1 -0
- package/src/react/view.tsx +6 -1
- package/src/server/host.ts +53 -15
package/dist/check/page.d.ts
CHANGED
|
@@ -1,42 +1,5 @@
|
|
|
1
|
-
import type
|
|
2
|
-
|
|
3
|
-
* The check page (P073): runs content in the real sandbox (the core's `createHost`, the config's
|
|
4
|
-
* own CSP) at one width and scheme at a time, and hears what happens inside from a small script
|
|
5
|
-
* the check puts first in the content: what it throws, what the sandbox blocks, what fails to
|
|
6
|
-
* load, what it logs, and its width. Bundled into one script (`@botiverse/porthole/check/page`)
|
|
7
|
-
* that `checkPage` loads into a blank page through its driver.
|
|
8
|
-
*/
|
|
9
|
-
export interface CheckRunSpec {
|
|
10
|
-
readonly config: PortholeConfig;
|
|
11
|
-
readonly content: string;
|
|
12
|
-
readonly widthPx: number;
|
|
13
|
-
readonly heightPx?: number;
|
|
14
|
-
readonly scheme: ColorScheme;
|
|
15
|
-
readonly hostTheme?: Readonly<Record<string, string>>;
|
|
16
|
-
}
|
|
17
|
-
export interface CheckRunData {
|
|
18
|
-
readonly errors: string[];
|
|
19
|
-
readonly blocked: {
|
|
20
|
-
readonly url: string;
|
|
21
|
-
readonly directive: string;
|
|
22
|
-
}[];
|
|
23
|
-
readonly failedLoads: {
|
|
24
|
-
readonly url: string;
|
|
25
|
-
readonly tag: string;
|
|
26
|
-
}[];
|
|
27
|
-
readonly console: {
|
|
28
|
-
readonly level: "error" | "warning";
|
|
29
|
-
readonly text: string;
|
|
30
|
-
}[];
|
|
31
|
-
readonly height: number | null;
|
|
32
|
-
readonly scrollWidth: number | null;
|
|
33
|
-
readonly clientWidth: number | null;
|
|
34
|
-
readonly outcome: string | null;
|
|
35
|
-
}
|
|
36
|
-
/** Put first in the content: it reports to the page that frames it. */
|
|
37
|
-
export declare const INSTRUMENT = "<script>(() => {\n const send = (kind, data) => { try { parent.postMessage({ portholeCheck: kind, data }, \"*\"); } catch (_) {} };\n const text = (value) => { try { return String(value && value.stack ? value.message || value : value); } catch (_) { return \"?\"; } };\n for (const [method, level] of [[\"error\", \"error\"], [\"warn\", \"warning\"]]) {\n const original = console[method];\n console[method] = (...args) => { send(\"console\", { level, text: args.map(text).join(\" \").slice(0, 400) }); return original.apply(console, args); };\n }\n addEventListener(\"error\", (event) => {\n const target = event.target;\n if (target && target !== window && (target.src || target.href)) {\n send(\"load\", { url: String(target.src || target.href).slice(0, 400), tag: String(target.tagName || \"\").toLowerCase() });\n } else if (event.message || event.error) {\n const where = event.lineno ? \" (line \" + event.lineno + \")\" : \"\";\n send(\"error\", (event.error && event.error.message ? (event.error.name || \"Error\") + \": \" + event.error.message : String(event.message)).slice(0, 400) + where);\n }\n }, true);\n addEventListener(\"unhandledrejection\", (event) => send(\"error\", (\"Unhandled rejection: \" + text(event.reason)).slice(0, 400)));\n addEventListener(\"securitypolicyviolation\", (event) => send(\"blocked\", { url: String(event.blockedURI || \"inline\").slice(0, 400), directive: String(event.effectiveDirective) }));\n addEventListener(\"message\", (event) => {\n if (event.source === parent && event.data && event.data.portholeCheck === \"measure\") {\n const root = document.documentElement;\n send(\"measure\", { scrollWidth: Math.max(root.scrollWidth, document.body ? document.body.scrollWidth : 0), clientWidth: root.clientWidth });\n }\n });\n})();</script>";
|
|
38
|
-
/** The content with the instrument first: after a document's <head>, or before a fragment. */
|
|
39
|
-
export declare function instrumented(content: string): string;
|
|
1
|
+
import { type CheckRunData, type CheckRunSpec } from "./instrument.ts";
|
|
2
|
+
export type { CheckCall, CheckRunData, CheckRunSpec } from "./instrument.ts";
|
|
40
3
|
declare const check: {
|
|
41
4
|
/** Shows the content at one width and scheme; returns its run id. */
|
|
42
5
|
run(spec: CheckRunSpec): number;
|
|
@@ -48,4 +11,3 @@ declare const check: {
|
|
|
48
11
|
end(id: number): void;
|
|
49
12
|
};
|
|
50
13
|
export type CheckPageApi = typeof check;
|
|
51
|
-
export {};
|
package/dist/check/page.js
CHANGED
|
@@ -1,45 +1,36 @@
|
|
|
1
|
+
import { capabilitySpec, isCapabilityName, } from "../config/capabilities.js";
|
|
1
2
|
import { createHost } from "../host/create-host.js";
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
})
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
if (head !== null) {
|
|
32
|
-
const at = head.index + head[0].length;
|
|
33
|
-
return `${content.slice(0, at)}${INSTRUMENT}${content.slice(at)}`;
|
|
34
|
-
}
|
|
35
|
-
const html = /<html[^>]*>/iu.exec(content);
|
|
36
|
-
if (html !== null) {
|
|
37
|
-
const at = html.index + html[0].length;
|
|
38
|
-
return `${content.slice(0, at)}<head>${INSTRUMENT}</head>${content.slice(at)}`;
|
|
3
|
+
import { contentLine, instrumented, } from "./instrument.js";
|
|
4
|
+
/**
|
|
5
|
+
* What a host that declines answers each host function with (P074): no prompt sent, no link
|
|
6
|
+
* opened, nothing downloaded or copied; a tool call or a read refused.
|
|
7
|
+
*/
|
|
8
|
+
const DECLINED = {
|
|
9
|
+
sendPrompt: () => false,
|
|
10
|
+
openLink: () => false,
|
|
11
|
+
downloadFile: () => false,
|
|
12
|
+
copyText: () => false,
|
|
13
|
+
setModelContext: () => undefined,
|
|
14
|
+
callTool: () => {
|
|
15
|
+
throw new Error("The host declined the tool call");
|
|
16
|
+
},
|
|
17
|
+
readData: () => {
|
|
18
|
+
throw new Error("The host declined the read");
|
|
19
|
+
},
|
|
20
|
+
};
|
|
21
|
+
/** A handler for each host function the config declares: it notes the call and answers no. */
|
|
22
|
+
function declining(capabilities, calls) {
|
|
23
|
+
const handlers = {};
|
|
24
|
+
for (const name of capabilities) {
|
|
25
|
+
if (isCapabilityName(name) && capabilitySpec(name).served === "handler") {
|
|
26
|
+
const answer = DECLINED[name];
|
|
27
|
+
handlers[name] = () => {
|
|
28
|
+
calls.push({ capability: name, outcome: "answered" });
|
|
29
|
+
return answer();
|
|
30
|
+
};
|
|
31
|
+
}
|
|
39
32
|
}
|
|
40
|
-
return
|
|
41
|
-
? content.replace(/^(\s*<!doctype[^>]*>)/iu, `$1${INSTRUMENT}`)
|
|
42
|
-
: `${INSTRUMENT}${content}`;
|
|
33
|
+
return handlers;
|
|
43
34
|
}
|
|
44
35
|
const runs = new Map();
|
|
45
36
|
let next = 0;
|
|
@@ -55,9 +46,17 @@ addEventListener("message", (event) => {
|
|
|
55
46
|
}
|
|
56
47
|
const said = data.data;
|
|
57
48
|
switch (data.portholeCheck) {
|
|
58
|
-
case "error":
|
|
59
|
-
|
|
49
|
+
case "error": {
|
|
50
|
+
const error = data.data;
|
|
51
|
+
const line = contentLine({
|
|
52
|
+
file: typeof error.file === "string" ? error.file : "",
|
|
53
|
+
line: typeof error.line === "number" ? error.line : 0,
|
|
54
|
+
stack: typeof error.stack === "string" ? error.stack : "",
|
|
55
|
+
}, run.scriptLines);
|
|
56
|
+
const message = typeof error.message === "string" ? error.message : "Error";
|
|
57
|
+
run.data.errors.push(`${message}${line === null ? "" : ` (line ${line})`}`);
|
|
60
58
|
break;
|
|
59
|
+
}
|
|
61
60
|
case "blocked":
|
|
62
61
|
run.data.blocked.push({ url: String(said.url), directive: String(said.directive) });
|
|
63
62
|
break;
|
|
@@ -89,19 +88,31 @@ const check = {
|
|
|
89
88
|
box.style.cssText = `width:${spec.widthPx}px;${spec.heightPx === undefined ? "" : `height:${spec.heightPx}px;`}`;
|
|
90
89
|
document.body.append(box);
|
|
91
90
|
const theme = spec.hostTheme ?? {};
|
|
91
|
+
const calls = [];
|
|
92
92
|
const display = createHost(spec.config, {
|
|
93
93
|
theme: () => theme,
|
|
94
94
|
hostInfo: { name: "porthole-check", version: "1" },
|
|
95
|
+
// Every host function the config declares, answered as a host that declines (P074): a
|
|
96
|
+
// person asked to confirm says no, a handler says no, and each call is noted.
|
|
97
|
+
handlers: declining(Object.keys(spec.config.capabilities), calls),
|
|
98
|
+
confirm: () => Promise.resolve("declined"),
|
|
99
|
+
// A served config's instance, issued by the check's own server on this page's origin.
|
|
100
|
+
locator: {
|
|
101
|
+
locate: async (instance) => (await (await fetch("/issue", { method: "POST", body: JSON.stringify({ instance }) })).json()),
|
|
102
|
+
},
|
|
95
103
|
}).mount(box, {
|
|
96
104
|
displayId: `check-${id}`,
|
|
97
105
|
title: "Check",
|
|
98
106
|
scheme: spec.scheme,
|
|
107
|
+
...(spec.instance === undefined ? {} : { instance: spec.instance }),
|
|
99
108
|
});
|
|
100
109
|
const run = {
|
|
101
110
|
display,
|
|
102
111
|
box,
|
|
112
|
+
scriptLines: spec.scriptLines,
|
|
103
113
|
data: {
|
|
104
114
|
errors: [],
|
|
115
|
+
calls,
|
|
105
116
|
blocked: [],
|
|
106
117
|
failedLoads: [],
|
|
107
118
|
console: [],
|
|
@@ -114,11 +125,20 @@ const check = {
|
|
|
114
125
|
display.on("resize", ({ height }) => {
|
|
115
126
|
run.data.height = height;
|
|
116
127
|
});
|
|
128
|
+
display.on("refused", ({ capability, refusal }) => {
|
|
129
|
+
// "failed": the declining handler's own no, already noted.
|
|
130
|
+
if (refusal !== "failed") {
|
|
131
|
+
calls.push({ capability, outcome: refusal });
|
|
132
|
+
}
|
|
133
|
+
});
|
|
117
134
|
display.on("outcome", (outcome) => {
|
|
118
135
|
run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
|
|
119
136
|
});
|
|
120
137
|
runs.set(id, run);
|
|
121
|
-
|
|
138
|
+
// A stored page comes from the check's server; a shell (served or opaque) gets the content.
|
|
139
|
+
if (spec.instance?.document.kind !== "artifact") {
|
|
140
|
+
display.on("initialized", () => display.setContent(instrumented(spec.content)));
|
|
141
|
+
}
|
|
122
142
|
return id;
|
|
123
143
|
},
|
|
124
144
|
/** Asks the frame for its width; resolves when it answers (or after a second). */
|
|
@@ -46,8 +46,12 @@ export interface HostConformanceOptions {
|
|
|
46
46
|
readonly config?: (instance: InstanceRef) => PortholeConfig;
|
|
47
47
|
/** The app's display kinds (`defineDisplays`), in place of `config`. */
|
|
48
48
|
readonly displays?: Displays;
|
|
49
|
-
/**
|
|
50
|
-
|
|
49
|
+
/**
|
|
50
|
+
* The content source `displays` serve from (`http://*.content.localhost:8790`). A function is
|
|
51
|
+
* asked when a case needs it (P074): a test server's port that isn't known when the spec file
|
|
52
|
+
* loads.
|
|
53
|
+
*/
|
|
54
|
+
readonly contentSource?: string | (() => string);
|
|
51
55
|
/**
|
|
52
56
|
* The instances the served cases ask for, each for the scope a case names (may be async: a
|
|
53
57
|
* page published on demand, `onDemand`). Give what the app serves; the cases for the rest are
|
|
@@ -117,9 +121,18 @@ export interface ConformanceProject {
|
|
|
117
121
|
* preferences its WebRTC probe needs (loopback ICE). Pass `devices` from `@playwright/test`
|
|
118
122
|
* (P071).
|
|
119
123
|
*/
|
|
120
|
-
export
|
|
121
|
-
readonly engines?: readonly
|
|
122
|
-
|
|
124
|
+
export interface ConformanceProjectsOptions {
|
|
125
|
+
readonly engines?: readonly ConformanceProject["name"][];
|
|
126
|
+
/** Added to every project's `use` (a trace setting, `ignoreHTTPSErrors`, a `baseURL`). */
|
|
127
|
+
readonly use?: Readonly<Record<string, unknown>>;
|
|
128
|
+
/**
|
|
129
|
+
* Each engine's launch options, merged with Porthole's own (P074): a system browser's
|
|
130
|
+
* `executablePath` and `args` (`{ chromium: { executablePath: "/usr/bin/chromium" } }`, on a box
|
|
131
|
+
* Playwright has no Chromium build for). Firefox's preferences add to the ones its probes need.
|
|
132
|
+
*/
|
|
133
|
+
readonly launchOptions?: Partial<Readonly<Record<ConformanceProject["name"], Readonly<Record<string, unknown>>>>>;
|
|
134
|
+
}
|
|
135
|
+
export declare function conformanceProjects(devices: Readonly<Record<string, Record<string, unknown>>>, options?: ConformanceProjectsOptions): ConformanceProject[];
|
|
123
136
|
/**
|
|
124
137
|
* Registers the leak and served suites against an app's real page, in a spec file of the app's
|
|
125
138
|
* (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
|
|
@@ -72,7 +72,7 @@ export function hostConformance(options) {
|
|
|
72
72
|
const { displays, contentSource } = options;
|
|
73
73
|
const configOf = options.config ??
|
|
74
74
|
(displays !== undefined && contentSource !== undefined
|
|
75
|
-
? (instance) => displays.configFor(instance, contentSource)
|
|
75
|
+
? (instance) => displays.configFor(instance, typeof contentSource === "function" ? contentSource() : contentSource)
|
|
76
76
|
: () => {
|
|
77
77
|
throw new TypeError("hostConformance needs config, or displays with contentSource");
|
|
78
78
|
});
|
|
@@ -345,30 +345,47 @@ export function onDemand(make) {
|
|
|
345
345
|
return found;
|
|
346
346
|
};
|
|
347
347
|
}
|
|
348
|
-
|
|
349
|
-
* The Playwright projects to run the suite on: Chromium, WebKit and Firefox, Firefox with the
|
|
350
|
-
* preferences its WebRTC probe needs (loopback ICE). Pass `devices` from `@playwright/test`
|
|
351
|
-
* (P071).
|
|
352
|
-
*/
|
|
348
|
+
const recordOf = (value) => value !== null && typeof value === "object" ? value : {};
|
|
353
349
|
export function conformanceProjects(devices, options = {}) {
|
|
354
|
-
const
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
350
|
+
const DEVICE = {
|
|
351
|
+
chromium: "Desktop Chrome",
|
|
352
|
+
webkit: "Desktop Safari",
|
|
353
|
+
firefox: "Desktop Firefox",
|
|
354
|
+
};
|
|
355
|
+
/** Porthole's own launch options: Firefox's WebRTC probe needs loopback ICE. */
|
|
356
|
+
const OWN = {
|
|
357
|
+
chromium: {},
|
|
358
|
+
webkit: {},
|
|
359
|
+
firefox: {
|
|
360
|
+
firefoxUserPrefs: {
|
|
361
|
+
"media.peerconnection.ice.loopback": true,
|
|
362
|
+
"media.peerconnection.ice.obfuscate_host_addresses": false,
|
|
367
363
|
},
|
|
368
364
|
},
|
|
369
|
-
|
|
365
|
+
};
|
|
370
366
|
const engines = options.engines ?? ["chromium", "webkit", "firefox"];
|
|
371
|
-
return
|
|
367
|
+
return ["chromium", "webkit", "firefox"]
|
|
368
|
+
.filter((name) => engines.includes(name))
|
|
369
|
+
.map((name) => {
|
|
370
|
+
const given = { ...recordOf(options.use?.launchOptions), ...options.launchOptions?.[name] };
|
|
371
|
+
const prefs = {
|
|
372
|
+
...recordOf(OWN[name].firefoxUserPrefs),
|
|
373
|
+
...recordOf(given.firefoxUserPrefs),
|
|
374
|
+
};
|
|
375
|
+
const launchOptions = {
|
|
376
|
+
...OWN[name],
|
|
377
|
+
...given,
|
|
378
|
+
...(Object.keys(prefs).length === 0 ? {} : { firefoxUserPrefs: prefs }),
|
|
379
|
+
};
|
|
380
|
+
return {
|
|
381
|
+
name,
|
|
382
|
+
use: {
|
|
383
|
+
...devices[DEVICE[name]],
|
|
384
|
+
...options.use,
|
|
385
|
+
...(Object.keys(launchOptions).length === 0 ? {} : { launchOptions }),
|
|
386
|
+
},
|
|
387
|
+
};
|
|
388
|
+
});
|
|
372
389
|
}
|
|
373
390
|
/**
|
|
374
391
|
* Registers the leak and served suites against an app's real page, in a spec file of the app's
|
|
@@ -102,4 +102,4 @@ export { defineLeakSuite, leakTests, PROBES, type ConformanceFixtures, type Conf
|
|
|
102
102
|
export { httpOracle, settle, udpOracle, type HttpOracle, type UdpOracle } from "./oracles.ts";
|
|
103
103
|
export { defineServedSuite, servedTests, type ServedConformanceHost, type ServedDisplay, type ServedSuiteOptions, } from "./served.ts";
|
|
104
104
|
export { entryTests, type EntryConformanceHost, type EntrySuiteOptions } from "./entry.ts";
|
|
105
|
-
export { conformancePage, conformanceProjects, defineHostConformance, harnessScript, hostConformance, onDemand, type ConformanceProject, type HostConformance, type HostConformanceOptions, } from "./host-kit.ts";
|
|
105
|
+
export { conformancePage, conformanceProjects, defineHostConformance, harnessScript, hostConformance, onDemand, type ConformanceProject, type ConformanceProjectsOptions, type HostConformance, type HostConformanceOptions, } from "./host-kit.ts";
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { FullResult, Reporter, TestCase, TestResult } from "@playwright/test/reporter";
|
|
2
|
+
/**
|
|
3
|
+
* A Playwright reporter that says why each conformance case was skipped (P074): the list and line
|
|
4
|
+
* reporters show a skipped case as "-" with no reason, and an inapplicable probe ("the page's own
|
|
5
|
+
* CSP, which an opaque frame inherits, blocks … (connect-src)") is a fact worth reading.
|
|
6
|
+
*
|
|
7
|
+
* reporter: [["list"], ["@botiverse/porthole/conformance/reporter"]],
|
|
8
|
+
*/
|
|
9
|
+
export default class SkipReasons implements Reporter {
|
|
10
|
+
#private;
|
|
11
|
+
printsToStdio(): boolean;
|
|
12
|
+
onTestEnd(test: TestCase, result: TestResult): void;
|
|
13
|
+
onEnd(_result: FullResult): void;
|
|
14
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A Playwright reporter that says why each conformance case was skipped (P074): the list and line
|
|
3
|
+
* reporters show a skipped case as "-" with no reason, and an inapplicable probe ("the page's own
|
|
4
|
+
* CSP, which an opaque frame inherits, blocks … (connect-src)") is a fact worth reading.
|
|
5
|
+
*
|
|
6
|
+
* reporter: [["list"], ["@botiverse/porthole/conformance/reporter"]],
|
|
7
|
+
*/
|
|
8
|
+
export default class SkipReasons {
|
|
9
|
+
#skipped = new Map();
|
|
10
|
+
printsToStdio() {
|
|
11
|
+
return true;
|
|
12
|
+
}
|
|
13
|
+
onTestEnd(test, result) {
|
|
14
|
+
if (result.status !== "skipped") {
|
|
15
|
+
return;
|
|
16
|
+
}
|
|
17
|
+
const reason = [...result.annotations, ...test.annotations].find((each) => each.type === "skip" && each.description !== undefined && each.description !== "")?.description ?? "skipped";
|
|
18
|
+
const title = test.title.length > 90 ? `${test.title.slice(0, 89)}…` : test.title;
|
|
19
|
+
this.#skipped.set(`${title}\u0000${reason}`, `${title}: ${reason}`);
|
|
20
|
+
}
|
|
21
|
+
onEnd(_result) {
|
|
22
|
+
if (this.#skipped.size === 0) {
|
|
23
|
+
return;
|
|
24
|
+
}
|
|
25
|
+
const lines = [...this.#skipped.values()].toSorted();
|
|
26
|
+
process.stdout.write(`\nSkipped (${lines.length}), and why:\n${lines.map((each) => ` - ${each}`).join("\n")}\n`);
|
|
27
|
+
}
|
|
28
|
+
}
|
package/dist/host/client.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { Displays } from "../displays/displays.ts";
|
|
3
|
-
import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
import type { FrameLocation, InstanceLocator, InstanceRef } from "../isolation/types.ts";
|
|
4
4
|
import type { FrameOutcome } from "./types.ts";
|
|
5
5
|
/**
|
|
6
6
|
* The client half of the host kit (P072): what the app's page needs from its server's Porthole
|
|
@@ -39,42 +39,60 @@ export interface PortholeClientOptions<N extends string> {
|
|
|
39
39
|
readonly handoff?: boolean;
|
|
40
40
|
readonly fetch?: typeof fetch;
|
|
41
41
|
}
|
|
42
|
+
/**
|
|
43
|
+
* Every function is declared `this: void` (P074): each may be passed bare
|
|
44
|
+
* (`useSyncExternalStore(porthole.subscribe, porthole.meta)`), and none reads `this`.
|
|
45
|
+
*/
|
|
42
46
|
export interface PortholeClient<N extends string = string> extends InstanceLocator {
|
|
43
47
|
readonly displays: Displays<N>;
|
|
48
|
+
/** Locates an instance's frame through `POST <base>/frames` (`InstanceLocator`). */
|
|
49
|
+
locate(this: void, instance: InstanceRef, signal?: AbortSignal): Promise<FrameLocation>;
|
|
44
50
|
/** The meta as last fetched, or null before it is known. */
|
|
45
|
-
meta(): ContentClientMeta | null;
|
|
51
|
+
meta(this: void): ContentClientMeta | null;
|
|
46
52
|
/** Called when the meta changes (frames served or not). */
|
|
47
|
-
subscribe(listener: () => void): () => void;
|
|
53
|
+
subscribe(this: void, listener: () => void): () => void;
|
|
48
54
|
/** Fetches the meta again. */
|
|
49
|
-
refresh(): Promise<ContentClientMeta | null>;
|
|
55
|
+
refresh(this: void): Promise<ContentClientMeta | null>;
|
|
50
56
|
/**
|
|
51
57
|
* The config a kind shows under now: served while frames are served, else opaque (a url kind:
|
|
52
58
|
* null). Null until the meta is known, so a frame never starts opaque and then restarts served.
|
|
53
59
|
*/
|
|
54
|
-
config(kind: N): PortholeConfig | null;
|
|
60
|
+
config(this: void, kind: N): PortholeConfig | null;
|
|
55
61
|
/** The same, for an instance's kind. */
|
|
56
|
-
configFor(instance: InstanceRef): PortholeConfig | null;
|
|
62
|
+
configFor(this: void, instance: InstanceRef): PortholeConfig | null;
|
|
57
63
|
/** An instance's clean address (`entry.pathOf` on the server), or null. */
|
|
58
|
-
link(instance: InstanceRef): Promise<string | null>;
|
|
64
|
+
link(this: void, instance: InstanceRef): Promise<string | null>;
|
|
59
65
|
/** The clean address if already known (from locating the instance), for rendering. */
|
|
60
|
-
knownLink(instance: InstanceRef): string | null;
|
|
66
|
+
knownLink(this: void, instance: InstanceRef): string | null;
|
|
61
67
|
/**
|
|
62
68
|
* Opens an instance's clean address in a new tab: call it in the click (the tab opens at once,
|
|
63
69
|
* then goes to the address).
|
|
64
70
|
*/
|
|
65
|
-
openInTab(instance: InstanceRef): void;
|
|
71
|
+
openInTab(this: void, instance: InstanceRef): void;
|
|
66
72
|
/** Hands the signed-in viewer to the authorize route (`entry.handoff`); true if it took. */
|
|
67
|
-
handoff(): Promise<boolean>;
|
|
68
|
-
/**
|
|
69
|
-
|
|
73
|
+
handoff(this: void): Promise<boolean>;
|
|
74
|
+
/**
|
|
75
|
+
* `next` if it is this server's authorize route (after a sign-in), or with `{ app: true }` any
|
|
76
|
+
* address on the app's own origin; else null (`entryTarget`).
|
|
77
|
+
*/
|
|
78
|
+
entryTarget(this: void, next: unknown, options?: {
|
|
79
|
+
readonly app?: boolean;
|
|
80
|
+
}): string | null;
|
|
70
81
|
/** Stops refreshing the handoff. */
|
|
71
|
-
close(): void;
|
|
82
|
+
close(this: void): void;
|
|
72
83
|
}
|
|
73
84
|
/**
|
|
74
85
|
* Whether a sign-in's `next` is the app's authorize route (P072): the open-redirect guard a
|
|
75
|
-
* single-page app runs before going on to it. Null for anything else
|
|
86
|
+
* single-page app runs before going on to it. Null for anything else; with `{ app: true }`, also
|
|
87
|
+
* any path or address on the app's own origin (P074), so one check serves a sign-in that comes
|
|
88
|
+
* back to redirect entry or to the app's own pages. Never another origin.
|
|
89
|
+
*
|
|
90
|
+
* The authorize route is `<first app origin><prefix>/authorize` unless the server names another
|
|
91
|
+
* (`entry.authorizeUrl`): `https://app.example.com/porthole/authorize` by default.
|
|
76
92
|
*/
|
|
77
|
-
export declare function entryTarget(next: unknown, authorizeUrl: string
|
|
93
|
+
export declare function entryTarget(next: unknown, authorizeUrl: string, options?: {
|
|
94
|
+
readonly app?: boolean;
|
|
95
|
+
}): string | null;
|
|
78
96
|
export declare function portholeClient<N extends string>(options: PortholeClientOptions<N>): PortholeClient<N>;
|
|
79
97
|
/** What a frame that showed nothing should offer the person, by its outcome (P072). */
|
|
80
98
|
export interface FrameFallback {
|
package/dist/host/client.js
CHANGED
|
@@ -2,9 +2,14 @@ import { LocateError } 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
|
|
5
|
-
* single-page app runs before going on to it. Null for anything else
|
|
5
|
+
* single-page app runs before going on to it. Null for anything else; with `{ app: true }`, also
|
|
6
|
+
* any path or address on the app's own origin (P074), so one check serves a sign-in that comes
|
|
7
|
+
* back to redirect entry or to the app's own pages. Never another origin.
|
|
8
|
+
*
|
|
9
|
+
* The authorize route is `<first app origin><prefix>/authorize` unless the server names another
|
|
10
|
+
* (`entry.authorizeUrl`): `https://app.example.com/porthole/authorize` by default.
|
|
6
11
|
*/
|
|
7
|
-
export function entryTarget(next, authorizeUrl) {
|
|
12
|
+
export function entryTarget(next, authorizeUrl, options = {}) {
|
|
8
13
|
if (typeof next !== "string" || next.length > 8_192) {
|
|
9
14
|
return null;
|
|
10
15
|
}
|
|
@@ -17,10 +22,17 @@ export function entryTarget(next, authorizeUrl) {
|
|
|
17
22
|
catch {
|
|
18
23
|
return null;
|
|
19
24
|
}
|
|
20
|
-
|
|
25
|
+
if (target.origin === route.origin &&
|
|
21
26
|
target.pathname === route.pathname &&
|
|
22
27
|
target.hash === "" &&
|
|
23
|
-
target.searchParams.has("state")
|
|
28
|
+
target.searchParams.has("state")) {
|
|
29
|
+
return target.href;
|
|
30
|
+
}
|
|
31
|
+
// An app path: one leading slash, no backslash (`//evil.example` and `/\evil.example` are
|
|
32
|
+
// other sites to a browser), and still the app's origin once resolved.
|
|
33
|
+
const path = /^\/(?![/\\])/u.test(next) && !next.includes("\\");
|
|
34
|
+
const absolute = /^https?:\/\//iu.test(next);
|
|
35
|
+
return options.app === true && (path || absolute) && target.origin === route.origin
|
|
24
36
|
? target.href
|
|
25
37
|
: null;
|
|
26
38
|
}
|
|
@@ -150,31 +162,34 @@ export function portholeClient(options) {
|
|
|
150
162
|
window.addEventListener("focus", fresh);
|
|
151
163
|
document.addEventListener("visibilitychange", fresh);
|
|
152
164
|
}
|
|
165
|
+
const link = async (instance) => {
|
|
166
|
+
const key = keyOf(instance);
|
|
167
|
+
if (!links.has(key)) {
|
|
168
|
+
try {
|
|
169
|
+
await issue(instance);
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
return null;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
return links.get(key) ?? null;
|
|
176
|
+
};
|
|
153
177
|
return {
|
|
154
178
|
displays: options.displays,
|
|
155
179
|
meta: () => meta,
|
|
156
|
-
subscribe(listener) {
|
|
180
|
+
subscribe: (listener) => {
|
|
157
181
|
listeners.add(listener);
|
|
158
|
-
return () =>
|
|
182
|
+
return () => {
|
|
183
|
+
listeners.delete(listener);
|
|
184
|
+
};
|
|
159
185
|
},
|
|
160
186
|
refresh,
|
|
161
187
|
config: (kind) => configOf(kind),
|
|
162
188
|
configFor: (instance) => configOf(options.displays.kindOf(instance)),
|
|
163
189
|
locate: issue,
|
|
164
|
-
|
|
165
|
-
const key = keyOf(instance);
|
|
166
|
-
if (!links.has(key)) {
|
|
167
|
-
try {
|
|
168
|
-
await issue(instance);
|
|
169
|
-
}
|
|
170
|
-
catch {
|
|
171
|
-
return null;
|
|
172
|
-
}
|
|
173
|
-
}
|
|
174
|
-
return links.get(key) ?? null;
|
|
175
|
-
},
|
|
190
|
+
link,
|
|
176
191
|
knownLink: (instance) => links.get(keyOf(instance)) ?? null,
|
|
177
|
-
openInTab(instance) {
|
|
192
|
+
openInTab: (instance) => {
|
|
178
193
|
// Opened inside the click (a popup blocker lets it), then sent to the address.
|
|
179
194
|
const tab = typeof window === "undefined" ? null : window.open("about:blank", "_blank");
|
|
180
195
|
if (tab === null) {
|
|
@@ -182,18 +197,18 @@ export function portholeClient(options) {
|
|
|
182
197
|
}
|
|
183
198
|
tab.opener = null;
|
|
184
199
|
void (async () => {
|
|
185
|
-
const
|
|
186
|
-
if (
|
|
200
|
+
const found = await link(instance);
|
|
201
|
+
if (found === null) {
|
|
187
202
|
tab.close();
|
|
188
203
|
}
|
|
189
204
|
else {
|
|
190
|
-
tab.location.href =
|
|
205
|
+
tab.location.href = found;
|
|
191
206
|
}
|
|
192
207
|
})();
|
|
193
208
|
},
|
|
194
209
|
handoff,
|
|
195
|
-
entryTarget: (next) => entryTarget(next, url("/authorize")),
|
|
196
|
-
close() {
|
|
210
|
+
entryTarget: (next, given) => entryTarget(next, url("/authorize"), given),
|
|
211
|
+
close: () => {
|
|
197
212
|
if (watching) {
|
|
198
213
|
window.removeEventListener("focus", fresh);
|
|
199
214
|
document.removeEventListener("visibilitychange", fresh);
|
package/dist/node/index.d.ts
CHANGED
|
@@ -47,8 +47,12 @@ export declare function nodeHost<V>(content: ContentHost<V>, app: NodeHostOption
|
|
|
47
47
|
*/
|
|
48
48
|
export declare function nodeProbe(): HealthProbe;
|
|
49
49
|
export interface NodeServerOptions {
|
|
50
|
-
/**
|
|
51
|
-
|
|
50
|
+
/**
|
|
51
|
+
* The content host, or a function giving it when it exists: a host made after the server listens
|
|
52
|
+
* (its content domain names the port `listen(0)` chose, P074). Until it gives one, every request
|
|
53
|
+
* is the app's; the health gate starts when it first does.
|
|
54
|
+
*/
|
|
55
|
+
readonly content: ContentHost<unknown> | (() => ContentHost<unknown> | null);
|
|
52
56
|
/**
|
|
53
57
|
* The app, fetch-style (Hono's `app.fetch`, or the app's own handler): every request that
|
|
54
58
|
* isn't the content domain's. Or `request`, a Node listener (Express).
|