@botiverse/porthole 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +83 -0
  2. package/dist/cli.d.ts +6 -0
  3. package/dist/cli.js +51 -0
  4. package/dist/conformance/entry.d.ts +19 -7
  5. package/dist/conformance/entry.js +39 -12
  6. package/dist/conformance/harness.js +8 -8
  7. package/dist/conformance/host-kit.d.ts +48 -13
  8. package/dist/conformance/host-kit.js +140 -28
  9. package/dist/conformance/index.d.ts +1 -1
  10. package/dist/conformance/index.js +1 -1
  11. package/dist/conformance/limits.js +15 -2
  12. package/dist/conformance/page.d.ts +6 -0
  13. package/dist/conformance/page.js +8 -0
  14. package/dist/conformance/served.d.ts +4 -4
  15. package/dist/conformance/served.js +26 -16
  16. package/dist/host/types.d.ts +6 -3
  17. package/dist/isolation/served.js +13 -2
  18. package/dist/node/index.d.ts +11 -3
  19. package/dist/node/index.js +70 -10
  20. package/dist/react/frame.d.ts +5 -2
  21. package/dist/server/host.d.ts +42 -8
  22. package/dist/server/host.js +35 -5
  23. package/dist/server/index.d.ts +4 -1
  24. package/dist/server/index.js +2 -0
  25. package/dist/server/pages.js +15 -1
  26. package/dist/server/proxy.js +2 -0
  27. package/dist/server/server.js +9 -2
  28. package/dist/server/types.d.ts +15 -6
  29. package/docs/ARCHITECTURE.md +277 -0
  30. package/docs/DECISIONS.md +1811 -0
  31. package/docs/DESIGN.md +1074 -0
  32. package/docs/OBJECTIVES.md +116 -0
  33. package/docs/PRINCIPLES.md +155 -0
  34. package/examples/app.mjs +234 -0
  35. package/examples/conformance/playwright.config.mjs +28 -0
  36. package/examples/conformance/porthole.spec.mjs +36 -0
  37. package/examples/node/server.mjs +75 -0
  38. package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
  39. package/examples/workers/worker.mjs +33 -0
  40. package/examples/workers/wrangler.jsonc +19 -0
  41. package/package.json +9 -3
  42. package/src/cli.ts +54 -0
  43. package/src/conformance/entry.ts +70 -19
  44. package/src/conformance/host-kit.ts +194 -45
  45. package/src/conformance/index.ts +4 -0
  46. package/src/conformance/limits.ts +21 -4
  47. package/src/conformance/page.ts +8 -0
  48. package/src/conformance/served.ts +34 -21
  49. package/src/host/types.ts +6 -3
  50. package/src/isolation/served.ts +12 -2
  51. package/src/node/index.ts +73 -10
  52. package/src/react/frame.tsx +5 -2
  53. package/src/server/host.ts +84 -14
  54. package/src/server/index.ts +6 -0
  55. package/src/server/pages.ts +15 -1
  56. package/src/server/proxy.ts +2 -0
  57. package/src/server/server.ts +11 -2
  58. package/src/server/types.ts +18 -7
@@ -1,7 +1,9 @@
1
1
  import { readFile } from "node:fs/promises";
2
2
  import { fileURLToPath } from "node:url";
3
+ import { runInThisContext } from "node:vm";
3
4
  import { expect } from "@playwright/test";
4
5
  import { entryTests } from "./entry.js";
6
+ export { conformancePage } from "./page.js";
5
7
  import { leakTests } from "./probes.js";
6
8
  import { servedTests } from "./served.js";
7
9
  const CANARY = "https://porthole-canary.example";
@@ -203,7 +205,11 @@ export function hostConformance(options) {
203
205
  },
204
206
  canary: (name) => Promise.resolve(`${CANARY}/${name}`),
205
207
  canaryHits: (name) => Promise.resolve(hits.get(name) ?? 0),
206
- shell: options.instances.shell,
208
+ // An app that serves only stored pages: the domain-mode cases on its page's first version.
209
+ shell: options.instances.shell ??
210
+ (artifact === undefined
211
+ ? (scope) => ({ scope, document: { kind: "shell", preset: "inlineWidget" } })
212
+ : (scope) => artifact(scope, "1")),
207
213
  // Asked for only by cases that run where the app gave them (`defineHostConformance` skips).
208
214
  artifact: artifact ??
209
215
  ((scope, version) => ({ scope, document: { kind: "artifact", id: "page", version } })),
