@botiverse/porthole 0.2.4 → 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 +17 -11
- package/dist/check/check.d.ts +100 -0
- package/dist/check/check.js +247 -0
- package/dist/check/drivers.d.ts +43 -0
- package/dist/check/drivers.js +181 -0
- package/dist/check/index.d.ts +8 -0
- package/dist/check/index.js +8 -0
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/lint.d.ts +21 -0
- package/dist/check/lint.js +131 -0
- package/dist/check/page-source.d.ts +2 -0
- package/dist/check/page-source.js +2 -0
- package/dist/check/page.d.ts +13 -0
- package/dist/check/page.js +170 -0
- package/dist/check/tools.d.ts +61 -0
- package/dist/check/tools.js +140 -0
- package/dist/conformance/host-kit.d.ts +26 -5
- package/dist/conformance/host-kit.js +46 -22
- 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/displays/displays.d.ts +61 -0
- package/dist/displays/displays.js +113 -0
- package/dist/host/client.d.ts +110 -0
- package/dist/host/client.js +274 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +6 -0
- package/dist/node/index.d.ts +26 -1
- package/dist/node/index.js +91 -1
- package/dist/react/frame.d.ts +79 -3
- package/dist/react/frame.js +183 -42
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +1 -0
- package/dist/react/view.d.ts +54 -0
- package/dist/react/view.js +151 -0
- package/dist/server/bootstrap.d.ts +27 -0
- package/dist/server/bootstrap.js +63 -0
- package/dist/server/host.d.ts +77 -8
- package/dist/server/host.js +268 -11
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +3 -1
- package/dist/server/pages.d.ts +19 -0
- package/dist/server/pages.js +8 -0
- package/dist/server/proxy.d.ts +24 -0
- package/dist/server/proxy.js +67 -0
- package/dist/server/server.js +14 -1
- package/dist/server/types.d.ts +8 -0
- package/docs/ADOPTING.md +278 -108
- package/docs/DECISIONS.md +280 -0
- package/docs/DESIGN.md +84 -2
- package/examples/app.mjs +82 -78
- package/examples/conformance/page.spec.mjs +23 -0
- package/examples/conformance/playwright.config.mjs +3 -2
- package/examples/conformance/porthole.spec.mjs +6 -3
- package/examples/displays.mjs +21 -0
- package/examples/mcp/server.mjs +121 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +13 -1
- package/src/check/check.ts +386 -0
- package/src/check/drivers.ts +242 -0
- package/src/check/index.ts +22 -0
- package/src/check/instrument.ts +138 -0
- package/src/check/lint.ts +238 -0
- package/src/check/page-source.ts +19 -0
- package/src/check/page.ts +230 -0
- package/src/check/tools.ts +206 -0
- package/src/conformance/host-kit.ts +82 -27
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/displays/displays.ts +191 -0
- package/src/host/client.ts +395 -0
- package/src/index.ts +25 -0
- package/src/node/index.ts +112 -2
- package/src/react/frame.tsx +271 -57
- package/src/react/index.ts +9 -0
- package/src/react/view.tsx +237 -0
- package/src/server/bootstrap.ts +97 -0
- package/src/server/host.ts +372 -18
- package/src/server/index.ts +11 -1
- package/src/server/pages.ts +28 -0
- package/src/server/proxy.ts +86 -0
- package/src/server/server.ts +26 -2
- package/src/server/types.ts +5 -0
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import type { InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
import { presets } from "../presets/presets.ts";
|
|
4
|
+
import { createServer } from "../server/server.ts";
|
|
5
|
+
import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.ts";
|
|
6
|
+
import { lintContent, type Finding } from "./lint.ts";
|
|
7
|
+
import {
|
|
8
|
+
instrumented,
|
|
9
|
+
namedScripts,
|
|
10
|
+
type CheckCall,
|
|
11
|
+
type CheckRunData,
|
|
12
|
+
type CheckRunSpec,
|
|
13
|
+
} from "./instrument.ts";
|
|
14
|
+
|
|
15
|
+
export type { CheckCall } from "./instrument.ts";
|
|
16
|
+
|
|
17
|
+
/** The content source the check's served origins match. */
|
|
18
|
+
const CHECK_SOURCE = `https://*.${CHECK_CONTENT_DOMAIN}`;
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Checks content before people see it (P073): runs it in the real sandbox at each width and
|
|
22
|
+
* scheme, through a driver (a browser the host has: Playwright, or any CDP session, Cloudflare
|
|
23
|
+
* Browser Rendering's included), and says what went wrong, briefly, for the agent.
|
|
24
|
+
*
|
|
25
|
+
* const report = await checkPage({ config, content: html, driver: playwrightDriver(browser) });
|
|
26
|
+
* report.ok; report.text; // "At 320 px, dark: TypeError: … (line 12). …"
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
/** A page the check drives: one at a time, sequentially. */
|
|
30
|
+
export interface CheckSession {
|
|
31
|
+
setViewport(width: number, height: number): Promise<void>;
|
|
32
|
+
/** Loads a whole HTML document into the page. */
|
|
33
|
+
load(html: string): Promise<void>;
|
|
34
|
+
/**
|
|
35
|
+
* Answers every request to the check page's origin and the check's content domain with
|
|
36
|
+
* `handler`, and opens the page (`/`): a served config's content then runs on an origin of its
|
|
37
|
+
* own, as people's browsers run it (P074). Without it, the check runs content opaque.
|
|
38
|
+
*/
|
|
39
|
+
serve?(handler: (request: Request) => Promise<Response>): Promise<void>;
|
|
40
|
+
/** Evaluates a JavaScript expression in the page (a promise is awaited); JSON back. */
|
|
41
|
+
evaluate<T>(expression: string): Promise<T>;
|
|
42
|
+
/** A PNG of the element `selector` names, where the driver can. */
|
|
43
|
+
screenshot?(selector: string): Promise<Uint8Array>;
|
|
44
|
+
close(): Promise<void>;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** How the check gets a page: `playwrightDriver(browser)`, `cdpDriver(session)`. */
|
|
48
|
+
export interface CheckDriver {
|
|
49
|
+
open(): Promise<CheckSession>;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export interface CheckOptions {
|
|
53
|
+
readonly config: PortholeConfig;
|
|
54
|
+
/** The content as the agent would send it: a fragment, or a whole document. */
|
|
55
|
+
readonly content: string;
|
|
56
|
+
readonly driver: CheckDriver;
|
|
57
|
+
/** Widths, px. Default: the manual's phone and desktop widths (`config.layout`). */
|
|
58
|
+
readonly widths?: readonly number[];
|
|
59
|
+
/** Default: light and dark, or light alone where the app doesn't theme it. */
|
|
60
|
+
readonly schemes?: readonly ColorScheme[];
|
|
61
|
+
/** The host's live theme values per scheme, as `HostOptions.theme` answers. */
|
|
62
|
+
readonly hostTheme?: {
|
|
63
|
+
readonly light?: Readonly<Record<string, string>>;
|
|
64
|
+
readonly dark?: Readonly<Record<string, string>>;
|
|
65
|
+
};
|
|
66
|
+
/** How long content settles before it is measured, ms. Default 1500. */
|
|
67
|
+
readonly settleMs?: number;
|
|
68
|
+
/** A PNG of each run, for an agent that sees. */
|
|
69
|
+
readonly screenshots?: boolean;
|
|
70
|
+
/** The most distinct problems `text` names (default 8): the rest are counted. */
|
|
71
|
+
readonly maxProblems?: number;
|
|
72
|
+
/**
|
|
73
|
+
* The check page's script (`import page from "@botiverse/porthole/check/page"`). Node finds it
|
|
74
|
+
* itself; a bundled runtime (a Worker) passes it.
|
|
75
|
+
*/
|
|
76
|
+
readonly page?: string;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export interface CheckRun {
|
|
80
|
+
readonly width: number;
|
|
81
|
+
readonly scheme: ColorScheme;
|
|
82
|
+
/** The height the content reported, px, and whether the config's limit cuts it. */
|
|
83
|
+
readonly height: number | null;
|
|
84
|
+
readonly clipped: boolean;
|
|
85
|
+
/** Wider than its frame: it scrolls sideways (or is cut). */
|
|
86
|
+
readonly overflowX: boolean;
|
|
87
|
+
readonly errors: readonly string[];
|
|
88
|
+
readonly blocked: readonly { readonly url: string; readonly directive: string }[];
|
|
89
|
+
readonly failedLoads: readonly { readonly url: string; readonly tag: string }[];
|
|
90
|
+
readonly console: readonly { readonly level: "error" | "warning"; readonly text: string }[];
|
|
91
|
+
/**
|
|
92
|
+
* The host functions it called (P074), each answered as a host that declines would. One a
|
|
93
|
+
* host's gates refuse whatever the person says (no click, bad arguments, not offered, too
|
|
94
|
+
* often) is a problem; one a person or host may decline is a note.
|
|
95
|
+
*/
|
|
96
|
+
readonly calls: readonly CheckCall[];
|
|
97
|
+
readonly screenshot?: Uint8Array;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export interface CheckReport {
|
|
101
|
+
/**
|
|
102
|
+
* Nothing failed: no errors, blocks, failed loads, console errors, host-function calls a host
|
|
103
|
+
* refuses, overflow or cut, no lint error.
|
|
104
|
+
*/
|
|
105
|
+
readonly ok: boolean;
|
|
106
|
+
readonly lint: readonly Finding[];
|
|
107
|
+
readonly runs: readonly CheckRun[];
|
|
108
|
+
/** One short summary for the agent: each problem once, with where it happened. */
|
|
109
|
+
readonly text: string;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
const noun = (config: PortholeConfig) =>
|
|
113
|
+
config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The config the check runs content under where it can't serve it (a driver without `serve`):
|
|
117
|
+
* opaque (a served config's content with the same CSP); an MCP Apps view as a page with the view's
|
|
118
|
+
* egress (its protocol is its host's).
|
|
119
|
+
*/
|
|
120
|
+
function checkedAs(config: PortholeConfig): PortholeConfig {
|
|
121
|
+
const opaque: PortholeConfig =
|
|
122
|
+
config.isolation === "opaque" ? config : { ...config, isolation: "opaque", contentOrigins: [] };
|
|
123
|
+
return opaque.mode === "mcp-app"
|
|
124
|
+
? presets.artifact({ egress: opaque.egress, limits: opaque.limits })
|
|
125
|
+
: opaque;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** The check page's script: given, or (Node) the package's own. */
|
|
129
|
+
async function pageScript(given: string | undefined): Promise<string> {
|
|
130
|
+
if (given !== undefined) {
|
|
131
|
+
return given;
|
|
132
|
+
}
|
|
133
|
+
// Not a literal: a bundler for a Worker leaves it alone (a Worker passes `page`).
|
|
134
|
+
const where = new URL(
|
|
135
|
+
import.meta.url.endsWith(".ts") ? "./page-source.ts" : "./page-source.js",
|
|
136
|
+
import.meta.url,
|
|
137
|
+
).href;
|
|
138
|
+
const loaded = (await import(where)) as { default: string };
|
|
139
|
+
return loaded.default;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
const escapeScript = (code: string) => code.replace(/<\/script/giu, "<\\/script");
|
|
143
|
+
|
|
144
|
+
export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
145
|
+
const { config } = options;
|
|
146
|
+
const lint = lintContent(config, options.content);
|
|
147
|
+
if (config.mode === "url") {
|
|
148
|
+
return {
|
|
149
|
+
ok: true,
|
|
150
|
+
lint,
|
|
151
|
+
runs: [],
|
|
152
|
+
text: "A url-mode app runs its own page: nothing to check here.",
|
|
153
|
+
};
|
|
154
|
+
}
|
|
155
|
+
const widths = options.widths ?? [config.layout.narrowWidthPx, config.layout.wideWidthPx];
|
|
156
|
+
const unthemed = config.theme.documents === "never";
|
|
157
|
+
const schemes = options.schemes ?? (unthemed ? ["light"] : ["light", "dark"]);
|
|
158
|
+
const settle = options.settleMs ?? 1_500;
|
|
159
|
+
const fills = config.layout.kind === "fill";
|
|
160
|
+
const script = await pageScript(options.page);
|
|
161
|
+
const html = `<!doctype html><html><head><meta charset="utf-8"><title>Porthole check</title><style>body{margin:0;padding:8px}section{margin-bottom:16px}</style></head><body><script>${escapeScript(script)}</script></body></html>`;
|
|
162
|
+
// Its inline scripts named, so an error says the line in the content as written (P074).
|
|
163
|
+
const { content, scriptLines } = namedScripts(options.content);
|
|
164
|
+
|
|
165
|
+
const session = await options.driver.open();
|
|
166
|
+
// A served config runs served, on a content origin the driver answers, under Porthole's own
|
|
167
|
+
// server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
|
|
168
|
+
const servedHere =
|
|
169
|
+
config.isolation === "domain" && config.mode !== "mcp-app" && session.serve !== undefined;
|
|
170
|
+
const servedConfig: PortholeConfig = { ...config, contentOrigins: [CHECK_SOURCE] };
|
|
171
|
+
const server = servedHere
|
|
172
|
+
? createServer({
|
|
173
|
+
content: { domain: CHECK_CONTENT_DOMAIN, scheme: "https" },
|
|
174
|
+
secret: crypto.getRandomValues(new Uint8Array(32)),
|
|
175
|
+
hostOrigins: [CHECK_ORIGIN],
|
|
176
|
+
configs: { check: servedConfig },
|
|
177
|
+
artifacts: { get: () => Promise.resolve({ html: instrumented(content) }) },
|
|
178
|
+
})
|
|
179
|
+
: null;
|
|
180
|
+
const handler = async (request: Request): Promise<Response> => {
|
|
181
|
+
const url = new URL(request.url);
|
|
182
|
+
if (url.origin === CHECK_ORIGIN) {
|
|
183
|
+
if (url.pathname === "/") {
|
|
184
|
+
return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });
|
|
185
|
+
}
|
|
186
|
+
if (url.pathname === "/issue" && server !== null) {
|
|
187
|
+
const asked = (await request.json()) as { instance: InstanceRef };
|
|
188
|
+
return Response.json(await server.issue(asked.instance, { viewer: "check" }));
|
|
189
|
+
}
|
|
190
|
+
return new Response("not found", { status: 404 });
|
|
191
|
+
}
|
|
192
|
+
return (await server?.handle(request)) ?? new Response("not found", { status: 404 });
|
|
193
|
+
};
|
|
194
|
+
const shown = servedHere ? servedConfig : checkedAs(config);
|
|
195
|
+
let runIndex = 0;
|
|
196
|
+
|
|
197
|
+
const runs: CheckRun[] = [];
|
|
198
|
+
try {
|
|
199
|
+
for (const width of widths) {
|
|
200
|
+
await session.setViewport(width + 40, fills ? 760 : 900);
|
|
201
|
+
if (servedHere && session.serve !== undefined) {
|
|
202
|
+
await session.serve(handler);
|
|
203
|
+
} else {
|
|
204
|
+
await session.load(html);
|
|
205
|
+
}
|
|
206
|
+
for (const scheme of schemes) {
|
|
207
|
+
runIndex += 1;
|
|
208
|
+
// Each run on an origin of its own: its storage starts empty, as a new page's does.
|
|
209
|
+
const instance: InstanceRef | undefined = servedHere
|
|
210
|
+
? {
|
|
211
|
+
scope: `check-${runIndex}`,
|
|
212
|
+
document:
|
|
213
|
+
config.mode === "inline"
|
|
214
|
+
? { kind: "shell", preset: "check" }
|
|
215
|
+
: { kind: "artifact", id: "check", version: "1", preset: "check" },
|
|
216
|
+
}
|
|
217
|
+
: undefined;
|
|
218
|
+
const spec: CheckRunSpec = {
|
|
219
|
+
config: shown,
|
|
220
|
+
content,
|
|
221
|
+
scriptLines,
|
|
222
|
+
...(instance === undefined ? {} : { instance }),
|
|
223
|
+
widthPx: width,
|
|
224
|
+
...(fills ? { heightPx: 700 } : {}),
|
|
225
|
+
scheme,
|
|
226
|
+
...(options.hostTheme?.[scheme] === undefined
|
|
227
|
+
? {}
|
|
228
|
+
: { hostTheme: options.hostTheme[scheme] }),
|
|
229
|
+
};
|
|
230
|
+
const id = await session.evaluate<number>(
|
|
231
|
+
`window.portholeCheck.run(${JSON.stringify(spec)})`,
|
|
232
|
+
);
|
|
233
|
+
await session.evaluate(`new Promise((resolve) => setTimeout(resolve, ${settle}))`);
|
|
234
|
+
await session.evaluate(`window.portholeCheck.measure(${id})`);
|
|
235
|
+
const data = await session.evaluate<CheckRunData | null>(
|
|
236
|
+
`window.portholeCheck.result(${id})`,
|
|
237
|
+
);
|
|
238
|
+
const screenshot =
|
|
239
|
+
options.screenshots === true && session.screenshot !== undefined
|
|
240
|
+
? await session.screenshot(`#porthole-check-${id}`)
|
|
241
|
+
: undefined;
|
|
242
|
+
await session.evaluate(`window.portholeCheck.end(${id})`);
|
|
243
|
+
const height = data?.height ?? null;
|
|
244
|
+
runs.push({
|
|
245
|
+
width,
|
|
246
|
+
scheme,
|
|
247
|
+
height,
|
|
248
|
+
clipped: !fills && height !== null && height >= config.limits.maxHeightPx,
|
|
249
|
+
overflowX:
|
|
250
|
+
data?.scrollWidth !== null &&
|
|
251
|
+
data?.scrollWidth !== undefined &&
|
|
252
|
+
data.clientWidth !== null &&
|
|
253
|
+
data.scrollWidth > data.clientWidth + 1,
|
|
254
|
+
errors: unique(data?.errors ?? []),
|
|
255
|
+
blocked: uniqueBy(data?.blocked ?? [], (each) => `${each.url} ${each.directive}`),
|
|
256
|
+
failedLoads: uniqueBy(data?.failedLoads ?? [], (each) => each.url),
|
|
257
|
+
console: uniqueBy(data?.console ?? [], (each) => `${each.level} ${each.text}`),
|
|
258
|
+
calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
|
|
259
|
+
...(screenshot === undefined ? {} : { screenshot }),
|
|
260
|
+
});
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
} finally {
|
|
264
|
+
await session.close();
|
|
265
|
+
}
|
|
266
|
+
const failed = (run: CheckRun) =>
|
|
267
|
+
run.errors.length > 0 ||
|
|
268
|
+
run.blocked.length > 0 ||
|
|
269
|
+
run.failedLoads.length > 0 ||
|
|
270
|
+
run.console.some((each) => each.level === "error") ||
|
|
271
|
+
run.calls.some((each) => REFUSED[each.outcome] !== undefined) ||
|
|
272
|
+
run.overflowX ||
|
|
273
|
+
run.clipped;
|
|
274
|
+
const ok = !lint.some((each) => each.severity === "error") && !runs.some(failed);
|
|
275
|
+
return { ok, lint, runs, text: summary(config, lint, runs, options.maxProblems ?? 8) };
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** Calls a host refuses whatever the person says: problems, worded for the agent. */
|
|
279
|
+
const REFUSED: Readonly<Record<string, (capability: string) => string>> = {
|
|
280
|
+
"no-user-activation": (name) =>
|
|
281
|
+
`It called ${name} at load, with no click: hosts refuse that. Call ${name} from a click`,
|
|
282
|
+
invalid: (name) =>
|
|
283
|
+
`It called ${name} with arguments hosts refuse: see what the manual says ${name} takes`,
|
|
284
|
+
"not-declared": (name) => `It called ${name}, which this host doesn't offer: leave it out`,
|
|
285
|
+
"rate-limited": (name) => `It called ${name} more often than hosts allow, and was refused`,
|
|
286
|
+
"no-confirm": (name) => `It called ${name}, which this host can't confirm, and was refused`,
|
|
287
|
+
};
|
|
288
|
+
|
|
289
|
+
const unique = (values: readonly string[]) => [...new Set(values)];
|
|
290
|
+
function uniqueBy<T>(values: readonly T[], key: (value: T) => string): T[] {
|
|
291
|
+
const seen = new Set<string>();
|
|
292
|
+
return values.filter((each) => {
|
|
293
|
+
const k = key(each);
|
|
294
|
+
if (seen.has(k)) {
|
|
295
|
+
return false;
|
|
296
|
+
}
|
|
297
|
+
seen.add(k);
|
|
298
|
+
return true;
|
|
299
|
+
});
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
const clip = (text: string, most = 200) =>
|
|
303
|
+
text.length > most ? `${text.slice(0, most - 1)}…` : text;
|
|
304
|
+
|
|
305
|
+
/**
|
|
306
|
+
* The report in a few lines for the agent: each problem once, with the runs it happened in, at
|
|
307
|
+
* most `most` of them.
|
|
308
|
+
*/
|
|
309
|
+
function summary(
|
|
310
|
+
config: PortholeConfig,
|
|
311
|
+
lint: readonly Finding[],
|
|
312
|
+
runs: readonly CheckRun[],
|
|
313
|
+
most: number,
|
|
314
|
+
): string {
|
|
315
|
+
const it = noun(config);
|
|
316
|
+
const where = new Map<string, string[]>();
|
|
317
|
+
const add = (problem: string, run: CheckRun) => {
|
|
318
|
+
const list = where.get(problem) ?? [];
|
|
319
|
+
list.push(`${run.width} px ${run.scheme}`);
|
|
320
|
+
where.set(problem, list);
|
|
321
|
+
};
|
|
322
|
+
// Calls a person or host may decline: the content should still work when they do.
|
|
323
|
+
const notes = new Set<string>();
|
|
324
|
+
for (const run of runs) {
|
|
325
|
+
for (const call of run.calls) {
|
|
326
|
+
const refused = REFUSED[call.outcome];
|
|
327
|
+
if (refused === undefined) {
|
|
328
|
+
notes.add(
|
|
329
|
+
`Note: it called ${call.capability} at load; the check answered no, as a host or a person may. Make sure the ${it} still works then.`,
|
|
330
|
+
);
|
|
331
|
+
} else {
|
|
332
|
+
add(refused(call.capability), run);
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
for (const error of run.errors) {
|
|
336
|
+
add(`It threw: ${clip(error)}`, run);
|
|
337
|
+
}
|
|
338
|
+
for (const block of run.blocked) {
|
|
339
|
+
add(
|
|
340
|
+
`The sandbox blocked ${clip(block.url, 120)} (${block.directive}): nothing loads from there here`,
|
|
341
|
+
run,
|
|
342
|
+
);
|
|
343
|
+
}
|
|
344
|
+
const blockedUrls = new Set(run.blocked.map((each) => each.url));
|
|
345
|
+
for (const load of run.failedLoads.filter((each) => !blockedUrls.has(each.url))) {
|
|
346
|
+
add(`Failed to load ${clip(load.url, 120)} (<${load.tag}>)`, run);
|
|
347
|
+
}
|
|
348
|
+
for (const line of run.console.filter((each) => each.level === "error")) {
|
|
349
|
+
add(`console.error: ${clip(line.text)}`, run);
|
|
350
|
+
}
|
|
351
|
+
if (run.overflowX) {
|
|
352
|
+
add(
|
|
353
|
+
`It is wider than its frame and scrolls sideways: nothing fixed wider than ${config.layout.minWidthPx} px; let it wrap`,
|
|
354
|
+
run,
|
|
355
|
+
);
|
|
356
|
+
}
|
|
357
|
+
if (run.clipped) {
|
|
358
|
+
add(`It is taller than ${config.limits.maxHeightPx} px and is cut: make it shorter`, run);
|
|
359
|
+
}
|
|
360
|
+
}
|
|
361
|
+
const lines = [
|
|
362
|
+
...lint.map(
|
|
363
|
+
(each) =>
|
|
364
|
+
`${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`,
|
|
365
|
+
),
|
|
366
|
+
...[...where].map(
|
|
367
|
+
([problem, at]) =>
|
|
368
|
+
`${problem} (at ${at.length === runs.length ? "every width and scheme" : at.join(", ")}).`,
|
|
369
|
+
),
|
|
370
|
+
];
|
|
371
|
+
const ran = `${[...new Set(runs.map((run) => `${run.width} px`))].join(" and ")}, ${[...new Set(runs.map((run) => run.scheme))].join(" and ")}`;
|
|
372
|
+
if (lines.length === 0) {
|
|
373
|
+
return [
|
|
374
|
+
`OK: the ${it} ran at ${ran} with no errors, blocks, failed loads or overflow.`,
|
|
375
|
+
...notes,
|
|
376
|
+
].join("\n");
|
|
377
|
+
}
|
|
378
|
+
const shown = lines.slice(0, most);
|
|
379
|
+
const more = lines.length - shown.length;
|
|
380
|
+
return [
|
|
381
|
+
`The ${it} has ${lines.length} problem${lines.length === 1 ? "" : "s"} (ran at ${ran}):`,
|
|
382
|
+
...shown.map((line) => `- ${line}`),
|
|
383
|
+
...(more > 0 ? [`- and ${more} more.`] : []),
|
|
384
|
+
...notes,
|
|
385
|
+
].join("\n");
|
|
386
|
+
}
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
import type { Browser } from "@playwright/test";
|
|
2
|
+
import type { CheckDriver, CheckSession } from "./check.ts";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Drivers for `checkPage` (P073): Playwright's browser on Node, or any Chrome DevTools Protocol
|
|
6
|
+
* session (Puppeteer's `page.createCDPSession()`, `@cloudflare/puppeteer` on Cloudflare Browser
|
|
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).
|
|
12
|
+
*/
|
|
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
|
+
|
|
36
|
+
/** Checks in a page of a Playwright browser (`chromium.launch()`), one page per check. */
|
|
37
|
+
export function playwrightDriver(browser: Browser): CheckDriver {
|
|
38
|
+
return {
|
|
39
|
+
async open(): Promise<CheckSession> {
|
|
40
|
+
const page = await browser.newPage();
|
|
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
|
+
});
|
|
72
|
+
return {
|
|
73
|
+
setViewport: (width, height) => page.setViewportSize({ width, height }),
|
|
74
|
+
async load(document) {
|
|
75
|
+
handler = pageOnly(document);
|
|
76
|
+
await page.goto(`${CHECK_ORIGIN}/`, { waitUntil: "load" });
|
|
77
|
+
},
|
|
78
|
+
async serve(given) {
|
|
79
|
+
handler = given;
|
|
80
|
+
await page.goto(`${CHECK_ORIGIN}/`, { waitUntil: "load" });
|
|
81
|
+
},
|
|
82
|
+
evaluate: (expression) => page.evaluate(expression),
|
|
83
|
+
screenshot: async (selector) => new Uint8Array(await page.locator(selector).screenshot()),
|
|
84
|
+
close: () => page.close(),
|
|
85
|
+
};
|
|
86
|
+
},
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
|
|
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
|
+
*/
|
|
95
|
+
export interface CdpSession {
|
|
96
|
+
send(method: string, params?: Record<string, unknown>): Promise<unknown>;
|
|
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
|
+
};
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const bytesToBase64 = (bytes: Uint8Array): string => {
|
|
112
|
+
let binary = "";
|
|
113
|
+
for (const byte of bytes) {
|
|
114
|
+
binary += String.fromCharCode(byte);
|
|
115
|
+
}
|
|
116
|
+
return btoa(binary);
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
const base64 = (text: string): Uint8Array =>
|
|
120
|
+
Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Checks over a CDP session to a page (P073): `cdpDriver(() => page.createCDPSession())` with
|
|
124
|
+
* Puppeteer, or `@cloudflare/puppeteer` in a Worker with a Browser Rendering binding. `open` is
|
|
125
|
+
* asked for a session per check; the caller closes its page.
|
|
126
|
+
*/
|
|
127
|
+
export function cdpDriver(open: () => Promise<CdpSession>): CheckDriver {
|
|
128
|
+
return {
|
|
129
|
+
async open(): Promise<CheckSession> {
|
|
130
|
+
const session = await open();
|
|
131
|
+
await session.send("Page.enable");
|
|
132
|
+
await session.send("Runtime.enable");
|
|
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
|
+
})();
|
|
169
|
+
});
|
|
170
|
+
const evaluate = async <T>(expression: string): Promise<T> => {
|
|
171
|
+
const answer = (await session.send("Runtime.evaluate", {
|
|
172
|
+
expression,
|
|
173
|
+
awaitPromise: true,
|
|
174
|
+
returnByValue: true,
|
|
175
|
+
})) as {
|
|
176
|
+
result?: { value?: unknown };
|
|
177
|
+
exceptionDetails?: { text?: string; exception?: { description?: string } };
|
|
178
|
+
};
|
|
179
|
+
if (answer.exceptionDetails !== undefined) {
|
|
180
|
+
throw new Error(
|
|
181
|
+
answer.exceptionDetails.exception?.description ??
|
|
182
|
+
answer.exceptionDetails.text ??
|
|
183
|
+
"Evaluation failed",
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
return answer.result?.value as T;
|
|
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
|
+
};
|
|
202
|
+
return {
|
|
203
|
+
async setViewport(width, height) {
|
|
204
|
+
await session.send("Emulation.setDeviceMetricsOverride", {
|
|
205
|
+
width,
|
|
206
|
+
height,
|
|
207
|
+
deviceScaleFactor: 1,
|
|
208
|
+
mobile: false,
|
|
209
|
+
});
|
|
210
|
+
},
|
|
211
|
+
async load(document) {
|
|
212
|
+
handler = pageOnly(document);
|
|
213
|
+
await goto();
|
|
214
|
+
},
|
|
215
|
+
async serve(given) {
|
|
216
|
+
handler = given;
|
|
217
|
+
await goto();
|
|
218
|
+
},
|
|
219
|
+
evaluate,
|
|
220
|
+
async screenshot(selector) {
|
|
221
|
+
const box = await evaluate<{
|
|
222
|
+
x: number;
|
|
223
|
+
y: number;
|
|
224
|
+
width: number;
|
|
225
|
+
height: number;
|
|
226
|
+
} | null>(
|
|
227
|
+
`(() => { const r = document.querySelector(${JSON.stringify(selector)})?.getBoundingClientRect(); return r ? { x: r.x, y: r.y, width: r.width, height: r.height } : null; })()`,
|
|
228
|
+
);
|
|
229
|
+
if (box === null) {
|
|
230
|
+
return new Uint8Array();
|
|
231
|
+
}
|
|
232
|
+
const shot = (await session.send("Page.captureScreenshot", {
|
|
233
|
+
format: "png",
|
|
234
|
+
clip: { ...box, scale: 1 },
|
|
235
|
+
})) as { data: string };
|
|
236
|
+
return base64(shot.data);
|
|
237
|
+
},
|
|
238
|
+
close: () => Promise.resolve(),
|
|
239
|
+
};
|
|
240
|
+
},
|
|
241
|
+
};
|
|
242
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@botiverse/porthole/check`: check content before people see it (P073). `checkPage` runs it in
|
|
3
|
+
* the real sandbox through a driver (`playwrightDriver`, `cdpDriver`); `lintContent` and the tool
|
|
4
|
+
* definitions are in the core (`@botiverse/porthole`), since they need no browser.
|
|
5
|
+
*/
|
|
6
|
+
export {
|
|
7
|
+
checkPage,
|
|
8
|
+
type CheckCall,
|
|
9
|
+
type CheckDriver,
|
|
10
|
+
type CheckOptions,
|
|
11
|
+
type CheckReport,
|
|
12
|
+
type CheckRun,
|
|
13
|
+
type CheckSession,
|
|
14
|
+
} from "./check.ts";
|
|
15
|
+
export {
|
|
16
|
+
CHECK_CONTENT_DOMAIN,
|
|
17
|
+
CHECK_ORIGIN,
|
|
18
|
+
cdpDriver,
|
|
19
|
+
playwrightDriver,
|
|
20
|
+
type CdpSession,
|
|
21
|
+
} from "./drivers.ts";
|
|
22
|
+
export { lintContent, type Finding, type LintRule } from "./lint.ts";
|