@statewalker/webrun-http-browser 0.5.0 → 0.6.2

package/dist/sw/sw-dispatcher.d.ts

@@ -35,6 +35,14 @@ export declare class SwPortHandler {
     constructor(options: SwPortHandlerOptions);
     get key(): string;
     get scope(): string;
+    /**
+     * The scope as a url on the worker's origin. Resolved against the worker's
+     * own url when one is given, not against this module's: a bundle that is
+     * not an ES module (an IIFE, Theia's frontend) has no `import.meta.url`, and
+     * `new URL(scope, undefined)` threw `Invalid URL` there. Only without a
+     * worker url does the module's location decide (its default `index-sw.js`
+     * sits next to it).
+     */
     get rootUrl(): URL;
     get serviceWorkerUrl(): string;
     protected _newCommunicationChannel(): Promise<[MessagePort, MessagePort]>;

package/dist/sw/sw-dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sw-dispatcher.d.ts","sourceRoot":"","sources":["../../src/sw/sw-dispatcher.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,OAAO,CAAC,iBAAiB,CAAC,CAAS;IACnC,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,oBAAoB,CAAC,CAAgB;IAC7C,OAAO,CAAC,qBAAqB,CAAC,CAAa;IAE3C,YAAY,OAAO,EAAE,oBAAoB,EAIxC;IAED,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,OAAO,IAAI,GAAG,CAEjB;IAED,IAAI,gBAAgB,IAAI,MAAM,CAa7B;IAED,UAAgB,wBAAwB,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAG9E;IAED,UAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;IAED,UAAgB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAU3D;IAED,SAAS,CAAC,oBAAoB,IAAI,WAAW,CAE5C;IAED;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAsD3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAU1B;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,aAAa,2BAAkC;IACxD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,cAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,kBAAkB,CAAC,CAAgB;IAE3C,YAAY,EAAE,IAAI,EAAE,GAAc,EAAE,EAAE,uBAAuB,EAG5D;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAgBnE;IAED,yDAAyD;IACzD,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjC;IAED,KAAK,IAAI,IAAI,CAgCZ;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1B;IAED,OAAO,CAAC,gBAAgB;YAOV,SAAS;YAgBT,kBAAkB;YAWlB,cAAc;YAOd,gBAAgB;CAY/B"}
+{"version":3,"file":"sw-dispatcher.d.ts","sourceRoot":"","sources":["../../src/sw/sw-dispatcher.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,OAAO,CAAC,iBAAiB,CAAC,CAAS;IACnC,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,oBAAoB,CAAC,CAAgB;IAC7C,OAAO,CAAC,qBAAqB,CAAC,CAAa;IAE3C,YAAY,OAAO,EAAE,oBAAoB,EAIxC;IAED,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;;OAOG;IACH,IAAI,OAAO,IAAI,GAAG,CAGjB;IAED,IAAI,gBAAgB,IAAI,MAAM,CAa7B;IAED,UAAgB,wBAAwB,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAG9E;IAED,UAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;IAED,UAAgB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAU3D;IAED,SAAS,CAAC,oBAAoB,IAAI,WAAW,CAE5C;IAED;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAsD3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAU1B;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,aAAa,2BAAkC;IACxD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,cAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,kBAAkB,CAAC,CAAgB;IAE3C,YAAY,EAAE,IAAI,EAAE,GAAc,EAAE,EAAE,uBAAuB,EAG5D;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAgBnE;IAED,yDAAyD;IACzD,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjC;IAED,KAAK,IAAI,IAAI,CAgCZ;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1B;IAED,OAAO,CAAC,gBAAgB;YAOV,SAAS;YAgBT,kBAAkB;YAWlB,cAAc;YAOd,gBAAgB;CAY/B"}

package/dist/sw.js

@@ -1765,8 +1765,17 @@ var SwPortHandler = class {
 	get scope() {
 		return this.options.scope ?? new URL("./", this.serviceWorkerUrl).pathname;
 	}
+	/**
+	* The scope as a url on the worker's origin. Resolved against the worker's
+	* own url when one is given, not against this module's: a bundle that is
+	* not an ES module (an IIFE, Theia's frontend) has no `import.meta.url`, and
+	* `new URL(scope, undefined)` threw `Invalid URL` there. Only without a
+	* worker url does the module's location decide (its default `index-sw.js`
+	* sits next to it).
+	*/
 	get rootUrl() {
-		return new URL(this.scope, import.meta.url);
+		const base = this.options.serviceWorkerUrl ? this.serviceWorkerUrl : import.meta.url;
+		return new URL(this.scope, base);
 	}
 	get serviceWorkerUrl() {
 		if (!this._serviceWorkerUrl) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-http-browser",
-  "version": "0.5.0",
+  "version": "0.6.2",
   "private": false,
   "type": "module",
   "description": "ServiceWorker-based HTTP server for browsers, with relay and same-origin dispatch modes",
@@ -19,17 +19,26 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./sw": {
+      "source": "./src/sw.ts",
       "types": "./dist/sw.d.ts",
       "import": "./dist/sw.js"
     },
     "./relay-sw": {
+      "source": "./src/relay-sw.ts",
       "default": "./dist/relay-sw.js"
     },
+    "./relay-worker": {
+      "source": "./src/relay-worker.ts",
+      "types": "./dist/relay-worker.d.ts",
+      "import": "./dist/relay-worker.js"
+    },
     "./sw-worker": {
+      "source": "./src/sw-worker.ts",
       "default": "./dist/sw-worker.js"
     }
   },
@@ -42,20 +51,20 @@
   ],
   "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-http-streams": "^0.2.4",
+    "@statewalker/webrun-rpc": "^0.4.2",
+    "@statewalker/webrun-streams": "^0.2.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.8",
-    "@types/node": "^26.2.0",
+    "@biomejs/biome": "^2.5.15",
+    "@types/node": "^26.6.4",
     "http-server": "^14.1.1",
-    "playwright": "^1.62.1",
+    "playwright": "^1.63.0",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.2.4",
+    "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.10"
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3"
   },
   "sideEffects": false,
   "publishConfig": {

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);
+}