@botiverse/porthole 0.2.1 → 0.2.2

package/dist/conformance/entry.d.ts

@@ -15,9 +15,15 @@ export interface EntryConformanceHost {
      * The clean address of a stored page the signed-in viewer may open (`ContentHost.urlOf`), for
      * `scope`: it draws `<main id="artifact">version 1</main>`.
      */
-    url(scope: string): string;
+    url(scope: string): string | Promise<string>;
     /** A clean address the signed-in viewer may not open. */
-    denied(scope: string): string;
+    denied(scope: string): string | Promise<string>;
+    /**
+     * Addresses on the content domain that name nothing (a label the app never assigns, the bare
+     * domain, a path no instance has): each must be Porthole's 404 there, never the app's sign-in
+     * (P070). Absent: the case is skipped.
+     */
+    unknown?(): readonly string[] | Promise<readonly string[]>;
     /** Whether `page` shows the app's own sign-in. */
     atSignIn(page: Page): Promise<boolean>;
     /** On the app's sign-in page: signs in, as a person does (and the app goes back). */

package/dist/conformance/entry.js

@@ -31,7 +31,7 @@ export function entryTests(host, options = {}) {
     };
     define("served.entry.direct", "a clean address opens directly for a signed-in viewer, and stays clean; a reload rides on its cookie", async ({ page }) => {
         await host.signIn(page);
-        const url = host.url("entry-direct");
+        const url = await host.url("entry-direct");
         await page.goto(url);
         await expect(page.locator("#artifact")).toHaveText("version 1");
         expect(page.url(), "the address bar shows the clean address, no code").toBe(url);
@@ -46,7 +46,7 @@ export function entryTests(host, options = {}) {
         expect(entries, "a reload needs no entry").toEqual([]);
     });
     define("served.entry.signed-out", "signed out, a clean address goes to the app's own sign-in, then back to the content", async ({ page }) => {
-        const url = host.url("entry-signed-out");
+        const url = await host.url("entry-signed-out");
         await page.goto(url);
         expect(await host.atSignIn(page), "the app's sign-in").toBe(true);
         expect(await shows(page)).toBe(false);
@@ -56,15 +56,30 @@ export function entryTests(host, options = {}) {
     });
     define("served.entry.denied", "a viewer without access gets the app's refusal, never the content", async ({ page }) => {
         await host.signIn(page);
-        const url = host.denied("entry-denied");
+        const url = await host.denied("entry-denied");
         const answer = await page.goto(url);
         expect(answer?.status()).toBe(403);
         expect(await shows(page)).toBe(false);
         expect(new URL(page.url()).origin, "the refusal is the app's").not.toBe(new URL(url).origin);
     });
+    define("served.entry.unknown", "an address that names nothing is a 404 on the content domain: never a trip to the app's sign-in", async ({ page }, info) => {
+        info.skip(host.unknown === undefined, "the host gave no addresses that name nothing (unknown)");
+        const request = page.context().request;
+        for (const url of (await host.unknown?.()) ?? []) {
+            const answer = await request.get(url, {
+                maxRedirects: 0,
+                headers: { "sec-fetch-dest": "document" },
+            });
+            expect(answer.status(), url).toBe(404);
+            expect(answer.headers().location, url).toBeUndefined();
+            const opened = await page.goto(url);
+            expect(opened?.status(), url).toBe(404);
+            expect(new URL(page.url()).origin, url).toBe(new URL(url).origin);
+        }
+    });
     define("served.entry.code-once", "an entry code works once: replayed, it opens nothing", async ({ page }) => {
         await host.signIn(page);
-        const code = await codeFor(page, host.url("entry-once"));
+        const code = await codeFor(page, await host.url("entry-once"));
         const request = page.context().request;
         const top = { "sec-fetch-dest": "document" };
         const first = await request.get(code, { maxRedirects: 0, headers: top });
@@ -75,8 +90,8 @@ export function entryTests(host, options = {}) {
     });
     define("served.entry.code-elsewhere", "an entry code taken to another instance's origin opens nothing there", async ({ page }) => {
         await host.signIn(page);
-        const code = new URL(await codeFor(page, host.url("entry-mine")));
-        const other = new URL(host.url("entry-theirs"));
+        const code = new URL(await codeFor(page, await host.url("entry-mine")));
+        const other = new URL(await host.url("entry-theirs"));
         const request = page.context().request;
         const answer = await request.get(`${other.origin}${code.pathname}${code.search}`, {
             maxRedirects: 0,
@@ -87,7 +102,7 @@ export function entryTests(host, options = {}) {
     });
     define("served.entry.framed", "a clean address in a frame shows the content where the browser keeps the cookies, else asks for a tab: never the app's sign-in", async ({ page, browserName }, info) => {
         await host.signIn(page);
-        const shown = await host.frame(page, host.url("entry-framed"));
+        const shown = await host.frame(page, await host.url("entry-framed"));
         const outcome = await shown.outcome();
         const frame = await shown.frame();
         expect(await host.atSignIn(page)).toBe(false);
@@ -110,7 +125,7 @@ export function entryTests(host, options = {}) {
         await host.signIn(page);
         // The app's page stays; the browser forgets every sign-in.
         await page.context().clearCookies();
-        const shown = await host.frame(page, host.url("entry-framed-out"));
+        const shown = await host.frame(page, await host.url("entry-framed-out"));
         expect(await shown.outcome()).toMatchObject({ state: "blocked", reason: "sign-in" });
         const frame = await shown.frame();
         await expect(frame.locator("h1")).toHaveText("Open this in a new tab to sign in");

package/dist/conformance/host-kit.d.ts

@@ -50,14 +50,19 @@ export interface HostConformanceOptions {
      * signed in and out, and in a frame.
      */
     readonly entry?: {
-        /** The clean address of `instances.artifact(scope, "1")` (`ContentHost.urlOf`). */
-        readonly url: (scope: string) => string;
+        /**
+         * The clean address of `instances.artifact(scope, "1")` (`ContentHost.urlOf`); may publish it
+         * on demand.
+         */
+        readonly url: (scope: string) => string | Promise<string>;
         /** A clean address the signed-in viewer may not open. */
-        readonly denied: (scope: string) => string;
+        readonly denied: (scope: string) => string | Promise<string>;
         /** Whether `page` shows the app's own sign-in. */
         readonly atSignIn: (page: Page) => Promise<boolean>;
         /** On the app's sign-in page: signs in, as a person does. */
         readonly completeSignIn: (page: Page) => Promise<void>;
+        /** Addresses on the content domain that name nothing: each a 404 there (P070). */
+        readonly unknown?: () => readonly string[] | Promise<readonly string[]>;
     };
     /** Case ids to skip, each with its reason (shown in the report). */
     readonly skip?: Readonly<Record<string, string>>;

package/dist/conformance/host-kit.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { runInThisContext } from "node:vm";
 import { expect } from "@playwright/test";
 import { entryTests } from "./entry.js";
 import { leakTests } from "./probes.js";
@@ -224,9 +225,10 @@ export function hostConformance(options) {
             denied: given.denied,
             atSignIn: given.atSignIn,
             completeSignIn: given.completeSignIn,
+            ...(given.unknown === undefined ? {} : { unknown: given.unknown }),
             async frame(page, url) {
                 await ready(page);
-                const instance = served.artifact("entry", "1");
+                const instance = await served.artifact("entry", "1");
                 const id = await invoke(page, "show", options.config(instance), instance, {
                     location: { url, origin: new URL(url).origin },
                 });
@@ -310,32 +312,65 @@ export function defineHostConformance(test, options) {
     if (options.instances.proxy === undefined) {
         absent(PROXY_CASES, "the app serves no MCP Apps views");
     }
-    typed.describe(`Porthole leak suite (${options.name})`, () => {
-        for (const each of leakTests(hosts.leak, { skip })) {
-            // Playwright reads the fixtures a test uses from its parameter's destructuring.
-            typed(each.title, async ({ page, browserName }, info) => {
-                await hosts.begin(page);
-                await each.run({ page, browserName }, info);
-            });
-        }
-    });
-    typed.describe(`Porthole served modes (${options.name})`, () => {
-        for (const each of servedTests(hosts.served, { skip })) {
-            typed(each.title, async ({ page, browserName }, info) => {
-                await hosts.begin(page);
-                await each.run({ page, browserName }, info);
-            });
-        }
-    });
-    const entry = hosts.entry;
-    if (entry !== null) {
-        typed.describe(`Porthole redirect entry (${options.name})`, () => {
-            for (const each of entryTests(entry, { skip })) {
-                typed(each.title, async ({ page, browserName }, info) => {
+    // Registered as the app's own spec file's (P070): Playwright locates a test where `test()` is
+    // called, so `playwright test <spec>` and `<spec>:<line>` select these.
+    const at = callerOf(defineHostConformance);
+    const describeOf = Reflect.get(test, "describe");
+    const describe = calledFrom(describeOf, at);
+    const register = calledFrom(typed, at);
+    const suite = (title, tests) => {
+        describe(title, () => {
+            for (const each of tests) {
+                // Playwright reads the fixtures a test uses from its parameter's destructuring.
+                register(each.title, async ({ page, browserName }, info) => {
                     await hosts.begin(page);
                     await each.run({ page, browserName }, info);
                 });
             }
         });
+    };
+    suite(`Porthole leak suite (${options.name})`, leakTests(hosts.leak, { skip }));
+    suite(`Porthole served modes (${options.name})`, servedTests(hosts.served, { skip }));
+    if (hosts.entry !== null) {
+        suite(`Porthole redirect entry (${options.name})`, entryTests(hosts.entry, { skip }));
+    }
+}
+/** Where a function was called from: the caller's file and line, or null. */
+function callerOf(callee) {
+    const holder = {};
+    Error.captureStackTrace(holder, callee);
+    // The first frame is the caller's: "    at file:///…/app.spec.ts:16:1" or "    at fn (/…/app.spec.ts:16:1)".
+    const frame = (holder.stack ?? "")
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line.startsWith("at "));
+    const where = (frame ?? "").slice(3).replace(/^.*\((.*)\)$/u, "$1");
+    const found = /^(.+):(\d+):\d+$/u.exec(where);
+    if (found?.[1] === undefined || found[2] === undefined) {
+        return null;
     }
+    try {
+        return {
+            file: found[1].startsWith("file://") ? fileURLToPath(found[1]) : found[1],
+            line: Number(found[2]),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `register` (Playwright's `test` or `test.describe`), called from a function compiled as the
+ * caller's file and line (`vm`'s `filename` and `lineOffset`), so the tests it makes are located
+ * there. Without a caller, `register` itself.
+ */
+function calledFrom(register, at) {
+    if (at === null) {
+        return (title, body) => register(title, body);
+    }
+    const call = runInThisContext("(register, title, body) => register(title, body)", {
+        filename: at.file,
+        lineOffset: Math.max(0, at.line - 1),
+    });
+    return (title, body) => call(register, title, body);
 }

package/dist/conformance/served.d.ts

@@ -53,20 +53,20 @@ export interface ServedConformanceHost {
     /** How many requests reached `canary(name)`. */
     canaryHits(name: string): Promise<number>;
     /** A served shell (domain isolation) for `scope`. */
-    shell(scope: string): InstanceRef;
+    shell(scope: string): InstanceRef | Promise<InstanceRef>;
     /**
      * A url-mode app for `scope`: its page loads a script from its own origin that sets
      * `document.documentElement.dataset.app = "ready"`.
      */
-    app(scope: string): InstanceRef;
+    app(scope: string): InstanceRef | Promise<InstanceRef>;
     /**
      * A stored artifact page (domain isolation) for `scope`: version `"1"` and `"2"` of one page,
      * each with `<main id="artifact">version N</main>` and a script that records
      * `document.documentElement.dataset.rtc = typeof RTCPeerConnection`.
      */
-    artifact(scope: string, version: "1" | "2"): InstanceRef;
+    artifact(scope: string, version: "1" | "2"): InstanceRef | Promise<InstanceRef>;
     /** The MCP Apps sandbox proxy (domain isolation) for `scope`, opening the view's `egress`. */
-    proxy(scope: string, egress?: EgressConfig): InstanceRef;
+    proxy(scope: string, egress?: EgressConfig): InstanceRef | Promise<InstanceRef>;
 }
 export interface ServedSuiteOptions {
     /** Case ids to skip, each with the reason (shown in the report). */

package/dist/conformance/served.js

@@ -112,7 +112,7 @@ export function servedTests(host, options = {}) {
             ["url", (scope) => host.app(scope)],
         ];
         // A served shell draws (and has a height to click in) once its host gives it content.
-        const showMode = (page, mode, instance) => host.show(page, instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
+        const showMode = async (page, mode, instance) => host.show(page, await instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
         for (const [mode, instance] of modes) {
             define(`served.${mode}.origin`, "content runs on its own origin, never the host's", async ({ page }) => {
                 const display = await showMode(page, mode, instance(`${mode}-origin`));
@@ -190,7 +190,9 @@ export function servedTests(host, options = {}) {
             });
         }
         define("served.domain.address", "a served frame's address is its own, carrying at most Porthole's ticket: never the app's", async ({ page }) => {
-            const display = await host.show(page, host.shell("address"), { content: SHELL_CONTENT });
+            const display = await host.show(page, await host.shell("address"), {
+                content: SHELL_CONTENT,
+            });
             const frame = await display.frame();
             const seen = await frame.evaluate(() => ({
                 origin: location.origin,
@@ -203,19 +205,25 @@ export function servedTests(host, options = {}) {
             expect(seen.origin).not.toBe(new URL(page.url()).origin);
         });
         define("served.domain.storage-scope", "storage persists within a scope and is never shared across scopes", async ({ page }) => {
-            const first = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
+            const first = await host.show(page, await host.shell("scope-a"), {
+                content: SHELL_CONTENT,
+            });
             await (await first.frame()).evaluate(() => localStorage.setItem("kept", "a"));
             await first.destroy();
-            const again = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
+            const again = await host.show(page, await host.shell("scope-a"), {
+                content: SHELL_CONTENT,
+            });
             expect(await (await again.frame()).evaluate(() => localStorage.getItem("kept"))).toBe("a");
             expect(again.origin).toBe(first.origin);
-            const other = await host.show(page, host.shell("scope-b"), { content: SHELL_CONTENT });
+            const other = await host.show(page, await host.shell("scope-b"), {
+                content: SHELL_CONTENT,
+            });
             expect(other.origin).not.toBe(first.origin);
             expect(await (await other.frame()).evaluate(() => localStorage.getItem("kept"))).toBeNull();
         });
         define("served.artifact.versions", "each version of a page shows as stored, on its scope's origin, hardened before it runs", async ({ page }) => {
-            const one = await host.show(page, host.artifact("artifact-scope", "1"));
-            const two = await host.show(page, host.artifact("artifact-scope", "2"));
+            const one = await host.show(page, await host.artifact("artifact-scope", "1"));
+            const two = await host.show(page, await host.artifact("artifact-scope", "2"));
             expect(two.origin).toBe(one.origin);
             for (const [display, version] of [
                 [one, "1"],
@@ -227,7 +235,7 @@ export function servedTests(host, options = {}) {
             }
         });
         define("served.domain.ticket-once", "a ticket opens its content once; without it there is nothing", async ({ page, browserName }) => {
-            const location = await host.locate(host.shell("ticket-once"));
+            const location = await host.locate(await host.shell("ticket-once"));
             const first = await page.goto(location.url);
             expect(first?.status()).toBe(200);
             // A fresh browser state: no cookie, only the used ticket.
@@ -243,7 +251,7 @@ export function servedTests(host, options = {}) {
             }
         });
         define("served.domain.frame-ancestors", "only the host's origins may frame content", async ({ page }) => {
-            const location = await host.locate(host.shell("foreign"));
+            const location = await host.locate(await host.shell("foreign"));
             await host.frameFromForeignOrigin(page, location.url);
             await page.waitForTimeout(SETTLE_MS);
             for (const frame of page.frames().slice(1)) {
@@ -264,7 +272,9 @@ export function servedTests(host, options = {}) {
             }
         });
         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 }) => {
-            const display = await host.show(page, host.shell("egress"), { content: SHELL_CONTENT });
+            const display = await host.show(page, await host.shell("egress"), {
+                content: SHELL_CONTENT,
+            });
             const frame = await display.frame();
             const kinds = ["fetch", "img", "media", "script", "style", "frame"];
             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 = {}) {
             .poll(async () => methodsOf(await display.received()))
             .toContain(MCP_APPS_METHODS.sandboxProxyReady);
         define("served.proxy.view", "the sandbox proxy becomes the view, hardened, talking to its host directly", async ({ page }) => {
-            const display = await host.show(page, host.proxy("proxy-view"));
+            const display = await host.show(page, await host.proxy("proxy-view"));
             await proxyReady(display);
             const canary = await host.canary("proxy-undeclared");
             await display.post(resourceReady(PROBE_VIEW(canary)));
@@ -357,7 +367,7 @@ export function servedTests(host, options = {}) {
             expect(await host.canaryHits("proxy-undeclared")).toBe(0);
         });
         define("served.proxy.parent-only", "the sandbox proxy takes a view only from its host", async ({ page }) => {
-            const display = await host.show(page, host.proxy("proxy-parent"));
+            const display = await host.show(page, await host.proxy("proxy-parent"));
             await proxyReady(display);
             const frame = await display.frame();
             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 = {}) {
         });
         define("served.proxy.egress", "the sandbox proxy opens what the view declares, and nothing else", async ({ page }) => {
             const canary = await host.canary("proxy-declared");
-            const display = await host.show(page, host.proxy("proxy-egress", { connect: [new URL(canary).origin] }));
+            const display = await host.show(page, await host.proxy("proxy-egress", { connect: [new URL(canary).origin] }));
             await proxyReady(display);
             await display.post(resourceReady(PROBE_VIEW(canary)));
             const frame = await display.frame();
@@ -374,7 +384,7 @@ export function servedTests(host, options = {}) {
             expect(await host.canaryHits("proxy-declared")).toBe(1);
         });
         define("served.url.ticket", "an app shows nothing to a browser without its ticket's cookie", async ({ page }) => {
-            const location = await host.locate(host.app("url-ticket"));
+            const location = await host.locate(await host.app("url-ticket"));
             // A fresh browser: no cookie of the content's, none of the app's. Porthole refuses it, or
             // (redirect entry, P068) hands it to the app's authorize route, which asks it to sign in.
             const fresh = await page.context().browser().newContext();
@@ -390,7 +400,7 @@ export function servedTests(host, options = {}) {
             }
         });
         define("served.url.tab", "an app opened on a tab of its own runs, its requests riding on its cookie", async ({ page }) => {
-            const location = await host.locate(host.app("url-tab"));
+            const location = await host.locate(await host.app("url-tab"));
             await page.goto(location.url);
             await expect(page.locator("html")).toHaveAttribute("data-app", "ready");
         });
@@ -398,7 +408,7 @@ export function servedTests(host, options = {}) {
             // Measured (P025): WebKit keeps no cookie in a cross-site frame, partitioned or not, so a
             // framed app's subresources are refused there; such hosts open the app on a tab.
             typed.fail(browserName === "webkit", "WebKit keeps no cookie in a cross-site frame");
-            const display = await host.show(page, host.app("url-framed"));
+            const display = await host.show(page, await host.app("url-framed"));
             const frame = await display.frame();
             await expect
                 .poll(() => frame.evaluate(() => document.documentElement.dataset.app ?? null), {

package/dist/node/index.d.ts

@@ -27,9 +27,17 @@ export interface NodeHost {
     readonly request: RequestListener;
     readonly upgrade: UpgradeListener;
 }
-/** The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). */
-export declare function toRequest(request: IncomingMessage, scheme: "https" | "http"): Request;
-/** Writes a fetch `Response` to a Node response, cookies one header each. */
+/**
+ * The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). `signal`
+ * (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work.
+ */
+export declare function toRequest(request: IncomingMessage, scheme: "https" | "http", signal?: AbortSignal): Request;
+/**
+ * Writes a fetch `Response` to a Node response, cookies one header each (P070): it waits for the
+ * socket to drain before reading on (a slow client never makes it buffer the body), cancels the
+ * body when the client goes away (an event stream ends with the page that asked for it), and on
+ * an error mid-body destroys the response rather than end it looking complete.
+ */
 export declare function sendResponse(response: ServerResponse, answer: Response): Promise<void>;
 export declare function nodeHost<V>(content: ContentHost<V>, app: NodeHostOptions): NodeHost;
 /**

package/dist/node/index.js

@@ -1,8 +1,11 @@
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { Readable } from "node:stream";
-/** The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). */
-export function toRequest(request, scheme) {
+/**
+ * The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). `signal`
+ * (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work.
+ */
+export function toRequest(request, scheme, signal) {
     const headers = new Headers();
     for (const [name, value] of Object.entries(request.headers)) {
         for (const each of Array.isArray(value) ? value : value === undefined ? [] : [value]) {
@@ -15,9 +18,20 @@ export function toRequest(request, scheme) {
         : target;
     const method = request.method ?? "GET";
     const body = method === "GET" || method === "HEAD" ? null : Readable.toWeb(request);
-    return new Request(url, { method, headers, body, duplex: "half" });
+    return new Request(url, {
+        method,
+        headers,
+        body,
+        duplex: "half",
+        ...(signal === undefined ? {} : { signal }),
+    });
 }
-/** Writes a fetch `Response` to a Node response, cookies one header each. */
+/**
+ * Writes a fetch `Response` to a Node response, cookies one header each (P070): it waits for the
+ * socket to drain before reading on (a slow client never makes it buffer the body), cancels the
+ * body when the client goes away (an event stream ends with the page that asked for it), and on
+ * an error mid-body destroys the response rather than end it looking complete.
+ */
 export async function sendResponse(response, answer) {
     const headers = {};
     for (const [name, value] of answer.headers) {
@@ -34,10 +48,46 @@ export async function sendResponse(response, answer) {
         response.end();
         return;
     }
-    for await (const chunk of answer.body) {
-        response.write(chunk);
+    const reader = answer.body.getReader();
+    let gone = false;
+    const leave = () => {
+        gone = true;
+        reader.cancel().catch(() => undefined);
+    };
+    // The client went away before the end: stop reading, and let the body's source know.
+    response.once("close", () => {
+        if (!response.writableFinished) {
+            leave();
+        }
+    });
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done || gone) {
+                break;
+            }
+            if (!response.write(value)) {
+                await new Promise((resolve) => {
+                    const on = () => {
+                        response.off("drain", on);
+                        response.off("close", on);
+                        resolve();
+                    };
+                    response.on("drain", on);
+                    response.on("close", on);
+                });
+            }
+        }
+    }
+    catch (error) {
+        // The head is sent: a body cut short must not look whole.
+        leave();
+        response.destroy(error instanceof Error ? error : new Error(String(error)));
+        return;
+    }
+    if (!gone) {
+        response.end();
     }
-    response.end();
 }
 /** Whether a Node request's Host (or absolute-form target) is under the content domain. */
 function forContent(content, request) {
@@ -67,7 +117,15 @@ export function nodeHost(content, app) {
                 app.request(request, response);
                 return;
             }
-            content.fetch(toRequest(request, scheme())).then((answer) => {
+            // Aborted when the client goes away first, so an upstream (a proxied app's event stream)
+            // stops with it.
+            const gone = new AbortController();
+            response.once("close", () => {
+                if (!response.writableFinished) {
+                    gone.abort();
+                }
+            });
+            content.fetch(toRequest(request, scheme(), gone.signal)).then((answer) => {
                 if (answer === null) {
                     // A label the app routes itself.
                     app.request(request, response);
@@ -75,9 +133,11 @@ export function nodeHost(content, app) {
                 }
                 return sendResponse(response, answer);
             }, () => {
-                if (!response.headersSent) {
-                    response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+                if (response.headersSent) {
+                    response.destroy();
+                    return;
                 }
+                response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
                 response.end("Content couldn't be served.");
             });
         },

package/dist/server/host.d.ts

@@ -21,6 +21,12 @@ export interface HealthOptions {
     /** How the check is fetched (default: `fetch`; on Node, `nodeProbe()`). */
     readonly probe?: HealthProbe;
     readonly timeoutMs?: number;
+    /**
+     * Told each time the gate's state changes (P070): checking to healthy or unhealthy, and every
+     * flip between them, with the new view. `meta().served` changes with it, so an app that tells
+     * its clients whether frames are served pushes it from here.
+     */
+    readonly onChange?: (view: ContentHealthView) => void;
 }
 /** Where content stands, for the app's own meta and logs. */
 export interface ContentHealthView {
@@ -64,7 +70,13 @@ export interface ContentHostOptions<V> {
      * that says which scope a label names (`prefixedName` does).
      */
     readonly name?: Naming;
-    /** Labels the app routes itself (`p-*` previews): `fetch` hands them back. */
+    /**
+     * Labels the app itself serves on the content domain, which `fetch` hands back (null) so the
+     * app's own routes answer there: Ferry's `p-*` previews, another server's namespace it routes
+     * on. Not for labels nothing should answer: a label the naming never makes, the bare domain
+     * and an address `entry.at` says names nothing all get Porthole's 404, with nothing to list
+     * (P070). The health label is reserved by the gate itself.
+     */
     readonly reserved?: readonly string[] | ((label: string) => boolean);
     /**
      * Policy 1, mapping: the instance a request proposes (`{ instance }`), as the app means it,
@@ -105,17 +117,39 @@ export interface EntryOptions<V> {
     /** The app's authorize route (`ContentHost.authorize`), an absolute URL on an app origin. */
     readonly authorizeUrl: string;
     /**
-     * Policy 1 for a clean address: the instance a scope's path means, or null (404). The path is
-     * the address's pathname; its query rides along but never chooses the instance.
+     * Policy 1 for a clean address: the instance a scope's path means, or null/undefined: nothing
+     * (404). The path is the address's pathname; its query rides along but never chooses the
+     * instance. Asked twice: on the content origin, with no viewer, whether the address names
+     * anything at all (nothing: Porthole's 404 there, never the app's sign-in, P070); then at the
+     * authorize route with the viewer. Say what exists the same way for both; `access` says who
+     * may see it.
      */
-    readonly at: (scope: string, path: string, viewer: V | null, request: Request) => Awaitable<InstanceRef | null>;
+    readonly at: (scope: string, path: string, viewer: V | null, request: Request) => Awaitable<InstanceRef | null | undefined>;
     /**
      * The app's own sign-in, which comes back to `returnTo` (the authorize URL) once signed in.
-     * Only ever on a tab: in a frame, the person is asked to open a new tab instead.
+     * Only ever on a tab: in a frame, the person is asked to open a new tab instead. `entry` is the
+     * address being opened, decoded (P070).
      */
-    readonly signIn: (returnTo: string, request: Request) => Awaitable<Response>;
-    /** The app's refusal page on a tab (a frame gets Porthole's plain one). Default: Porthole's. */
-    readonly refusal?: (status: 403 | 404, request: Request) => Awaitable<Response>;
+    readonly signIn: (returnTo: string, request: Request, entry: EntryContext) => Awaitable<Response>;
+    /**
+     * The app's refusal page on a tab (a frame gets Porthole's plain one), for the address in
+     * `entry`. Nothing (null, undefined): Porthole's own (P070).
+     */
+    readonly refusal?: (status: 403 | 404, request: Request, entry: EntryContext) => Awaitable<Response | null | undefined>;
+}
+/** The clean address a redirect entry is opening, as its authorize route decoded it (P070). */
+export interface EntryContext {
+    /** The address's label, and the scope it names (null: one the naming never makes). */
+    readonly label: string;
+    readonly scope: string | null;
+    /** The path (and query) asked for. */
+    readonly path: string;
+    /** The clean address itself: where the person comes back to. */
+    readonly url: string;
+    /** The instance the path names for this viewer (`entry.at`), or null. */
+    readonly instance: InstanceRef | null;
+    /** Whether it was asked from a frame. */
+    readonly framed: boolean;
 }
 export interface ContentHost<V> {
     /** The parsed content domain, or null (off, or unusable settings under the fallback). */