@@ -215,18 +221,25 @@ export function hostConformance(options) {
215
221
  ? null
216
222
  : {
217
223
  name: options.name,
224
+ url: given.url,
218
225
  // Signed in on the app's page, the harness there (a frame needs it).
219
226
  signIn: async (page) => {
220
227
  await open(page);
221
228
  await ready(page);
222
229
  },
223
- url: given.url,
224
- denied: given.denied,
225
- atSignIn: given.atSignIn,
226
- completeSignIn: given.completeSignIn,
230
+ ...(given.denied === undefined ? {} : { denied: given.denied }),
231
+ ...(given.atSignIn === undefined ? {} : { atSignIn: given.atSignIn }),
232
+ ...(given.completeSignIn === undefined ? {} : { completeSignIn: given.completeSignIn }),
233
+ ...(given.unknown === undefined
234
+ ? {}
235
+ : {
236
+ unknown: given.unknown === "derive"
237
+ ? async () => derivedUnknown(await given.url("entry-unknown"))
238
+ : given.unknown,
239
+ }),
227
240
  async frame(page, url) {
228
241
  await ready(page);
229
- const instance = served.artifact("entry", "1");
242
+ const instance = await served.artifact("entry", "1");
230
243
  const id = await invoke(page, "show", options.config(instance), instance, {
231
244
  location: { url, origin: new URL(url).origin },
232
245
  });
@@ -287,6 +300,69 @@ const URL_CASES = [
287
300
  "served.url.framed",
288
301
  ];
289
302
  const PROXY_CASES = ["served.proxy.view", "served.proxy.parent-only", "served.proxy.egress"];
303
+ const DOMAIN_CASES = [
304
+ "served.domain.origin",
305
+ "served.domain.no-reach",
306
+ "served.domain.no-top-navigation",
307
+ "served.domain.no-popups",
308
+ "served.domain.address",
309
+ "served.domain.storage-scope",
310
+ "served.domain.ticket-once",
311
+ "served.domain.frame-ancestors",
312
+ "served.domain.egress",
313
+ ];
314
+ /**
315
+ * Addresses that name nothing, under the content domain of a clean address: `www`, the bare
316
+ * domain, and a label no naming makes (P071).
317
+ */
318
+ function derivedUnknown(clean) {
319
+ const url = new URL(clean);
320
+ const domain = url.hostname.split(".").slice(1).join(".");
321
+ const port = url.port === "" ? "" : `:${url.port}`;
322
+ return ["www.", "", "zz-porthole-nothing."].map((label) => `${url.protocol}//${label}${domain}${port}/`);
323
+ }
324
+ /**
325
+ * A memo for fixtures made on demand (a page published the first time a case asks for it): one
326
+ * promise per key, per worker (P071).
327
+ */
328
+ export function onDemand(make) {
329
+ const made = new Map();
330
+ return (key) => {
331
+ let found = made.get(key);
332
+ if (found === undefined) {
333
+ found = make(key);
334
+ made.set(key, found);
335
+ // A failure is tried again by the next case, not remembered.
336
+ found.catch(() => made.delete(key));
337
+ }
338
+ return found;
339
+ };
340
+ }
341
+ /**
342
+ * The Playwright projects to run the suite on: Chromium, WebKit and Firefox, Firefox with the
343
+ * preferences its WebRTC probe needs (loopback ICE). Pass `devices` from `@playwright/test`
344
+ * (P071).
345
+ */
346
+ export function conformanceProjects(devices, options = {}) {
347
+ const all = [
348
+ { name: "chromium", use: { ...devices["Desktop Chrome"] } },
349
+ { name: "webkit", use: { ...devices["Desktop Safari"] } },
350
+ {
351
+ name: "firefox",
352
+ use: {
353
+ ...devices["Desktop Firefox"],
354
+ launchOptions: {
355
+ firefoxUserPrefs: {
356
+ "media.peerconnection.ice.loopback": true,
357
+ "media.peerconnection.ice.obfuscate_host_addresses": false,
358
+ },
359
+ },
360
+ },
361
+ },
362
+ ];
363
+ const engines = options.engines ?? ["chromium", "webkit", "firefox"];
364
+ return all.filter((project) => engines.includes(project.name));
365
+ }
290
366
  /**
291
367
  * Registers the leak and served suites against an app's real page, in a spec file of the app's
292
368
  * (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
@@ -304,38 +380,74 @@ export function defineHostConformance(test, options) {
304
380
  if (options.instances.artifact === undefined) {
305
381
  absent(["served.artifact.versions"], "the app serves no versions of a stored page");
306
382
  }
383
+ if (options.instances.shell === undefined && options.instances.artifact === undefined) {
384
+ absent(DOMAIN_CASES, "the app serves no documents on content origins (instances.shell or .artifact)");
385
+ }
307
386
  if (options.instances.app === undefined) {
308
387
  absent(URL_CASES, "the app serves no url-mode apps");
309
388
  }
310
389
  if (options.instances.proxy === undefined) {
311
390
  absent(PROXY_CASES, "the app serves no MCP Apps views");
312
391
  }
313
- typed.describe(`Porthole leak suite (${options.name})`, () => {
314
- for (const each of leakTests(hosts.leak, { skip })) {
315
- // Playwright reads the fixtures a test uses from its parameter's destructuring.
316
- typed(each.title, async ({ page, browserName }, info) => {
317
- await hosts.begin(page);
318
- await each.run({ page, browserName }, info);
319
- });
320
- }
321
- });
322
- typed.describe(`Porthole served modes (${options.name})`, () => {
323
- for (const each of servedTests(hosts.served, { skip })) {
324
- typed(each.title, async ({ page, browserName }, info) => {
325
- await hosts.begin(page);
326
- await each.run({ page, browserName }, info);
327
- });
328
- }
329
- });
330
- const entry = hosts.entry;
331
- if (entry !== null) {
332
- typed.describe(`Porthole redirect entry (${options.name})`, () => {
333
- for (const each of entryTests(entry, { skip })) {
334
- typed(each.title, async ({ page, browserName }, info) => {
392
+ // Registered as the app's own spec file's (P070): Playwright locates a test where `test()` is
393
+ // called, so `playwright test <spec>` and `<spec>:<line>` select these.
394
+ const at = callerOf(defineHostConformance);
395
+ const describeOf = Reflect.get(test, "describe");
396
+ const describe = calledFrom(describeOf, at);
397
+ const register = calledFrom(typed, at);
398
+ const suite = (title, tests) => {
399
+ describe(title, () => {
400
+ for (const each of tests) {
401
+ // Playwright reads the fixtures a test uses from its parameter's destructuring.
402
+ register(each.title, async ({ page, browserName }, info) => {
335
403
  await hosts.begin(page);
336
404
  await each.run({ page, browserName }, info);
337
405
  });
338
406
  }
339
407
  });
408
+ };
409
+ suite(`Porthole leak suite (${options.name})`, leakTests(hosts.leak, { skip }));
410
+ suite(`Porthole served modes (${options.name})`, servedTests(hosts.served, { skip }));
411
+ if (hosts.entry !== null) {
412
+ suite(`Porthole redirect entry (${options.name})`, entryTests(hosts.entry, { skip }));
413
+ }
414
+ }
415
+ /** Where a function was called from: the caller's file and line, or null. */
416
+ function callerOf(callee) {
417
+ const holder = {};
418
+ Error.captureStackTrace(holder, callee);
419
+ // The first frame is the caller's: " at file:///…/app.spec.ts:16:1" or " at fn (/…/app.spec.ts:16:1)".
420
+ const frame = (holder.stack ?? "")
421
+ .split("\n")
422
+ .map((line) => line.trim())
423
+ .find((line) => line.startsWith("at "));
424
+ const where = (frame ?? "").slice(3).replace(/^.*\((.*)\)$/u, "$1");
425
+ const found = /^(.+):(\d+):\d+$/u.exec(where);
426
+ if (found?.[1] === undefined || found[2] === undefined) {
427
+ return null;
428
+ }
429
+ try {
430
+ return {
431
+ file: found[1].startsWith("file://") ? fileURLToPath(found[1]) : found[1],
432
+ line: Number(found[2]),
433
+ };
340
434
  }
435
+ catch {
436
+ return null;
437
+ }
438
+ }
439
+ /**
440
+ * `register` (Playwright's `test` or `test.describe`), called from a function compiled as the
441
+ * caller's file and line (`vm`'s `filename` and `lineOffset`), so the tests it makes are located
442
+ * there. Without a caller, `register` itself.
443
+ */
444
+ function calledFrom(register, at) {
445
+ if (at === null) {
446
+ return (title, body) => register(title, body);
447
+ }
448
+ const call = runInThisContext("(register, title, body) => register(title, body)", {
449
+ filename: at.file,
450
+ lineOffset: Math.max(0, at.line - 1),
451
+ });
452
+ return (title, body) => call(register, title, body);
341
453
  }
@@ -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 { defineHostConformance, harnessScript, hostConformance, type HostConformance, type HostConformanceOptions, } from "./host-kit.ts";
105
+ export { conformancePage, conformanceProjects, defineHostConformance, harnessScript, hostConformance, onDemand, type ConformanceProject, type HostConformance, type HostConformanceOptions, } from "./host-kit.ts";
@@ -5,4 +5,4 @@ export { defineServedSuite, servedTests, } from "./served.js";
5
5
  // Redirect entry's cases (P068).
6
6
  export { entryTests } from "./entry.js";
7
7
  // The runner an app points at its real page and issue endpoint (P066).
8
- export { defineHostConformance, harnessScript, hostConformance, } from "./host-kit.js";
8
+ export { conformancePage, conformanceProjects, defineHostConformance, harnessScript, hostConformance, onDemand, } from "./host-kit.js";
@@ -37,6 +37,8 @@ function watch(page) {
37
37
  /** A WAV of silence, small enough to inline. */
38
38
  const SILENCE = "data:audio/wav;base64,UklGRkQDAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YSADAACAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgA==";
39
39
  const RECORDER = "<script>window.r = {};</script>";
40
+ /** A one-pixel GIF, inline. */
41
+ const PIXEL = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
40
42
  export const LIMIT_PROBES = [
41
43
  {
42
44
  id: "14.fill",
@@ -166,16 +168,27 @@ export const LIMIT_PROBES = [
166
168
  title: "assets inline as data: URLs and CSS in a <style> work where nothing outside is open",
167
169
  async run(context) {
168
170
  const canary = await context.http();
169
- const pixel = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
170
171
  const display = await context.launch({
171
172
  config: inline(),
172
173
  content: attack(`
173
174
  const image = document.getElementById("inline");
174
175
  r.inline = await new Promise((resolve) => { if (image.complete && image.naturalWidth > 0) resolve("loaded"); image.addEventListener("load", () => resolve("loaded")); image.addEventListener("error", () => resolve("failed")); setTimeout(() => resolve("pending"), 3000); });
175
- r.styled = getComputedStyle(document.getElementById("styled")).width;`, `<style>#styled { width: 37px }</style><div id="styled"></div><img id="inline" src="${pixel}"><img src="${canary.origin}/outside.png">`),
176
+ r.styled = getComputedStyle(document.getElementById("styled")).width;
177
+ if (r.inline !== "loaded") {
178
+ r.dataBlocked = await inheritedBlocks("data", () => { new Image().src = ${js(PIXEL)}; });
179
+ }
180
+ if (r.styled !== "37px") {
181
+ r.styleBlocked = await inheritedBlocks("inline", () => { const style = document.createElement("style"); style.textContent = "#styled { width: 38px }"; document.head.append(style); });
182
+ }`, `<style>#styled { width: 37px }</style><div id="styled"></div><img id="inline" src="${PIXEL}"><img src="${canary.origin}/outside.png">`),
176
183
  });
177
184
  const verdict = await context.result(display);
178
185
  await settle();
186
+ // The frame's own policy allows data: images and inline styles: a block of either is the
187
+ // page's own CSP, which an opaque frame inherits (P058, P071).
188
+ if ((verdict.inline !== "loaded" && verdict.dataBlocked === true) ||
189
+ (verdict.styled !== "37px" && verdict.styleBlocked === true)) {
190
+ context.inapplicable("the page's own CSP, which an opaque frame inherits, blocks data: images or inline styles (img-src, style-src): opaque content here can't inline its assets, whatever its config");
191
+ }
179
192
  expect(verdict).toMatchObject({ inline: "loaded", styled: "37px" });
180
193
  expect(canary.requests()).toEqual([]);
181
194
  },
@@ -0,0 +1,6 @@
1
+ /**
2
+ * The stored page the served and entry cases ask for, version "1" or "2": what an app's
3
+ * `instances.artifact(scope, version)` must serve, exactly (P071). Free of Playwright, so an app
4
+ * in test mode serves it from `@botiverse/porthole/server`.
5
+ */
6
+ export declare function conformancePage(version: "1" | "2"): string;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * The stored page the served and entry cases ask for, version "1" or "2": what an app's
3
+ * `instances.artifact(scope, version)` must serve, exactly (P071). Free of Playwright, so an app
4
+ * in test mode serves it from `@botiverse/porthole/server`.
5
+ */
6
+ export function conformancePage(version) {
7
+ return `<!doctype html><html><head><title>Page</title></head><body><main id="artifact">version ${version}</main><script>document.documentElement.dataset.rtc = typeof RTCPeerConnection;</script></body></html>`;
8
+ }
@@ -53,20 +53,20 @@ export interface ServedConformanceHost {
53
53
  /** How many requests reached `canary(name)`. */
54
54
  canaryHits(name: string): Promise<number>;
55
55
  /** A served shell (domain isolation) for `scope`. */
56
- shell(scope: string): InstanceRef;
56
+ shell(scope: string): InstanceRef | Promise<InstanceRef>;
57
57
  /**
58
58
  * A url-mode app for `scope`: its page loads a script from its own origin that sets
59
59
  * `document.documentElement.dataset.app = "ready"`.
60
60
  */
61
- app(scope: string): InstanceRef;
61
+ app(scope: string): InstanceRef | Promise<InstanceRef>;
62
62
  /**
63
63
  * A stored artifact page (domain isolation) for `scope`: version `"1"` and `"2"` of one page,
64
64
  * each with `<main id="artifact">version N</main>` and a script that records
65
65
  * `document.documentElement.dataset.rtc = typeof RTCPeerConnection`.
66
66
  */
67
- artifact(scope: string, version: "1" | "2"): InstanceRef;
67
+ artifact(scope: string, version: "1" | "2"): InstanceRef | Promise<InstanceRef>;
68
68
  /** The MCP Apps sandbox proxy (domain isolation) for `scope`, opening the view's `egress`. */
69
- proxy(scope: string, egress?: EgressConfig): InstanceRef;
69
+ proxy(scope: string, egress?: EgressConfig): InstanceRef | Promise<InstanceRef>;
70
70
  }
71
71
  export interface ServedSuiteOptions {
72
72
  /** Case ids to skip, each with the reason (shown in the report). */
@@ -112,7 +112,7 @@ export function servedTests(host, options = {}) {
112
112
  ["url", (scope) => host.app(scope)],
113
113
  ];
114
114
  // A served shell draws (and has a height to click in) once its host gives it content.
115
- const showMode = (page, mode, instance) => host.show(page, instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
115
+ const showMode = async (page, mode, instance) => host.show(page, await instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
116
116
  for (const [mode, instance] of modes) {
117
117
  define(`served.${mode}.origin`, "content runs on its own origin, never the host's", async ({ page }) => {
118
118
  const display = await showMode(page, mode, instance(`${mode}-origin`));
@@ -190,7 +190,9 @@ export function servedTests(host, options = {}) {
190
190
  });
191
191
  }
192
192
  define("served.domain.address", "a served frame's address is its own, carrying at most Porthole's ticket: never the app's", async ({ page }) => {
193
- const display = await host.show(page, host.shell("address"), { content: SHELL_CONTENT });
193
+ const display = await host.show(page, await host.shell("address"), {
194
+ content: SHELL_CONTENT,
195
+ });
194
196
  const frame = await display.frame();
195
197
  const seen = await frame.evaluate(() => ({
196
198
  origin: location.origin,
@@ -203,19 +205,25 @@ export function servedTests(host, options = {}) {
203
205
  expect(seen.origin).not.toBe(new URL(page.url()).origin);
204
206
  });
205
207
  define("served.domain.storage-scope", "storage persists within a scope and is never shared across scopes", async ({ page }) => {
206
- const first = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
208
+ const first = await host.show(page, await host.shell("scope-a"), {
209
+ content: SHELL_CONTENT,
210
+ });
207
211
  await (await first.frame()).evaluate(() => localStorage.setItem("kept", "a"));
208
212
  await first.destroy();
209
- const again = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
213
+ const again = await host.show(page, await host.shell("scope-a"), {
214
+ content: SHELL_CONTENT,
215
+ });
210
216
  expect(await (await again.frame()).evaluate(() => localStorage.getItem("kept"))).toBe("a");
211
217
  expect(again.origin).toBe(first.origin);
212
- const other = await host.show(page, host.shell("scope-b"), { content: SHELL_CONTENT });
218
+ const other = await host.show(page, await host.shell("scope-b"), {
219
+ content: SHELL_CONTENT,
220
+ });
213
221
  expect(other.origin).not.toBe(first.origin);
214
222
  expect(await (await other.frame()).evaluate(() => localStorage.getItem("kept"))).toBeNull();
215
223
  });
216
224
  define("served.artifact.versions", "each version of a page shows as stored, on its scope's origin, hardened before it runs", async ({ page }) => {
217
- const one = await host.show(page, host.artifact("artifact-scope", "1"));
218
- const two = await host.show(page, host.artifact("artifact-scope", "2"));
225
+ const one = await host.show(page, await host.artifact("artifact-scope", "1"));
226
+ const two = await host.show(page, await host.artifact("artifact-scope", "2"));
219
227
  expect(two.origin).toBe(one.origin);
220
228
  for (const [display, version] of [
221
229
  [one, "1"],
@@ -227,7 +235,7 @@ export function servedTests(host, options = {}) {
227
235
  }
228
236
  });
229
237
  define("served.domain.ticket-once", "a ticket opens its content once; without it there is nothing", async ({ page, browserName }) => {
230
- const location = await host.locate(host.shell("ticket-once"));
238
+ const location = await host.locate(await host.shell("ticket-once"));
231
239
  const first = await page.goto(location.url);
232
240
  expect(first?.status()).toBe(200);
233
241
  // A fresh browser state: no cookie, only the used ticket.
@@ -243,7 +251,7 @@ export function servedTests(host, options = {}) {
243
251
  }
244
252
  });
245
253
  define("served.domain.frame-ancestors", "only the host's origins may frame content", async ({ page }) => {
246
- const location = await host.locate(host.shell("foreign"));
254
+ const location = await host.locate(await host.shell("foreign"));
247
255
  await host.frameFromForeignOrigin(page, location.url);
248
256
  await page.waitForTimeout(SETTLE_MS);
249
257
  for (const frame of page.frames().slice(1)) {
@@ -264,7 +272,9 @@ export function servedTests(host, options = {}) {
264
272
  }
265
273
  });
266
274
  define("served.domain.egress", "the CSP in the document's headers closes egress; only what the config opens to any https site (images, media) reaches it", async ({ page }) => {
267
- const display = await host.show(page, host.shell("egress"), { content: SHELL_CONTENT });
275
+ const display = await host.show(page, await host.shell("egress"), {
276
+ content: SHELL_CONTENT,
277
+ });
268
278
  const frame = await display.frame();
269
279
  const kinds = ["fetch", "img", "media", "script", "style", "frame"];
270
280
  const urls = Object.fromEntries(await Promise.all(kinds.map(async (kind) => [kind, await host.canary(`egress-${kind}`)])));
@@ -343,7 +353,7 @@ export function servedTests(host, options = {}) {
343
353
  .poll(async () => methodsOf(await display.received()))
344
354
  .toContain(MCP_APPS_METHODS.sandboxProxyReady);
345
355
  define("served.proxy.view", "the sandbox proxy becomes the view, hardened, talking to its host directly", async ({ page }) => {
346
- const display = await host.show(page, host.proxy("proxy-view"));
356
+ const display = await host.show(page, await host.proxy("proxy-view"));
347
357
  await proxyReady(display);
348
358
  const canary = await host.canary("proxy-undeclared");
349
359
  await display.post(resourceReady(PROBE_VIEW(canary)));
@@ -357,7 +367,7 @@ export function servedTests(host, options = {}) {
357
367
  expect(await host.canaryHits("proxy-undeclared")).toBe(0);
358
368
  });
359
369
  define("served.proxy.parent-only", "the sandbox proxy takes a view only from its host", async ({ page }) => {
360
- const display = await host.show(page, host.proxy("proxy-parent"));
370
+ const display = await host.show(page, await host.proxy("proxy-parent"));
361
371
  await proxyReady(display);
362
372
  const frame = await display.frame();
363
373
  await frame.evaluate((message) => window.postMessage(message, "*"), resourceReady('<p id="view">Not from the host.</p>'));
@@ -366,7 +376,7 @@ export function servedTests(host, options = {}) {
366
376
  });
367
377
  define("served.proxy.egress", "the sandbox proxy opens what the view declares, and nothing else", async ({ page }) => {
368
378
  const canary = await host.canary("proxy-declared");
369
- const display = await host.show(page, host.proxy("proxy-egress", { connect: [new URL(canary).origin] }));
379
+ const display = await host.show(page, await host.proxy("proxy-egress", { connect: [new URL(canary).origin] }));
370
380
  await proxyReady(display);
371
381
  await display.post(resourceReady(PROBE_VIEW(canary)));
372
382
  const frame = await display.frame();
@@ -374,7 +384,7 @@ export function servedTests(host, options = {}) {
374
384
  expect(await host.canaryHits("proxy-declared")).toBe(1);
375
385
  });
376
386
  define("served.url.ticket", "an app shows nothing to a browser without its ticket's cookie", async ({ page }) => {
377
- const location = await host.locate(host.app("url-ticket"));
387
+ const location = await host.locate(await host.app("url-ticket"));
378
388
  // A fresh browser: no cookie of the content's, none of the app's. Porthole refuses it, or
379
389
  // (redirect entry, P068) hands it to the app's authorize route, which asks it to sign in.
380
390
  const fresh = await page.context().browser().newContext();
@@ -390,7 +400,7 @@ export function servedTests(host, options = {}) {
390
400
  }
391
401
  });
392
402
  define("served.url.tab", "an app opened on a tab of its own runs, its requests riding on its cookie", async ({ page }) => {
393
- const location = await host.locate(host.app("url-tab"));
403
+ const location = await host.locate(await host.app("url-tab"));
394
404
  await page.goto(location.url);
395
405
  await expect(page.locator("html")).toHaveAttribute("data-app", "ready");
396
406
  });
@@ -398,7 +408,7 @@ export function servedTests(host, options = {}) {
398
408
  // Measured (P025): WebKit keeps no cookie in a cross-site frame, partitioned or not, so a
399
409
  // framed app's subresources are refused there; such hosts open the app on a tab.
400
410
  typed.fail(browserName === "webkit", "WebKit keeps no cookie in a cross-site frame");
401
- const display = await host.show(page, host.app("url-framed"));
411
+ const display = await host.show(page, await host.app("url-framed"));
402
412
  const frame = await display.frame();
403
413
  await expect
404
414
  .poll(() => frame.evaluate(() => document.documentElement.dataset.app ?? null), {
@@ -58,9 +58,12 @@ export interface MountOptions {
58
58
  /** The height to start at, before the content reports its own. */
59
59
  readonly initialHeightPx?: number;
60
60
  /**
61
- * Fill the container (give it a height) instead of taking the content's height: the content
62
- * scrolls inside its frame (an artifact viewer's page). The content's sizes are still reported
63
- * (`resize`). A url-mode app always fills.
61
+ * Fill the container (give it a height) instead of taking the content's height.
62
+ *
63
+ * @deprecated Say it in the config, `layout: { kind: "fill" }`: every mount then fills, and the
64
+ * manual tells the agent so (a page that scrolls itself, `position: fixed` works). This option
65
+ * sizes only this frame, so the manual keeps saying the height follows the content (P071). A
66
+ * url-mode app always fills.
64
67
  */
65
68
  readonly fill?: boolean;
66
69
  }
@@ -102,10 +102,12 @@ export function checkFrameLocation(location, contentOrigins, hostOrigin) {
102
102
  url = new URL(location.url);
103
103
  }
104
104
  catch {
105
- throw new TypeError(`The located URL ${JSON.stringify(location.url)} is not a URL`);
105
+ throw new TypeError("The located URL is not a URL");
106
106
  }
107
107
  if (origin === null || url.origin !== location.origin) {
108
- throw new TypeError(`The located URL ${JSON.stringify(location.url)} is not on its origin ${JSON.stringify(location.origin)}`);
108
+ throw new TypeError(
109
+ // Named by its origin only: a located URL carries a ticket, which never goes in a message.
110
+ `The located URL is not on its origin ${JSON.stringify(location.origin)} (it is on ${JSON.stringify(safeOrigin(location.url))})`);
109
111
  }
110
112
  if (!contentOrigins.some((source) => originMatchesSource(location.origin, source))) {
111
113
  throw new TypeError(`The located origin ${location.origin} is not one of the config's content origins`);
@@ -115,3 +117,12 @@ export function checkFrameLocation(location, contentOrigins, hostOrigin) {
115
117
  throw new TypeError(`The located origin ${location.origin} may be the same site as the host (${hostOrigin}): content must be served from a registrable domain the host uses for nothing else`);
116
118
  }
117
119
  }
120
+ /** A URL's origin, for a message: never its path or query (a ticket). */
121
+ function safeOrigin(url) {
122
+ try {
123
+ return new URL(url).origin;
124
+ }
125
+ catch {
126
+ return "an unparsable address";
127
+ }
128
+ }
@@ -27,9 +27,17 @@ export interface NodeHost {
27
27
  readonly request: RequestListener;
28
28
  readonly upgrade: UpgradeListener;
29
29
  }
30
- /** The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). */
31
- export declare function toRequest(request: IncomingMessage, scheme: "https" | "http"): Request;
32
- /** Writes a fetch `Response` to a Node response, cookies one header each. */
30
+ /**
31
+ * The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). `signal`
32
+ * (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work.
33
+ */
34
+ export declare function toRequest(request: IncomingMessage, scheme: "https" | "http", signal?: AbortSignal): Request;
35
+ /**
36
+ * Writes a fetch `Response` to a Node response, cookies one header each (P070): it waits for the
37
+ * socket to drain before reading on (a slow client never makes it buffer the body), cancels the
38
+ * body when the client goes away (an event stream ends with the page that asked for it), and on
39
+ * an error mid-body destroys the response rather than end it looking complete.
40
+ */
33
41
  export declare function sendResponse(response: ServerResponse, answer: Response): Promise<void>;
34
42
  export declare function nodeHost<V>(content: ContentHost<V>, app: NodeHostOptions): NodeHost;
35
43
  /**
@@ -1,8 +1,11 @@
1
1
  import { request as httpRequest } from "node:http";
2
2
  import { request as httpsRequest } from "node:https";
3
3
  import { Readable } from "node:stream";
4
- /** The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). */
5
- export function toRequest(request, scheme) {
4
+ /**
5
+ * The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). `signal`
6
+ * (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work.
7
+ */
8
+ export function toRequest(request, scheme, signal) {
6
9
  const headers = new Headers();
7
10
  for (const [name, value] of Object.entries(request.headers)) {
8
11
  for (const each of Array.isArray(value) ? value : value === undefined ? [] : [value]) {
@@ -15,9 +18,20 @@ export function toRequest(request, scheme) {
15
18
  : target;
16
19
  const method = request.method ?? "GET";
17
20
  const body = method === "GET" || method === "HEAD" ? null : Readable.toWeb(request);
18
- return new Request(url, { method, headers, body, duplex: "half" });
21
+ return new Request(url, {
22
+ method,
23
+ headers,
24
+ body,
25
+ duplex: "half",
26
+ ...(signal === undefined ? {} : { signal }),
27
+ });
19
28
  }
20
- /** Writes a fetch `Response` to a Node response, cookies one header each. */
29
+ /**
30
+ * Writes a fetch `Response` to a Node response, cookies one header each (P070): it waits for the
31
+ * socket to drain before reading on (a slow client never makes it buffer the body), cancels the
32
+ * body when the client goes away (an event stream ends with the page that asked for it), and on
33
+ * an error mid-body destroys the response rather than end it looking complete.
34
+ */
21
35
  export async function sendResponse(response, answer) {
22
36
  const headers = {};
23
37
  for (const [name, value] of answer.headers) {
@@ -34,10 +48,46 @@ export async function sendResponse(response, answer) {
34
48
  response.end();
35
49
  return;
36
50
  }
37
- for await (const chunk of answer.body) {
38
- response.write(chunk);
51
+ const reader = answer.body.getReader();
52
+ let gone = false;
53
+ const leave = () => {
54
+ gone = true;
55
+ reader.cancel().catch(() => undefined);
56
+ };
57
+ // The client went away before the end: stop reading, and let the body's source know.
58
+ response.once("close", () => {
59
+ if (!response.writableFinished) {
60
+ leave();
61
+ }
62
+ });
63
+ try {
64
+ for (;;) {
65
+ const { done, value } = await reader.read();
66
+ if (done || gone) {
67
+ break;
68
+ }
69
+ if (!response.write(value)) {
70
+ await new Promise((resolve) => {
71
+ const on = () => {
72
+ response.off("drain", on);
73
+ response.off("close", on);
74
+ resolve();
75
+ };
76
+ response.on("drain", on);
77
+ response.on("close", on);
78
+ });
79
+ }
80
+ }
81
+ }
82
+ catch (error) {
83
+ // The head is sent: a body cut short must not look whole.
84
+ leave();
85
+ response.destroy(error instanceof Error ? error : new Error(String(error)));
86
+ return;
87
+ }
88
+ if (!gone) {
89
+ response.end();
39
90
  }
40
- response.end();
41
91
  }
42
92
  /** Whether a Node request's Host (or absolute-form target) is under the content domain. */
43
93
  function forContent(content, request) {
@@ -67,7 +117,15 @@ export function nodeHost(content, app) {
67
117
  app.request(request, response);
68
118
  return;
69
119
  }
70
- content.fetch(toRequest(request, scheme())).then((answer) => {
120
+ // Aborted when the client goes away first, so an upstream (a proxied app's event stream)
121
+ // stops with it.
122
+ const gone = new AbortController();
123
+ response.once("close", () => {
124
+ if (!response.writableFinished) {
125
+ gone.abort();
126
+ }
127
+ });
128
+ content.fetch(toRequest(request, scheme(), gone.signal)).then((answer) => {
71
129
  if (answer === null) {
72
130
  // A label the app routes itself.
73
131
  app.request(request, response);
@@ -75,9 +133,11 @@ export function nodeHost(content, app) {
75
133
  }
76
134
  return sendResponse(response, answer);
77
135
  }, () => {
78
- if (!response.headersSent) {
79
- response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
136
+ if (response.headersSent) {
137
+ response.destroy();
138
+ return;
80
139
  }
140
+ response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
81
141
  response.end("Content couldn't be served.");
82
142
  });
83
143
  },