@statewalker/webrun-http-browser 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-http-browser",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "ServiceWorker-based HTTP server for browsers, with relay and same-origin dispatch modes",
@@ -29,6 +29,10 @@
     "./relay-sw": {
       "default": "./dist/relay-sw.js"
     },
+    "./relay-worker": {
+      "types": "./dist/relay-worker.d.ts",
+      "import": "./dist/relay-worker.js"
+    },
     "./sw-worker": {
       "default": "./dist/sw-worker.js"
     }
@@ -43,8 +47,8 @@
   "dependencies": {
     "idb-keyval": "^6.3.0",
     "@statewalker/webrun-http-streams": "0.2.2",
-    "@statewalker/webrun-streams": "0.2.0",
-    "@statewalker/webrun-rpc": "0.4.0"
+    "@statewalker/webrun-rpc": "0.4.0",
+    "@statewalker/webrun-streams": "0.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.8",

package/src/relay/index-sw.ts

@@ -4,15 +4,173 @@ import { callChannel, handleChannelCalls } from "../core/data-calls.js";
 import { newRegistry } from "../core/registry.js";
 import { handleClaimRequests } from "../core/service-worker-control.js";
 import { sendHttpRequest } from "../http/http-send-recieve.js";
+import { type MountSpec, type MountTable, newMountTable } from "./mount-table.js";
 import { splitServiceUrl } from "./split-service-url.js";
 
+/** What the registry keeps per service key. */
+export interface RegisteredClient {
+  clientId: string;
+  /** Where the service is mounted. Absent means `/~<key>/`, as before mounts. */
+  path?: string;
+}
+
+/**
+ * One stored registry entry, whatever shape it is on disk.
+ *
+ * BEFORE MOUNTS THE VALUE WAS A BARE CLIENT ID. A browser that ran the earlier
+ * worker still holds that shape, and reading it as an object would drop the id
+ * and quietly unregister every service the visitor had.
+ */
+export function readStoredEntry(value: unknown): RegisteredClient | undefined {
+  if (typeof value === "string") return { clientId: value };
+  if (typeof value !== "object" || value === null) return undefined;
+  const { clientId, path } = value as { clientId?: unknown; path?: unknown };
+  if (typeof clientId !== "string" || clientId === "") return undefined;
+  return typeof path === "string" ? { clientId, path } : { clientId };
+}
+
+/**
+ * Which service, if any, should answer `url`.
+ *
+ * `undefined` means NOT THE RELAY'S, and the caller must not call
+ * `respondWith`: the request then goes to the network, which is how a host
+ * keeps serving its own files from its own origin. Answering 404 here instead
+ * would make a root mount fatal.
+ */
+export function resolveServiceKey(
+  url: URL,
+  table: MountTable,
+  selfOrigin: string,
+): string | undefined {
+  // Another origin's resource is the network's business, as in any page.
+  if (url.origin !== selfOrigin) return undefined;
+  // Checked before EITHER route: an excluded path is never claimed, and the
+  // `/~<key>/` fallback below does not consult the table.
+  if (table.excludes(url)) return undefined;
+  const mounted = table.find(url);
+  if (mounted != null) return mounted;
+  const { key } = splitServiceUrl(url);
+  return key === "" ? undefined : key;
+}
+
+/**
+ * Waits for the mount table to be restored from the registry before routing
+ * `url` — but a restore failure must never wedge every fetch. `restored`
+ * rejecting (blocked storage, quota, private-mode edge cases) would otherwise
+ * propagate straight to `respondWith` on every request, including ones that
+ * should reach the network, which breaks the one rule this file exists to
+ * uphold. So: log the failure and route with whatever the in-memory table
+ * already holds — possibly empty, never fatal.
+ */
+export async function resolveAfterRestore(
+  restored: Promise<void>,
+  url: URL,
+  table: MountTable,
+  selfOrigin: string,
+): Promise<string | undefined> {
+  try {
+    await restored;
+  } catch (error) {
+    console.error("[relay] failed to restore mounts from the registry", error);
+  }
+  return resolveServiceKey(url, table, selfOrigin);
+}
+
+/**
+ * What REGISTER does to the mount table: set it when `path` is given, or
+ * remove any earlier mount when it is not. A path-less re-registration
+ * reverts a service to `/~<key>/` addressing, and a stale prefix left behind
+ * would keep routing requests to a mount that no longer exists.
+ *
+ * A REGISTRATION ONLY TOUCHES WHAT A REGISTRATION MADE. `hostKeys` names the
+ * mounts the host declared itself, in `options.mounts`. Those are the host's
+ * build-time decision and a page may not undo it: the documented static flow
+ * -- host declares `{ key: "app", path: "/" }`, page calls `initHttpService(h,
+ * { key: "app", port })` with no path -- would otherwise have its very first
+ * registration delete the host's own mount and leave the origin unmounted. A
+ * path-ful REGISTER naming a host key is ignored for the same reason (it would
+ * replace a `match` predicate with a prefix of the page's choosing).
+ */
+export function applyRegisteredMount(
+  table: MountTable,
+  key: string,
+  path: string | undefined,
+  hostKeys: ReadonlySet<string> = new Set(),
+): void {
+  if (hostKeys.has(key)) return;
+  if (path != null) {
+    table.set(key, { path });
+  } else {
+    table.remove(key);
+  }
+}
+
+/**
+ * What UNREGISTER does to the mount table: drop the mount a registration
+ * made. A host-declared mount stays, for the reason `applyRegisteredMount`
+ * gives -- a page tearing down its service must not take the host's table
+ * with it.
+ */
+export function removeRegisteredMount(
+  table: MountTable,
+  key: string,
+  hostKeys: ReadonlySet<string> = new Set(),
+): void {
+  if (hostKeys.has(key)) return;
+  table.remove(key);
+}
+
+export interface RelayServiceWorkerOptions {
+  /** A fixed table, for a host that knows its services at build time. */
+  mounts?: Array<{ key: string } & MountSpec>;
+  /** Paths the relay never claims. Checked before the table. */
+  exclude?: (url: URL) => boolean;
+  /** Refuse a registration from the wrong client. Default: everyone may. */
+  canRegister?: (client: Client, key: string) => boolean | Promise<boolean>;
+  /** Default `"last-wins"`, the behaviour before this option existed. */
+  takeover?: "first-wins" | "last-wins";
+  /** Stamp headers on responses the relay makes. Not applied to network fetches. */
+  decorateResponse?: (response: Response, request: Request) => Response;
+}
+
+/**
+ * May `candidateId` take the key?
+ *
+ * `last-wins` is what the relay has always done and stays the default. With
+ * `first-wins`, a LIVE holder keeps its key: on an origin whose name is
+ * guessable, a second page proves nothing by existing. A holder that reloaded
+ * is no longer live, so a host's own re-registration is never blocked.
+ */
+export function mayRegister(args: {
+  current?: RegisteredClient;
+  candidateId: string;
+  isCurrentLive: boolean;
+  takeover: "first-wins" | "last-wins";
+}): boolean {
+  if (args.takeover === "last-wins") return true;
+  if (args.current == null || !args.isCurrentLive) return true;
+  return args.current.clientId === args.candidateId;
+}
+
 /**
  * Boots the relay ServiceWorker: routes fetches shaped `<origin>/~<key>/…` to
  * the client that registered `key`, and exposes REGISTER/UNREGISTER/CONNECT
  * channel calls used by the page-side relay client.
  */
-export function startRelayServiceWorker(self: ServiceWorkerGlobalScope): () => void {
+export function startRelayServiceWorker(
+  self: ServiceWorkerGlobalScope,
+  options: RelayServiceWorkerOptions = {},
+): () => void {
   const [register, clear] = newRegistry();
+  const mounts = newMountTable({ exclude: options.exclude });
+  // The keys the HOST declared. Kept so a page's REGISTER/UNREGISTER cannot
+  // replace or delete a mount it never created -- see `applyRegisteredMount`.
+  const hostKeys = new Set<string>();
+  for (const { key, ...spec } of options.mounts ?? []) {
+    mounts.set(key, spec);
+    hostKeys.add(key);
+  }
+  const takeover = options.takeover ?? "last-wins";
 
   if (typeof self.skipWaiting === "function") {
     self.addEventListener("install", (e: ExtendableEvent) => {
@@ -28,6 +186,30 @@ export function startRelayServiceWorker(self: ServiceWorkerGlobalScope): () => v
 
   const clientsRegistry = newClientsRegistry({ self });
 
+  // A RESTARTED WORKER HAS AN EMPTY TABLE AND A FULL DATABASE. The registry
+  // survives in IndexedDB; the mounts are in memory, so they must be read back
+  // or the first fetch after a restart finds nothing mounted.
+  const restored = clientsRegistry.restoreMounts(mounts, hostKeys);
+
+  // ONCE THE RESTORE HAS SETTLED THE TABLE CAN BE READ SYNCHRONOUSLY, and the
+  // fetch listener needs that: `respondWith` must be called synchronously, so
+  // a listener that can only decide after an `await` has to call it for EVERY
+  // request and re-issue the ones that are nobody's. That is not the same as
+  // leaving them alone -- it defeats navigation preload and makes a request
+  // with `cache: "only-if-cached"` throw. This latch keeps the async path for
+  // the handful of requests that arrive before the restore settles, and only
+  // those.
+  //
+  // The handler is attached here, at creation, rather than at the first fetch:
+  // a rejection with nothing listening surfaces as an `unhandledrejection` in
+  // the worker. `resolveAfterRestore` still does its own logging for the
+  // requests that await `restored` directly.
+  let restoreSettled = false;
+  const latch = () => {
+    restoreSettled = true;
+  };
+  restored.then(latch, latch);
+
   // Pages bridge to `registration.active` when uncontrolled, so they do not
   // need this; it is here so any page of this origin can ask for control.
   register(handleClaimRequests(self));
@@ -36,13 +218,33 @@ export function startRelayServiceWorker(self: ServiceWorkerGlobalScope): () => v
     handleChannelCalls(self, "REGISTER", async (event, data) => {
       const source = event.source as Client | null;
       if (!source) return false;
-      const { key } = data as { key: string };
-      return await clientsRegistry.addClient(key, source);
+      const { key, path } = data as { key: string; path?: string };
+
+      if (options.canRegister != null && !(await options.canRegister(source, key))) {
+        throw new Error(`this client may not register "${key}"`);
+      }
+
+      // `last-wins` -- the untouched default -- must cost exactly what it did
+      // before this option existed: no registry lookup beyond `addClient`'s
+      // own. Only `first-wins` needs to know who currently holds the key and
+      // whether they are still live, so only it pays for finding out.
+      if (takeover === "first-wins") {
+        const current = await clientsRegistry.getMount(key);
+        const isCurrentLive = current != null && (await clientsRegistry.getClient(key)) != null;
+        if (!mayRegister({ current, candidateId: source.id, isCurrentLive, takeover })) {
+          throw new Error(`"${key}" is already served by another client`);
+        }
+      }
+
+      const added = await clientsRegistry.addClient(key, source, path);
+      applyRegisteredMount(mounts, key, path, hostKeys);
+      return added;
     }),
   );
   register(
     handleChannelCalls(self, "UNREGISTER", async (_event, data) => {
       const { key } = data as { key: string };
+      removeRegisteredMount(mounts, key, hostKeys);
       return await clientsRegistry.removeClient(key);
     }),
   );
@@ -55,31 +257,54 @@ export function startRelayServiceWorker(self: ServiceWorkerGlobalScope): () => v
     }),
   );
 
+  /** Answers `request` as the service registered under `key`. */
+  async function serve(key: string, request: Request, url: URL): Promise<Response> {
+    const params = splitServiceUrl(url);
+    try {
+      const channel = new MessageChannel();
+      const client = await clientsRegistry.getClient(key);
+      if (!client) throw HttpError.errorResourceGone(params);
+      const data = { type: "http", key };
+      const accepted = await callChannel<boolean>(client, "CONNECT", data, channel.port2);
+      if (!accepted) throw HttpError.errorForbidden(params);
+      const response = await sendHttpRequest(channel.port1, request);
+      return options.decorateResponse?.(response, request) ?? response;
+    } catch (error) {
+      const httpError = HttpError.fromError(error);
+      const errorOptions = httpError.getResponseOptions(params);
+      const errorResponse = new Response(JSON.stringify(errorOptions), {
+        status: httpError.status ?? 500,
+        statusText: httpError.statusText ?? "Internal Error",
+        headers: { "Content-Type": "application/json" },
+      });
+      return options.decorateResponse?.(errorResponse, request) ?? errorResponse;
+    }
+  }
+
   const fetchListener = (event: FetchEvent) => {
     const request = event.request;
-    const params = splitServiceUrl(request.url);
-    const { key } = params;
-    if (!key) return;
+    const url = new URL(request.url);
 
+    // THE ORDINARY CASE: decide synchronously and, when the request is
+    // nobody's, RETURN WITHOUT `respondWith` -- the browser then performs it
+    // exactly as it would with no worker installed.
+    if (restoreSettled) {
+      const key = resolveServiceKey(url, mounts, self.location.origin);
+      if (key == null) return;
+      event.respondWith(serve(key, request, url));
+      return;
+    }
+
+    // Before the restore settles there is nothing to decide on synchronously,
+    // and `respondWith` cannot be called after an await. Such a request is
+    // claimed and, if it turns out to be nobody's, re-issued -- the one
+    // window in which the worker still stands in for the network, and it
+    // lasts only until the registry read completes.
     event.respondWith(
       (async (): Promise<Response> => {
-        try {
-          const channel = new MessageChannel();
-          const client = await clientsRegistry.getClient(key);
-          if (!client) throw HttpError.errorResourceGone(params);
-          const data = { type: "http", key };
-          const accepted = await callChannel<boolean>(client, "CONNECT", data, channel.port2);
-          if (!accepted) throw HttpError.errorForbidden(params);
-          return await sendHttpRequest(channel.port1, request);
-        } catch (error) {
-          const httpError = HttpError.fromError(error);
-          const options = httpError.getResponseOptions(params);
-          return new Response(JSON.stringify(options), {
-            status: httpError.status ?? 500,
-            statusText: httpError.statusText ?? "Internal Error",
-            headers: { "Content-Type": "application/json" },
-          });
-        }
+        const key = await resolveAfterRestore(restored, url, mounts, self.location.origin);
+        if (key == null) return await fetch(request);
+        return await serve(key, request, url);
       })(),
     );
   };
@@ -95,33 +320,41 @@ interface ClientsRegistryOptions {
 }
 
 interface ClientsRegistry {
-  addClient(clientKey: string, client: Client): Promise<boolean>;
+  addClient(clientKey: string, client: Client, path?: string): Promise<boolean>;
   removeClient(clientKey: string): Promise<boolean>;
   getClient(clientKey: string): Promise<Client | undefined>;
+  getMount(clientKey: string): Promise<RegisteredClient | undefined>;
+  restoreMounts(table: MountTable, hostKeys?: ReadonlySet<string>): Promise<void>;
 }
 
 function newClientsRegistry({ self, key = "clientsIds" }: ClientsRegistryOptions): ClientsRegistry {
-  let _index: Record<string, string> | undefined;
+  let _index: Record<string, RegisteredClient> | undefined;
 
-  async function loadClientsIndex(): Promise<Record<string, string>> {
+  async function loadClientsIndex(): Promise<Record<string, RegisteredClient>> {
     if (!_index) {
-      const entries = ((await get<Array<[string, string]>>(key)) ?? []) as Array<[string, string]>;
-      _index = Object.fromEntries(entries);
+      const entries = ((await get<Array<[string, unknown]>>(key)) ?? []) as Array<
+        [string, unknown]
+      >;
+      _index = {};
+      for (const [clientKey, value] of entries) {
+        const entry = readStoredEntry(value);
+        if (entry) _index[clientKey] = entry;
+      }
     }
     return _index;
   }
 
-  async function storeClientsIndex(): Promise<Record<string, string>> {
+  async function storeClientsIndex(): Promise<Record<string, RegisteredClient>> {
     const index = await loadClientsIndex();
     await set(key, Object.entries(index));
     return index;
   }
 
-  async function addClient(clientKey: string, client: Client): Promise<boolean> {
+  async function addClient(clientKey: string, client: Client, path?: string): Promise<boolean> {
     const index = await loadClientsIndex();
-    const clientId = client.id;
-    if (index[clientKey] === clientId) return false;
-    index[clientKey] = clientId;
+    const current = index[clientKey];
+    if (current?.clientId === client.id && current.path === path) return false;
+    index[clientKey] = path == null ? { clientId: client.id } : { clientId: client.id, path };
     await storeClientsIndex();
     return true;
   }
@@ -134,11 +367,29 @@ function newClientsRegistry({ self, key = "clientsIds" }: ClientsRegistryOptions
     return true;
   }
 
+  async function getMount(clientKey: string): Promise<RegisteredClient | undefined> {
+    const index = await loadClientsIndex();
+    return index[clientKey];
+  }
+
+  async function restoreMounts(
+    table: MountTable,
+    hostKeys: ReadonlySet<string> = new Set(),
+  ): Promise<void> {
+    const index = await loadClientsIndex();
+    for (const [clientKey, entry] of Object.entries(index)) {
+      // A host-declared mount outranks a persisted registration of the same
+      // key, exactly as it does on a live REGISTER.
+      if (hostKeys.has(clientKey)) continue;
+      if (entry.path != null) table.set(clientKey, { path: entry.path });
+    }
+  }
+
   async function getClient(clientKey: string): Promise<Client | undefined> {
     const index = await loadClientsIndex();
-    const clientId = index[clientKey];
-    if (!clientId) return undefined;
-    const client = await self.clients.get(clientId);
+    const entry = index[clientKey];
+    if (!entry) return undefined;
+    const client = await self.clients.get(entry.clientId);
     if (!client) {
       delete index[clientKey];
       await storeClientsIndex();
@@ -146,5 +397,5 @@ function newClientsRegistry({ self, key = "clientsIds" }: ClientsRegistryOptions
     return client ?? undefined;
   }
 
-  return { getClient, addClient, removeClient };
+  return { getClient, getMount, addClient, removeClient, restoreMounts };
 }

package/src/relay/index.ts

@@ -1,6 +1,6 @@
 import type { HttpHandler } from "@statewalker/webrun-http-streams";
 import { serializeError } from "@statewalker/webrun-streams";
-import { callChannel, handleChannelCalls } from "../core/data-calls.js";
+import { type ChannelCallHandler, callChannel } from "../core/data-calls.js";
 import type { MessageTarget } from "../core/message-target.js";
 import { newRegistry } from "../core/registry.js";
 import {
@@ -80,6 +80,11 @@ async function registerServiceWorker({
 
 export interface ServiceOptions {
   key: string;
+  /**
+   * Where this service is mounted on the relay origin, e.g. `/` or `/peers/`.
+   * Omitted, the service stays reachable at `/~<key>/`, as before mounts.
+   */
+  path?: string;
   port: MessageTarget;
 }
 
@@ -89,10 +94,11 @@ export interface ServiceOptions {
  */
 export async function initHttpService(
   handler: HttpHandler,
-  { key, port }: ServiceOptions,
+  { key, path, port }: ServiceOptions,
 ): Promise<() => void> {
   return await registerConnectionsHandler({
     key,
+    path,
     communicationPort: port,
     handler: async (_event, _data, callPort) => {
       handleHttpRequests(callPort, handler);
@@ -258,22 +264,72 @@ export async function initializeConnection({
 
 export interface RegisterConnectionsHandlerOptions {
   key: string;
+  /** Where this service is mounted; see `ServiceOptions.path`. */
+  path?: string;
   handler: (event: MessageEvent, data: unknown, port: MessagePort) => boolean | Promise<boolean>;
   communicationPort: MessageTarget;
 }
 
 export async function registerConnectionsHandler({
   key,
+  path,
   handler,
   communicationPort,
 }: RegisterConnectionsHandlerOptions): Promise<() => void> {
   const [register, cleanup] = newRegistry();
-  await callChannel(communicationPort, "REGISTER", { key });
+  // `path` is omitted rather than sent as undefined: the worker distinguishes
+  // "mounted at /" from "not mounted", and a key with no path keeps /~<key>/.
+  await callChannel(communicationPort, "REGISTER", path == null ? { key } : { key, path });
   register(() => callChannel(communicationPort, "UNREGISTER", { key }));
   register(
-    handleChannelCalls(communicationPort, "CONNECT", async (event, data, port) => {
+    handleKeyedChannelCalls(communicationPort, "CONNECT", key, async (event, data, port) => {
       return await handler(event, data, port);
     }),
   );
   return cleanup;
 }
+
+/**
+ * `handleChannelCalls`, but only for calls whose `params.key` is `key`.
+ *
+ * ONE CONNECTION CARRIES SEVERAL SERVICES — an app at `/` and a mesh gateway
+ * at `/peers/` over one relay iframe is the shape mounts exist for. Plain
+ * `handleChannelCalls` cannot do that: every listener it has for a call type
+ * runs on every message, and each is handed the SAME reply port and the SAME
+ * transferred stream port. Two services then both serve the one channel the
+ * worker is reading, and its response comes back with both bodies in it.
+ *
+ * WHY NOT A FILTER INSIDE THE HANDLER. Returning `false` for a foreign key
+ * does not help: `handleChannelCalls` still replies, `callChannel` resolves on
+ * the FIRST reply it receives, and the loser's `false` reaches the worker as
+ * "the client refused" — a 403, non-deterministically. A service that is not
+ * the addressee must stay SILENT and leave the transferred port untouched.
+ *
+ * Local to this module on purpose. `handleChannelCalls` is also used where a
+ * call carries no key (REGISTER/UNREGISTER, and the worker's own CONNECT in
+ * `index-sw.ts`, which is the other direction), so its semantics must not
+ * change.
+ */
+function handleKeyedChannelCalls(
+  target: MessageTarget,
+  callType: string,
+  key: string,
+  handler: ChannelCallHandler,
+): () => void {
+  const listener = async (event: MessageEvent) => {
+    const data = event.data as { type?: string; params?: { key?: unknown } } | null | undefined;
+    if (!data || data.type !== callType) return;
+    if (data.params?.key !== key) return;
+    const [port, ...transfers] = (event.ports ?? []) as MessagePort[];
+    const response: { result?: unknown; error?: unknown } = {};
+    try {
+      response.result = await handler(event, data.params, ...transfers);
+    } catch (error) {
+      response.error = serializeError(error);
+    }
+    port?.postMessage(response);
+  };
+  target.addEventListener("message", listener);
+  target.start?.();
+  return () => target.removeEventListener("message", listener);
+}

package/src/relay/mount-table.ts

@@ -0,0 +1,115 @@
+/**
+ * Which registered service owns a URL.
+ *
+ * A pure lookup: no ServiceWorker, no storage, no I/O, so the routing rules
+ * can be tested as arithmetic rather than through a browser.
+ *
+ * TWO KINDS OF MOUNT, AND WHY BOTH. A `path` is a prefix, which is all most
+ * hosts need and costs nothing to match. A `match` predicate is the escape
+ * hatch for anything richer -- a host that wants URLPattern brings it and pays
+ * for it; this file must stay dependency-free, because it runs in a
+ * ServiceWorker that has to start fast.
+ *
+ * SPECIFICITY, NOT REGISTRATION ORDER. Prefixes are tried longest-first, so a
+ * catch-all at "/" cannot swallow "/peers/" and a host need not register in a
+ * careful order. Predicates are opaque -- nothing can be said about how
+ * specific they are -- so they are tried after every prefix, in the order they
+ * were registered.
+ */
+
+export interface MountSpec {
+  /** A path prefix, e.g. `/peers/`. `/` is the whole origin. */
+  path?: string;
+  /** Anything richer. Consulted only when no prefix matches. */
+  match?: (url: URL) => boolean;
+}
+
+export interface MountTable {
+  /** Add or replace the mount for `key`. */
+  set(key: string, spec: MountSpec): void;
+  remove(key: string): void;
+  /** The key that owns `url`, or `undefined` — meaning "not the relay's". */
+  find(url: URL): string | undefined;
+  /**
+   * Is `url` reserved by `exclude`? `find` already applies it, but the relay
+   * has a SECOND route — the `/~<key>/` spelling, which does not go through
+   * the table at all — and "an excluded path is never claimed" has to hold
+   * for both. The predicate lives here so there is one copy of it.
+   */
+  excludes(url: URL): boolean;
+}
+
+export interface MountTableOptions {
+  /**
+   * Paths the relay never claims, checked BEFORE the table. A root mount
+   * matches every path, so a host with files of its own (a relay page, a
+   * worker, hashed assets) is unusable without this.
+   */
+  exclude?: (url: URL) => boolean;
+}
+
+interface Entry {
+  key: string;
+  /** `""` for a predicate-only mount; otherwise `/` or `/a/b/`. */
+  prefix: string;
+  match?: (url: URL) => boolean;
+  /** Registration order, to break ties between predicates. */
+  seq: number;
+}
+
+/** `/` stays `/`; `/peers` and `/peers/` both become `/peers/`. */
+function normalise(path: string): string {
+  if (path === "" || path === "/") return "/";
+  const withSlash = path.startsWith("/") ? path : `/${path}`;
+  return withSlash.endsWith("/") ? withSlash : `${withSlash}/`;
+}
+
+/** Does `prefix` own `pathname`? `/peers/` owns `/peers/`, `/peers` and `/peers/x`. */
+function owns(prefix: string, pathname: string): boolean {
+  if (prefix === "/") return true;
+  if (pathname.startsWith(prefix)) return true;
+  return `${pathname}/` === prefix;
+}
+
+export function newMountTable(options: MountTableOptions = {}): MountTable {
+  const entries = new Map<string, Entry>();
+  let seq = 0;
+
+  return {
+    set(key, spec) {
+      entries.set(key, {
+        key,
+        prefix: spec.path == null ? "" : normalise(spec.path),
+        match: spec.match,
+        seq: seq++,
+      });
+    },
+
+    remove(key) {
+      entries.delete(key);
+    },
+
+    excludes(url) {
+      return options.exclude?.(url) === true;
+    },
+
+    find(url) {
+      if (options.exclude?.(url) === true) return undefined;
+
+      let best: Entry | undefined;
+      for (const entry of entries.values()) {
+        if (entry.prefix === "" || !owns(entry.prefix, url.pathname)) continue;
+        if (best == null || entry.prefix.length > best.prefix.length) best = entry;
+      }
+      if (best != null) return best.key;
+
+      const predicates = [...entries.values()]
+        .filter((entry) => entry.match != null)
+        .sort((a, b) => a.seq - b.seq);
+      for (const entry of predicates) {
+        if (entry.match?.(url) === true) return entry.key;
+      }
+      return undefined;
+    },
+  };
+}