@botiverse/porthole 0.2.0 → 0.2.2

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). */

package/dist/server/host.js

@@ -88,7 +88,19 @@ export function createContentHost(options) {
                 ...(options.upstream === undefined ? {} : { upstream: options.upstream }),
                 ...(options.entry === undefined
                     ? {}
-                    : { entry: { authorizeUrl: options.entry.authorizeUrl } }),
+                    : {
+                        entry: {
+                            authorizeUrl: options.entry.authorizeUrl,
+                            // Whether a clean address names anything, before a browser is sent away (P070).
+                            named: async (label, path, request) => {
+                                const scope = options.name?.scopeOf?.(label) ?? null;
+                                const at = options.entry?.at;
+                                return (scope !== null &&
+                                    at !== undefined &&
+                                    (await at(scope, path, null, request)) != null);
+                            },
+                        },
+                    }),
                 ...(options.authorize === undefined
                     ? {}
                     : {
@@ -173,6 +185,14 @@ export function createContentHost(options) {
                     ? { evt: "porthole.content.healthy" }
                     : { evt: "porthole.content.unhealthy", reason });
             }
+            if (before.state !== view.state) {
+                try {
+                    gate.onChange?.(view);
+                }
+                catch {
+                    // The app's listener failing changes nothing here.
+                }
+            }
             running = null;
             schedule();
             return view;
@@ -356,18 +376,28 @@ export function createContentHost(options) {
                 try {
                     const instance = scope === null
                         ? null
-                        : await entry.at(scope, new URL(state.path, "https://x.invalid").pathname, viewer, request);
+                        : ((await entry.at(scope, new URL(state.path, "https://x.invalid").pathname, viewer, request)) ?? null);
                     const grant = instance === null ? null : await options.access(instance, viewer, request);
+                    // The address being opened, decoded, for the app's sign-in and refusal pages.
+                    const context = {
+                        label: state.label,
+                        scope,
+                        path: state.path,
+                        url: clean,
+                        instance,
+                        framed,
+                    };
                     if (instance === null || grant === null) {
                         if (viewer === null) {
                             // The app's sign-in never shows in a frame: the person opens a tab for it.
                             return framed
                                 ? appPage(401, "Open this in a new tab to sign in", "Signing in doesn't work inside a frame.", "sign-in", method)
-                                : await entry.signIn(request.url, request);
+                                : await entry.signIn(request.url, request, context);
                         }
                         const status = instance === null ? 404 : 403;
-                        if (!framed && entry.refusal !== undefined) {
-                            return await entry.refusal(status, request);
+                        const own = framed ? null : await entry.refusal?.(status, request, context);
+                        if (own !== null && own !== undefined) {
+                            return own;
                         }
                         return status === 404
                             ? appPage(404, "Not found", "There is nothing here.", "not-found", method)

package/dist/server/index.d.ts

@@ -33,10 +33,12 @@
  * content without a valid ticket or cookie gets nothing of the content.
  */
 export { createServer } from "./server.ts";
-export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
+export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type EntryContext, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
 export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
 export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
 export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
 export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
+export type { PortholeConfig } from "../config/schema.ts";
+export type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
 export { proxyTo, type ProxyOptions } from "./proxy.ts";
 export type { Access, ArtifactStore, AuthorizeAnswer, AuthorizeRequest, Authorizer, ContentDomain, EntryState, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";

package/dist/server/pages.js

@@ -14,7 +14,21 @@ export const STATUS_SCRIPT_PATH = "/__porthole/status.js";
 export const ENTER_SCRIPT_PATH = "/__porthole/enter.js";
 /** Answers 204 when the request carries a good session for its origin's app, 401 otherwise. */
 export const SESSION_PATH = "/__porthole/session";
-const say = () => `const say = (params) => { if (window.parent === window) return; for (const origin of hosts) window.parent.postMessage({ jsonrpc: "2.0", method: ${JSON.stringify(FRAME_STATUS_METHOD)}, params }, origin); };`;
+/**
+ * Tells the page that frames this one how loading went, at each web host origin. A desktop app's
+ * own scheme (`ferry://app`) is no target origin a browser takes (postMessage throws), so where
+ * the host origins hold one, and the parent isn't known to be a web host origin, the word goes to
+ * the parent as `*`: these pages' `frame-ancestors` already hold their parent to the host origins,
+ * and what they say is no secret (P070). One origin failing never stops the page.
+ */
+const say = () => `const say = (params) => {
+    if (window.parent === window) return;
+    const message = { jsonrpc: "2.0", method: ${JSON.stringify(FRAME_STATUS_METHOD)}, params };
+    const web = hosts.filter((origin) => origin.startsWith("https://") || origin.startsWith("http://"));
+    for (const origin of web) { try { window.parent.postMessage(message, origin); } catch (_) {} }
+    const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
+    if (web.length < hosts.length && (parent === null || !web.includes(parent))) { try { window.parent.postMessage(message, "*"); } catch (_) {} }
+  };`;
 /** Tells the host the page is blocked, and why (from the page's data attributes). */
 const STATUS_SCRIPT = `(() => {
   const main = document.querySelector("[data-porthole-status]");

package/dist/server/proxy.js

@@ -96,6 +96,8 @@ export function proxyTo(options = {}) {
             method,
             headers: upstreamRequestHeaders(request.headers, access.origin, target),
             redirect: "manual",
+            // The browser went away (`nodeHost` aborts it): so does the relay (P070).
+            signal: request.signal,
             ...(hasBody ? { body: request.body, duplex: "half" } : {}),
         });
         return new Response(method === "HEAD" ? null : answer.body, {

package/dist/server/server.js

@@ -565,8 +565,15 @@ export function createServer(options) {
      * signed state, the browser holding the state's nonce in a cookie of this origin. A path just
      * entered whose cookie still didn't come back is a browser that keeps none here: no loop.
      */
-    function beginEntry(request, url, label, to) {
+    async function beginEntry(request, url, label, to) {
         const method = request.method.toUpperCase();
+        // An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
+        const scopeOf = content.name?.scopeOf;
+        const named = options.entry?.named;
+        if ((scopeOf !== undefined && scopeOf(label) === null) ||
+            (named !== undefined && !(await named(label, url.pathname, request)))) {
+            return page(404, "Nothing here", "This address names no content.", method);
+        }
         if (method !== "GET" && method !== "HEAD") {
             return page(401, "Open this from the app", "Open this address in a browser.", method, "session");
         }
@@ -942,7 +949,7 @@ export function createServer(options) {
                         return await serveAccess(request, entered, null);
                     }
                     if (options.upstream === undefined || accessOf(request, label, null) === null) {
-                        return beginEntry(request, url, label, authorizeUrl);
+                        return await beginEntry(request, url, label, authorizeUrl);
                     }
                 }
                 // Without an upstream, only Porthole's own paths are served here: any other is nothing.

package/dist/server/types.d.ts

@@ -1,5 +1,6 @@
 import type { PortholeConfig } from "../config/schema.ts";
 import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
+import type { Naming } from "./naming.ts";
 export interface ContentDomain {
     /**
      * The registrable domain content is served under, used for nothing else
@@ -16,13 +17,14 @@ export interface ContentDomain {
      * names like `a-<id>`) must return one lowercase DNS label, the same for the same scope, a
      * different one for a different scope, and never a `reserved` one.
      */
-    readonly name?: (scope: string) => string;
+    readonly name?: Naming;
     /**
-     * Labels this server never serves or names: another server's namespace under the same domain
-     * (`f` for `<instance>.f.<domain>`, `www`), or the host's own (`p-*`: every label starting
-     * `p-`). Each entry is a whole label, or a prefix ending in `*`; or a function that says
-     * whether a label is reserved. Requests for them, and for the names under them, get null (the
-     * host's routes), so a host routes them without wrapping `handle`.
+     * Labels something else serves on this domain, so this server never names them and hands their
+     * requests back: another server's namespace (`f` for `<instance>.f.<domain>`, where that server
+     * answers), or the host's own (`p-*`: its previews). Each entry is a whole label, or a prefix
+     * ending in `*`; or a function that says whether a label is reserved. Requests for them, and for
+     * the names under them, get null (the host's routes), so a host routes them without wrapping
+     * `handle`. Labels nothing serves need no entry: they get this server's 404 (P070).
      */
     readonly reserved?: readonly string[] | ((label: string) => boolean);
 }
@@ -161,6 +163,13 @@ export interface ServerOptions {
      */
     readonly entry?: {
         readonly authorizeUrl: string;
+        /**
+         * Whether a clean address names anything (P070): asked before sending a browser away, with
+         * the address's label and pathname. False: this server's 404, never the authorize route. A
+         * naming that says a label's scope (`Naming.scopeOf`) already answers 404 for a label it never
+         * makes.
+         */
+        readonly named?: (label: string, path: string, request: Request) => boolean | Promise<boolean>;
     };
 }
 /** A redirect entry's state, as the host's authorize route reads it (`PortholeServer.entryState`). */