@botiverse/porthole 0.3.0 → 0.3.2
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 +20 -3
- package/dist/check/check.js +88 -25
- 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/harness-source.d.ts +2 -0
- package/dist/conformance/harness-source.js +2 -0
- package/dist/conformance/host-kit.d.ts +20 -7
- package/dist/conformance/host-kit.js +42 -48
- 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 +115 -26
- package/docs/DECISIONS.md +167 -0
- package/docs/DESIGN.md +38 -13
- 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 +9 -3
- package/src/check/check.ts +122 -25
- 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-source.ts +4 -3
- package/src/check/page.ts +94 -68
- package/src/conformance/harness-source.ts +23 -0
- package/src/conformance/host-kit.ts +69 -46
- 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/conformance/harness.js +0 -1662
package/src/check/drivers.ts
CHANGED
|
@@ -5,22 +5,78 @@ import type { CheckDriver, CheckSession } from "./check.ts";
|
|
|
5
5
|
* Drivers for `checkPage` (P073): Playwright's browser on Node, or any Chrome DevTools Protocol
|
|
6
6
|
* session (Puppeteer's `page.createCDPSession()`, `@cloudflare/puppeteer` on Cloudflare Browser
|
|
7
7
|
* Rendering from a Worker).
|
|
8
|
+
*
|
|
9
|
+
* A driver answers two names no network has itself: the check page's origin (a host's), and a
|
|
10
|
+
* content domain, where a served config's content runs on an origin of its own as people's
|
|
11
|
+
* browsers run it (P074).
|
|
8
12
|
*/
|
|
9
13
|
|
|
14
|
+
/** Where the check page is served from. */
|
|
15
|
+
export const CHECK_ORIGIN = "https://porthole-check.invalid";
|
|
16
|
+
/** The content domain a served config's content runs under in the check: another site. */
|
|
17
|
+
export const CHECK_CONTENT_DOMAIN = "porthole-check-content.invalid";
|
|
18
|
+
|
|
19
|
+
const CHECK_HOST = new URL(CHECK_ORIGIN).hostname;
|
|
20
|
+
/** Whether the driver answers a URL itself. */
|
|
21
|
+
const answered = (url: URL): boolean =>
|
|
22
|
+
url.hostname === CHECK_HOST || url.hostname.endsWith(`.${CHECK_CONTENT_DOMAIN}`);
|
|
23
|
+
|
|
24
|
+
type Handler = (request: Request) => Promise<Response>;
|
|
25
|
+
|
|
26
|
+
/** A page that answers the check's own names: `/` the given document, the rest 404. */
|
|
27
|
+
const pageOnly =
|
|
28
|
+
(html: string): Handler =>
|
|
29
|
+
(request) =>
|
|
30
|
+
Promise.resolve(
|
|
31
|
+
new URL(request.url).hostname === CHECK_HOST && new URL(request.url).pathname === "/"
|
|
32
|
+
? new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } })
|
|
33
|
+
: new Response("not found", { status: 404 }),
|
|
34
|
+
);
|
|
35
|
+
|
|
10
36
|
/** Checks in a page of a Playwright browser (`chromium.launch()`), one page per check. */
|
|
11
37
|
export function playwrightDriver(browser: Browser): CheckDriver {
|
|
12
38
|
return {
|
|
13
39
|
async open(): Promise<CheckSession> {
|
|
14
40
|
const page = await browser.newPage();
|
|
15
|
-
let
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
41
|
+
let handler: Handler = pageOnly("");
|
|
42
|
+
await page.route(answered, async (route) => {
|
|
43
|
+
const asked = route.request();
|
|
44
|
+
const headers = Object.entries(await asked.allHeaders()).filter(
|
|
45
|
+
([name]) => !name.startsWith(":"),
|
|
46
|
+
);
|
|
47
|
+
const method = asked.method();
|
|
48
|
+
const body = method === "GET" || method === "HEAD" ? null : asked.postDataBuffer();
|
|
49
|
+
const answer = await handler(
|
|
50
|
+
new Request(asked.url(), {
|
|
51
|
+
method,
|
|
52
|
+
headers,
|
|
53
|
+
...(body === null ? {} : { body: new Uint8Array(body) }),
|
|
54
|
+
}),
|
|
55
|
+
);
|
|
56
|
+
const out: Record<string, string> = {};
|
|
57
|
+
for (const [name, value] of answer.headers) {
|
|
58
|
+
if (name !== "set-cookie") {
|
|
59
|
+
out[name] = value;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
const cookies = answer.headers.getSetCookie();
|
|
63
|
+
if (cookies.length > 0) {
|
|
64
|
+
out["set-cookie"] = cookies.join("\n");
|
|
65
|
+
}
|
|
66
|
+
await route.fulfill({
|
|
67
|
+
status: answer.status,
|
|
68
|
+
headers: out,
|
|
69
|
+
body: Buffer.from(await answer.arrayBuffer()),
|
|
70
|
+
});
|
|
71
|
+
});
|
|
20
72
|
return {
|
|
21
73
|
setViewport: (width, height) => page.setViewportSize({ width, height }),
|
|
22
74
|
async load(document) {
|
|
23
|
-
|
|
75
|
+
handler = pageOnly(document);
|
|
76
|
+
await page.goto(`${CHECK_ORIGIN}/`, { waitUntil: "load" });
|
|
77
|
+
},
|
|
78
|
+
async serve(given) {
|
|
79
|
+
handler = given;
|
|
24
80
|
await page.goto(`${CHECK_ORIGIN}/`, { waitUntil: "load" });
|
|
25
81
|
},
|
|
26
82
|
evaluate: (expression) => page.evaluate(expression),
|
|
@@ -31,21 +87,30 @@ export function playwrightDriver(browser: Browser): CheckDriver {
|
|
|
31
87
|
};
|
|
32
88
|
}
|
|
33
89
|
|
|
34
|
-
/**
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
90
|
+
/**
|
|
91
|
+
* A Chrome DevTools Protocol session: its commands and its events. The least the driver uses, so
|
|
92
|
+
* Puppeteer's `CDPSession` (`@cloudflare/puppeteer`'s too) and Playwright's fit as they are, with
|
|
93
|
+
* no cast (P074).
|
|
94
|
+
*/
|
|
38
95
|
export interface CdpSession {
|
|
39
96
|
send(method: string, params?: Record<string, unknown>): Promise<unknown>;
|
|
40
|
-
on(
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
97
|
+
on(event: "Fetch.requestPaused", listener: (params: PausedRequest) => void): unknown;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** What CDP says of a request it paused. */
|
|
101
|
+
interface PausedRequest {
|
|
102
|
+
readonly requestId: string;
|
|
103
|
+
readonly request?: {
|
|
104
|
+
readonly url: string;
|
|
105
|
+
readonly method: string;
|
|
106
|
+
readonly headers?: Readonly<Record<string, string>>;
|
|
107
|
+
readonly postData?: string;
|
|
108
|
+
};
|
|
44
109
|
}
|
|
45
110
|
|
|
46
|
-
const
|
|
111
|
+
const bytesToBase64 = (bytes: Uint8Array): string => {
|
|
47
112
|
let binary = "";
|
|
48
|
-
for (const byte of
|
|
113
|
+
for (const byte of bytes) {
|
|
49
114
|
binary += String.fromCharCode(byte);
|
|
50
115
|
}
|
|
51
116
|
return btoa(binary);
|
|
@@ -65,16 +130,42 @@ export function cdpDriver(open: () => Promise<CdpSession>): CheckDriver {
|
|
|
65
130
|
const session = await open();
|
|
66
131
|
await session.send("Page.enable");
|
|
67
132
|
await session.send("Runtime.enable");
|
|
68
|
-
let
|
|
69
|
-
// The check
|
|
70
|
-
await session.send("Fetch.enable", {
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
133
|
+
let handler: Handler = pageOnly("");
|
|
134
|
+
// The check's own names are answered here; everything else goes on.
|
|
135
|
+
await session.send("Fetch.enable", {
|
|
136
|
+
patterns: [
|
|
137
|
+
{ urlPattern: `${CHECK_ORIGIN}/*` },
|
|
138
|
+
{ urlPattern: `https://*.${CHECK_CONTENT_DOMAIN}/*` },
|
|
139
|
+
],
|
|
140
|
+
});
|
|
141
|
+
session.on("Fetch.requestPaused", (event) => {
|
|
142
|
+
void (async () => {
|
|
143
|
+
const asked = event.request;
|
|
144
|
+
if (asked === undefined || !answered(new URL(asked.url))) {
|
|
145
|
+
await session.send("Fetch.continueRequest", { requestId: event.requestId });
|
|
146
|
+
return;
|
|
147
|
+
}
|
|
148
|
+
const body =
|
|
149
|
+
asked.method === "GET" || asked.method === "HEAD" ? null : (asked.postData ?? null);
|
|
150
|
+
const answer = await handler(
|
|
151
|
+
new Request(asked.url, {
|
|
152
|
+
method: asked.method,
|
|
153
|
+
headers: Object.entries(asked.headers ?? {}),
|
|
154
|
+
...(body === null ? {} : { body }),
|
|
155
|
+
}),
|
|
156
|
+
);
|
|
157
|
+
await session.send("Fetch.fulfillRequest", {
|
|
158
|
+
requestId: event.requestId,
|
|
159
|
+
responseCode: answer.status,
|
|
160
|
+
responseHeaders: [
|
|
161
|
+
...[...answer.headers]
|
|
162
|
+
.filter(([name]) => name !== "set-cookie")
|
|
163
|
+
.map(([name, value]) => ({ name, value })),
|
|
164
|
+
...answer.headers.getSetCookie().map((value) => ({ name: "set-cookie", value })),
|
|
165
|
+
],
|
|
166
|
+
body: bytesToBase64(new Uint8Array(await answer.arrayBuffer())),
|
|
167
|
+
});
|
|
168
|
+
})();
|
|
78
169
|
});
|
|
79
170
|
const evaluate = async <T>(expression: string): Promise<T> => {
|
|
80
171
|
const answer = (await session.send("Runtime.evaluate", {
|
|
@@ -94,6 +185,20 @@ export function cdpDriver(open: () => Promise<CdpSession>): CheckDriver {
|
|
|
94
185
|
}
|
|
95
186
|
return answer.result?.value as T;
|
|
96
187
|
};
|
|
188
|
+
const goto = async () => {
|
|
189
|
+
await session.send("Page.navigate", { url: `${CHECK_ORIGIN}/` });
|
|
190
|
+
// The page's script runs when it loads: wait until it says so.
|
|
191
|
+
for (let tries = 0; tries < 100; tries += 1) {
|
|
192
|
+
const ready = await evaluate<boolean>(
|
|
193
|
+
'document.documentElement?.dataset.portholeCheck === "ready"',
|
|
194
|
+
).catch(() => false);
|
|
195
|
+
if (ready) {
|
|
196
|
+
return;
|
|
197
|
+
}
|
|
198
|
+
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
199
|
+
}
|
|
200
|
+
throw new Error("The check page didn't start");
|
|
201
|
+
};
|
|
97
202
|
return {
|
|
98
203
|
async setViewport(width, height) {
|
|
99
204
|
await session.send("Emulation.setDeviceMetricsOverride", {
|
|
@@ -104,19 +209,12 @@ export function cdpDriver(open: () => Promise<CdpSession>): CheckDriver {
|
|
|
104
209
|
});
|
|
105
210
|
},
|
|
106
211
|
async load(document) {
|
|
107
|
-
|
|
108
|
-
await
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
).catch(() => false);
|
|
114
|
-
if (ready) {
|
|
115
|
-
return;
|
|
116
|
-
}
|
|
117
|
-
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
118
|
-
}
|
|
119
|
-
throw new Error("The check page didn't start");
|
|
212
|
+
handler = pageOnly(document);
|
|
213
|
+
await goto();
|
|
214
|
+
},
|
|
215
|
+
async serve(given) {
|
|
216
|
+
handler = given;
|
|
217
|
+
await goto();
|
|
120
218
|
},
|
|
121
219
|
evaluate,
|
|
122
220
|
async screenshot(selector) {
|
package/src/check/index.ts
CHANGED
|
@@ -5,11 +5,18 @@
|
|
|
5
5
|
*/
|
|
6
6
|
export {
|
|
7
7
|
checkPage,
|
|
8
|
+
type CheckCall,
|
|
8
9
|
type CheckDriver,
|
|
9
10
|
type CheckOptions,
|
|
10
11
|
type CheckReport,
|
|
11
12
|
type CheckRun,
|
|
12
13
|
type CheckSession,
|
|
13
14
|
} from "./check.ts";
|
|
14
|
-
export {
|
|
15
|
+
export {
|
|
16
|
+
CHECK_CONTENT_DOMAIN,
|
|
17
|
+
CHECK_ORIGIN,
|
|
18
|
+
cdpDriver,
|
|
19
|
+
playwrightDriver,
|
|
20
|
+
type CdpSession,
|
|
21
|
+
} from "./drivers.ts";
|
|
15
22
|
export { lintContent, type Finding, type LintRule } from "./lint.ts";
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import type { InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* What the check puts in the content it runs (P073, P074): a small script first that reports
|
|
6
|
+
* what happens inside to the page that frames it, and a name on each inline script so an error
|
|
7
|
+
* says the line in the content as written. Pure: the check (any runtime) and its page both use it.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
export interface CheckRunSpec {
|
|
11
|
+
readonly config: PortholeConfig;
|
|
12
|
+
readonly content: string;
|
|
13
|
+
/** Where each inline script's text starts in the content as written (file lines), by index. */
|
|
14
|
+
readonly scriptLines: readonly number[];
|
|
15
|
+
/** A served config's instance (located through the check's own server), else opaque. */
|
|
16
|
+
readonly instance?: InstanceRef;
|
|
17
|
+
readonly widthPx: number;
|
|
18
|
+
readonly heightPx?: number;
|
|
19
|
+
readonly scheme: ColorScheme;
|
|
20
|
+
readonly hostTheme?: Readonly<Record<string, string>>;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* A host function the content called (P074): `answered` where the call reached the check's stub
|
|
25
|
+
* (which answers no, as a declining host would), else the refusal a host's gates gave it
|
|
26
|
+
* (`no-user-activation` for a call on load, `declined` where a person was asked).
|
|
27
|
+
*/
|
|
28
|
+
export interface CheckCall {
|
|
29
|
+
readonly capability: string;
|
|
30
|
+
readonly outcome: string;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface CheckRunData {
|
|
34
|
+
readonly errors: string[];
|
|
35
|
+
readonly calls: CheckCall[];
|
|
36
|
+
readonly blocked: { readonly url: string; readonly directive: string }[];
|
|
37
|
+
readonly failedLoads: { readonly url: string; readonly tag: string }[];
|
|
38
|
+
readonly console: { readonly level: "error" | "warning"; readonly text: string }[];
|
|
39
|
+
readonly height: number | null;
|
|
40
|
+
readonly scrollWidth: number | null;
|
|
41
|
+
readonly clientWidth: number | null;
|
|
42
|
+
readonly outcome: string | null;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Each inline script's name (`//# sourceURL`): its index in the content. */
|
|
46
|
+
export const SCRIPT_NAME = "porthole-script-";
|
|
47
|
+
|
|
48
|
+
/** Put first in the content: it reports to the page that frames it. */
|
|
49
|
+
export const INSTRUMENT = `<script>(() => {
|
|
50
|
+
const send = (kind, data) => { try { parent.postMessage({ portholeCheck: kind, data }, "*"); } catch (_) {} };
|
|
51
|
+
const text = (value) => { try { return String(value && value.stack ? value.message || value : value); } catch (_) { return "?"; } };
|
|
52
|
+
for (const [method, level] of [["error", "error"], ["warn", "warning"]]) {
|
|
53
|
+
const original = console[method];
|
|
54
|
+
console[method] = (...args) => { send("console", { level, text: args.map(text).join(" ").slice(0, 400) }); return original.apply(console, args); };
|
|
55
|
+
}
|
|
56
|
+
addEventListener("error", (event) => {
|
|
57
|
+
const target = event.target;
|
|
58
|
+
if (target && target !== window && (target.src || target.href)) {
|
|
59
|
+
send("load", { url: String(target.src || target.href).slice(0, 400), tag: String(target.tagName || "").toLowerCase() });
|
|
60
|
+
} else if (event.message || event.error) {
|
|
61
|
+
const error = event.error;
|
|
62
|
+
send("error", {
|
|
63
|
+
message: (error && error.message ? (error.name || "Error") + ": " + error.message : String(event.message)).slice(0, 400),
|
|
64
|
+
file: String(event.filename || ""),
|
|
65
|
+
line: event.lineno || 0,
|
|
66
|
+
stack: error && error.stack ? String(error.stack).slice(0, 1000) : "",
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
}, true);
|
|
70
|
+
addEventListener("unhandledrejection", (event) => send("error", {
|
|
71
|
+
message: ("Unhandled rejection: " + text(event.reason)).slice(0, 400),
|
|
72
|
+
file: "", line: 0,
|
|
73
|
+
stack: event.reason && event.reason.stack ? String(event.reason.stack).slice(0, 1000) : "",
|
|
74
|
+
}));
|
|
75
|
+
addEventListener("securitypolicyviolation", (event) => send("blocked", { url: String(event.blockedURI || "inline").slice(0, 400), directive: String(event.effectiveDirective) }));
|
|
76
|
+
addEventListener("message", (event) => {
|
|
77
|
+
if (event.source === parent && event.data && event.data.portholeCheck === "measure") {
|
|
78
|
+
const root = document.documentElement;
|
|
79
|
+
send("measure", { scrollWidth: Math.max(root.scrollWidth, document.body ? document.body.scrollWidth : 0), clientWidth: root.clientWidth });
|
|
80
|
+
}
|
|
81
|
+
});
|
|
82
|
+
})();</script>`;
|
|
83
|
+
|
|
84
|
+
/** The content with the instrument first: after a document's <head>, or before a fragment. */
|
|
85
|
+
export function instrumented(content: string): string {
|
|
86
|
+
const head = /<head[^>]*>/iu.exec(content);
|
|
87
|
+
if (head !== null) {
|
|
88
|
+
const at = head.index + head[0].length;
|
|
89
|
+
return `${content.slice(0, at)}${INSTRUMENT}${content.slice(at)}`;
|
|
90
|
+
}
|
|
91
|
+
const html = /<html[^>]*>/iu.exec(content);
|
|
92
|
+
if (html !== null) {
|
|
93
|
+
const at = html.index + html[0].length;
|
|
94
|
+
return `${content.slice(0, at)}<head>${INSTRUMENT}</head>${content.slice(at)}`;
|
|
95
|
+
}
|
|
96
|
+
return /^\s*<!doctype/iu.test(content)
|
|
97
|
+
? content.replace(/^(\s*<!doctype[^>]*>)/iu, `$1${INSTRUMENT}`)
|
|
98
|
+
: `${INSTRUMENT}${content}`;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* The content with each inline script named (`//# sourceURL=porthole-script-<n>`, after its
|
|
103
|
+
* last line, so no line moves), and where each one's text starts in the content as written.
|
|
104
|
+
*/
|
|
105
|
+
export function namedScripts(content: string): { content: string; scriptLines: number[] } {
|
|
106
|
+
const scriptLines: number[] = [];
|
|
107
|
+
const named = content.replace(
|
|
108
|
+
/(<script\b(?![^>]*\bsrc\s*=)[^>]*>)([\s\S]*?)(<\/script>)/giu,
|
|
109
|
+
(whole, open: string, body: string, close: string, offset: number) => {
|
|
110
|
+
const index = scriptLines.length;
|
|
111
|
+
scriptLines.push(content.slice(0, offset + open.length).split("\n").length);
|
|
112
|
+
return `${open}${body}\n//# sourceURL=${SCRIPT_NAME}${index}\n${close}`;
|
|
113
|
+
},
|
|
114
|
+
);
|
|
115
|
+
return { content: named, scriptLines };
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* An error's line in the content as written: from its script's name (the event's file, or its
|
|
120
|
+
* stack's first frame there) and its line in that script; null where it can't be told.
|
|
121
|
+
*/
|
|
122
|
+
export function contentLine(
|
|
123
|
+
error: { readonly file: string; readonly line: number; readonly stack: string },
|
|
124
|
+
scriptLines: readonly number[],
|
|
125
|
+
): number | null {
|
|
126
|
+
const named = new RegExp(`${SCRIPT_NAME}(\\d+)(?::(\\d+))?`, "u");
|
|
127
|
+
const fromFile = named.exec(error.file);
|
|
128
|
+
if (fromFile?.[1] !== undefined && error.line > 0) {
|
|
129
|
+
const start = scriptLines[Number(fromFile[1])];
|
|
130
|
+
return start === undefined ? null : start + error.line - 1;
|
|
131
|
+
}
|
|
132
|
+
const fromStack = named.exec(error.stack);
|
|
133
|
+
if (fromStack?.[1] !== undefined && fromStack[2] !== undefined) {
|
|
134
|
+
const start = scriptLines[Number(fromStack[1])];
|
|
135
|
+
return start === undefined ? null : start + Number(fromStack[2]) - 1;
|
|
136
|
+
}
|
|
137
|
+
return null;
|
|
138
|
+
}
|
package/src/check/page-source.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The check page's script as a module (`@botiverse/porthole/check/page`)
|
|
3
|
-
*
|
|
4
|
-
*
|
|
2
|
+
* The check page's script as a module (`@botiverse/porthole/check/page`), which `checkPage`
|
|
3
|
+
* imports: from the sources, bundled now (Node, esbuild, Porthole's own development dependency);
|
|
4
|
+
* the package ships it built (`dist/check/page-source.js`, a string and nothing else), so a
|
|
5
|
+
* bundler takes it in like any module (P075).
|
|
5
6
|
*/
|
|
6
7
|
import { fileURLToPath } from "node:url";
|
|
7
8
|
|
package/src/check/page.ts
CHANGED
|
@@ -1,6 +1,54 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type { CapabilityHandlers } from "../bridge/types.ts";
|
|
2
|
+
import {
|
|
3
|
+
capabilitySpec,
|
|
4
|
+
isCapabilityName,
|
|
5
|
+
type HandledCapability,
|
|
6
|
+
} from "../config/capabilities.ts";
|
|
2
7
|
import { createHost } from "../host/create-host.ts";
|
|
3
8
|
import type { DisplayHandle } from "../host/types.ts";
|
|
9
|
+
import type { FrameLocation } from "../isolation/types.ts";
|
|
10
|
+
import {
|
|
11
|
+
contentLine,
|
|
12
|
+
instrumented,
|
|
13
|
+
type CheckCall,
|
|
14
|
+
type CheckRunData,
|
|
15
|
+
type CheckRunSpec,
|
|
16
|
+
} from "./instrument.ts";
|
|
17
|
+
|
|
18
|
+
export type { CheckCall, CheckRunData, CheckRunSpec } from "./instrument.ts";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* What a host that declines answers each host function with (P074): no prompt sent, no link
|
|
22
|
+
* opened, nothing downloaded or copied; a tool call or a read refused.
|
|
23
|
+
*/
|
|
24
|
+
const DECLINED: { readonly [N in HandledCapability]: () => unknown } = {
|
|
25
|
+
sendPrompt: () => false,
|
|
26
|
+
openLink: () => false,
|
|
27
|
+
downloadFile: () => false,
|
|
28
|
+
copyText: () => false,
|
|
29
|
+
setModelContext: () => undefined,
|
|
30
|
+
callTool: () => {
|
|
31
|
+
throw new Error("The host declined the tool call");
|
|
32
|
+
},
|
|
33
|
+
readData: () => {
|
|
34
|
+
throw new Error("The host declined the read");
|
|
35
|
+
},
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
/** A handler for each host function the config declares: it notes the call and answers no. */
|
|
39
|
+
function declining(capabilities: readonly string[], calls: CheckCall[]): CapabilityHandlers {
|
|
40
|
+
const handlers: Record<string, () => unknown> = {};
|
|
41
|
+
for (const name of capabilities) {
|
|
42
|
+
if (isCapabilityName(name) && capabilitySpec(name).served === "handler") {
|
|
43
|
+
const answer = DECLINED[name as HandledCapability];
|
|
44
|
+
handlers[name] = () => {
|
|
45
|
+
calls.push({ capability: name, outcome: "answered" });
|
|
46
|
+
return answer();
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
return handlers;
|
|
51
|
+
}
|
|
4
52
|
|
|
5
53
|
/**
|
|
6
54
|
* The check page (P073): runs content in the real sandbox (the core's `createHost`, the config's
|
|
@@ -10,75 +58,13 @@ import type { DisplayHandle } from "../host/types.ts";
|
|
|
10
58
|
* that `checkPage` loads into a blank page through its driver.
|
|
11
59
|
*/
|
|
12
60
|
|
|
13
|
-
export interface CheckRunSpec {
|
|
14
|
-
readonly config: PortholeConfig;
|
|
15
|
-
readonly content: string;
|
|
16
|
-
readonly widthPx: number;
|
|
17
|
-
readonly heightPx?: number;
|
|
18
|
-
readonly scheme: ColorScheme;
|
|
19
|
-
readonly hostTheme?: Readonly<Record<string, string>>;
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
export interface CheckRunData {
|
|
23
|
-
readonly errors: string[];
|
|
24
|
-
readonly blocked: { readonly url: string; readonly directive: string }[];
|
|
25
|
-
readonly failedLoads: { readonly url: string; readonly tag: string }[];
|
|
26
|
-
readonly console: { readonly level: "error" | "warning"; readonly text: string }[];
|
|
27
|
-
readonly height: number | null;
|
|
28
|
-
readonly scrollWidth: number | null;
|
|
29
|
-
readonly clientWidth: number | null;
|
|
30
|
-
readonly outcome: string | null;
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
/** Put first in the content: it reports to the page that frames it. */
|
|
34
|
-
export const INSTRUMENT = `<script>(() => {
|
|
35
|
-
const send = (kind, data) => { try { parent.postMessage({ portholeCheck: kind, data }, "*"); } catch (_) {} };
|
|
36
|
-
const text = (value) => { try { return String(value && value.stack ? value.message || value : value); } catch (_) { return "?"; } };
|
|
37
|
-
for (const [method, level] of [["error", "error"], ["warn", "warning"]]) {
|
|
38
|
-
const original = console[method];
|
|
39
|
-
console[method] = (...args) => { send("console", { level, text: args.map(text).join(" ").slice(0, 400) }); return original.apply(console, args); };
|
|
40
|
-
}
|
|
41
|
-
addEventListener("error", (event) => {
|
|
42
|
-
const target = event.target;
|
|
43
|
-
if (target && target !== window && (target.src || target.href)) {
|
|
44
|
-
send("load", { url: String(target.src || target.href).slice(0, 400), tag: String(target.tagName || "").toLowerCase() });
|
|
45
|
-
} else if (event.message || event.error) {
|
|
46
|
-
const where = event.lineno ? " (line " + event.lineno + ")" : "";
|
|
47
|
-
send("error", (event.error && event.error.message ? (event.error.name || "Error") + ": " + event.error.message : String(event.message)).slice(0, 400) + where);
|
|
48
|
-
}
|
|
49
|
-
}, true);
|
|
50
|
-
addEventListener("unhandledrejection", (event) => send("error", ("Unhandled rejection: " + text(event.reason)).slice(0, 400)));
|
|
51
|
-
addEventListener("securitypolicyviolation", (event) => send("blocked", { url: String(event.blockedURI || "inline").slice(0, 400), directive: String(event.effectiveDirective) }));
|
|
52
|
-
addEventListener("message", (event) => {
|
|
53
|
-
if (event.source === parent && event.data && event.data.portholeCheck === "measure") {
|
|
54
|
-
const root = document.documentElement;
|
|
55
|
-
send("measure", { scrollWidth: Math.max(root.scrollWidth, document.body ? document.body.scrollWidth : 0), clientWidth: root.clientWidth });
|
|
56
|
-
}
|
|
57
|
-
});
|
|
58
|
-
})();</script>`;
|
|
59
|
-
|
|
60
|
-
/** The content with the instrument first: after a document's <head>, or before a fragment. */
|
|
61
|
-
export function instrumented(content: string): string {
|
|
62
|
-
const head = /<head[^>]*>/iu.exec(content);
|
|
63
|
-
if (head !== null) {
|
|
64
|
-
const at = head.index + head[0].length;
|
|
65
|
-
return `${content.slice(0, at)}${INSTRUMENT}${content.slice(at)}`;
|
|
66
|
-
}
|
|
67
|
-
const html = /<html[^>]*>/iu.exec(content);
|
|
68
|
-
if (html !== null) {
|
|
69
|
-
const at = html.index + html[0].length;
|
|
70
|
-
return `${content.slice(0, at)}<head>${INSTRUMENT}</head>${content.slice(at)}`;
|
|
71
|
-
}
|
|
72
|
-
return /^\s*<!doctype/iu.test(content)
|
|
73
|
-
? content.replace(/^(\s*<!doctype[^>]*>)/iu, `$1${INSTRUMENT}`)
|
|
74
|
-
: `${INSTRUMENT}${content}`;
|
|
75
|
-
}
|
|
76
|
-
|
|
77
61
|
interface Run {
|
|
78
62
|
readonly display: DisplayHandle;
|
|
79
63
|
readonly box: HTMLElement;
|
|
64
|
+
readonly scriptLines: readonly number[];
|
|
80
65
|
readonly data: {
|
|
81
66
|
errors: string[];
|
|
67
|
+
calls: CheckCall[];
|
|
82
68
|
blocked: { url: string; directive: string }[];
|
|
83
69
|
failedLoads: { url: string; tag: string }[];
|
|
84
70
|
console: { level: "error" | "warning"; text: string }[];
|
|
@@ -105,9 +91,25 @@ addEventListener("message", (event: MessageEvent) => {
|
|
|
105
91
|
}
|
|
106
92
|
const said = data.data as Record<string, unknown>;
|
|
107
93
|
switch (data.portholeCheck) {
|
|
108
|
-
case "error":
|
|
109
|
-
|
|
94
|
+
case "error": {
|
|
95
|
+
const error = data.data as {
|
|
96
|
+
message?: unknown;
|
|
97
|
+
file?: unknown;
|
|
98
|
+
line?: unknown;
|
|
99
|
+
stack?: unknown;
|
|
100
|
+
};
|
|
101
|
+
const line = contentLine(
|
|
102
|
+
{
|
|
103
|
+
file: typeof error.file === "string" ? error.file : "",
|
|
104
|
+
line: typeof error.line === "number" ? error.line : 0,
|
|
105
|
+
stack: typeof error.stack === "string" ? error.stack : "",
|
|
106
|
+
},
|
|
107
|
+
run.scriptLines,
|
|
108
|
+
);
|
|
109
|
+
const message = typeof error.message === "string" ? error.message : "Error";
|
|
110
|
+
run.data.errors.push(`${message}${line === null ? "" : ` (line ${line})`}`);
|
|
110
111
|
break;
|
|
112
|
+
}
|
|
111
113
|
case "blocked":
|
|
112
114
|
run.data.blocked.push({ url: String(said.url), directive: String(said.directive) });
|
|
113
115
|
break;
|
|
@@ -140,19 +142,34 @@ const check = {
|
|
|
140
142
|
box.style.cssText = `width:${spec.widthPx}px;${spec.heightPx === undefined ? "" : `height:${spec.heightPx}px;`}`;
|
|
141
143
|
document.body.append(box);
|
|
142
144
|
const theme = spec.hostTheme ?? {};
|
|
145
|
+
const calls: CheckCall[] = [];
|
|
143
146
|
const display = createHost(spec.config, {
|
|
144
147
|
theme: () => theme,
|
|
145
148
|
hostInfo: { name: "porthole-check", version: "1" },
|
|
149
|
+
// Every host function the config declares, answered as a host that declines (P074): a
|
|
150
|
+
// person asked to confirm says no, a handler says no, and each call is noted.
|
|
151
|
+
handlers: declining(Object.keys(spec.config.capabilities), calls),
|
|
152
|
+
confirm: () => Promise.resolve("declined"),
|
|
153
|
+
// A served config's instance, issued by the check's own server on this page's origin.
|
|
154
|
+
locator: {
|
|
155
|
+
locate: async (instance) =>
|
|
156
|
+
(await (
|
|
157
|
+
await fetch("/issue", { method: "POST", body: JSON.stringify({ instance }) })
|
|
158
|
+
).json()) as FrameLocation,
|
|
159
|
+
},
|
|
146
160
|
}).mount(box, {
|
|
147
161
|
displayId: `check-${id}`,
|
|
148
162
|
title: "Check",
|
|
149
163
|
scheme: spec.scheme,
|
|
164
|
+
...(spec.instance === undefined ? {} : { instance: spec.instance }),
|
|
150
165
|
});
|
|
151
166
|
const run: Run = {
|
|
152
167
|
display,
|
|
153
168
|
box,
|
|
169
|
+
scriptLines: spec.scriptLines,
|
|
154
170
|
data: {
|
|
155
171
|
errors: [],
|
|
172
|
+
calls,
|
|
156
173
|
blocked: [],
|
|
157
174
|
failedLoads: [],
|
|
158
175
|
console: [],
|
|
@@ -165,11 +182,20 @@ const check = {
|
|
|
165
182
|
display.on("resize", ({ height }) => {
|
|
166
183
|
run.data.height = height;
|
|
167
184
|
});
|
|
185
|
+
display.on("refused", ({ capability, refusal }) => {
|
|
186
|
+
// "failed": the declining handler's own no, already noted.
|
|
187
|
+
if (refusal !== "failed") {
|
|
188
|
+
calls.push({ capability, outcome: refusal });
|
|
189
|
+
}
|
|
190
|
+
});
|
|
168
191
|
display.on("outcome", (outcome) => {
|
|
169
192
|
run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
|
|
170
193
|
});
|
|
171
194
|
runs.set(id, run);
|
|
172
|
-
|
|
195
|
+
// A stored page comes from the check's server; a shell (served or opaque) gets the content.
|
|
196
|
+
if (spec.instance?.document.kind !== "artifact") {
|
|
197
|
+
display.on("initialized", () => display.setContent(instrumented(spec.content)));
|
|
198
|
+
}
|
|
173
199
|
return id;
|
|
174
200
|
},
|
|
175
201
|
/** Asks the frame for its width; resolves when it answers (or after a second). */
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The conformance harness as one browser script, as a module `defineHostConformance` imports: from
|
|
3
|
+
* the sources, bundled now (Node, esbuild, Porthole's own development dependency); the package
|
|
4
|
+
* ships it built (`dist/conformance/harness-source.js`, a string and nothing else), so a bundler
|
|
5
|
+
* takes it in like any module and nothing is looked up beside it at run time (P075).
|
|
6
|
+
*/
|
|
7
|
+
import { fileURLToPath } from "node:url";
|
|
8
|
+
|
|
9
|
+
const { build } = await import("esbuild");
|
|
10
|
+
const result = await build({
|
|
11
|
+
entryPoints: [fileURLToPath(new URL("./harness/page.ts", import.meta.url))],
|
|
12
|
+
bundle: true,
|
|
13
|
+
format: "iife",
|
|
14
|
+
platform: "browser",
|
|
15
|
+
target: "es2022",
|
|
16
|
+
write: false,
|
|
17
|
+
logLevel: "silent",
|
|
18
|
+
});
|
|
19
|
+
const source: string = result.outputFiles[0]?.text ?? "";
|
|
20
|
+
if (source === "") {
|
|
21
|
+
throw new Error("the conformance harness didn't build");
|
|
22
|
+
}
|
|
23
|
+
export default source;
|