@statewalker/webrun-http-browser 0.5.0 → 0.6.2

package/README.md

@@ -49,7 +49,8 @@ npm install @statewalker/webrun-http-browser
 | --- | --- |
 | `@statewalker/webrun-http-browser` | Page-side relay API: `newRemoteRelayChannel`, `initHttpService`, `callHttpService`, `splitServiceUrl`, `initServiceWorker`, `newServiceWorkerPort`, `getRelayWindowMessageHandler`; the MessagePort call primitives (`callChannel`, `handleChannelCalls`, `newInvokationChannel`, `sendStream`, `handleStreams`, `newRegistry`); plus everything re-exported from `@statewalker/webrun-http-streams` (`HttpError`, the client/server stubs), `@statewalker/webrun-streams` (stream and error helpers) and the `MessageTarget` family from `@statewalker/webrun-rpc` |
 | `@statewalker/webrun-http-browser/sw` | Same-origin adapter classes: `SwHttpAdapter` (page), `SwHttpDispatcher` (SW), `startHttpDispatcher` bootstrap; `start()` options `timeout` and `reloadIfUncontrolled` |
-| `@statewalker/webrun-http-browser/relay-sw` | IIFE bundle of the relay SW runtime — load via `importScripts` from a loader script in your relay origin |
+| `@statewalker/webrun-http-browser/relay-sw` | IIFE bundle of the relay SW runtime — load via `importScripts` from a loader script in your relay origin. No declarations: it takes its options from `self.RELAY_OPTIONS` |
+| `@statewalker/webrun-http-browser/relay-worker` | The same runtime as a typed ES module, for a host that bundles its own relay worker: `startRelayServiceWorker(self, options)`, plus `RelayServiceWorkerOptions` and `MountSpec` to type them (including a hand-written `self.RELAY_OPTIONS`) |
 | `@statewalker/webrun-http-browser/sw-worker` | IIFE bundle of the same-origin SW runtime — ditto, for same-origin apps |
 
 ## Examples
@@ -101,6 +102,125 @@ const res = await callHttpService(
 serving a mini site; [`demo/demo-2.html`](./demo/demo-2.html) pipes a
 local-disk folder (File System Access API) through it.
 
+### Mounting a service at a path
+
+A service can claim a path prefix instead of living at `/~<key>/`. Both the
+key and the path are the caller's, and several services can share **one**
+relay connection — the shape mounts exist for is an app at the origin root
+and, say, a gateway one level down, both reachable through the same iframe:
+
+```ts
+const connection = await newRemoteRelayChannel(/* … */);
+
+await initHttpService(appHandler, { key: "app", path: "/", port: connection.port });
+await initHttpService(meshHandler, { key: "mesh", path: "/peers/", port: connection.port });
+```
+
+A `CONNECT` is routed to the service named in its `key`, so the two never see
+each other's calls even though they share one port. (Earlier builds routed
+every `CONNECT` on a connection to every registered service, which collided
+whenever more than one service shared a port — fixed before this shipped.)
+
+The worker routes by the longest matching path prefix, so a catch-all at `/`
+does not shadow `/peers/`, and registration order does not matter. A service
+registered with no `path` is reachable at `/~<key>/`, exactly as before —
+unless the host declared that key in `mounts`, in which case the host's mount
+stands and the page need not repeat it.
+
+**A request that matches no mount is not the relay's** — the worker does not
+answer it at all, so the browser performs it exactly as it would with no
+worker installed. That is what lets a host serve its own files from the same
+origin, and it is why a root mount needs `exclude`.
+
+**The matched prefix is NOT stripped.** A handler mounted at `/peers/`
+receives `/peers/12D3Koo/llm`, not `/12D3Koo/llm` — the request reaches it
+with the path the browser asked for, whichever mount matched. A handler that
+wants to route relative to its mount keeps its own `basePath` and strips the
+prefix itself.
+
+These options are read by `startRelayServiceWorker`, which a host that
+bundles its own relay worker imports from
+`@statewalker/webrun-http-browser/relay-worker` and calls directly (see the
+options table below for the prebuilt-bundle equivalent):
+
+```ts
+import { startRelayServiceWorker } from "@statewalker/webrun-http-browser/relay-worker";
+
+startRelayServiceWorker(self, {
+  exclude: (url) =>
+    url.pathname === "/index.html" ||
+    url.pathname === "/relay.html" ||
+    url.pathname === "/relay-sw.js",
+  takeover: "first-wins",
+  canRegister: (client, _key) => new URL(client.url).pathname === "/relay.html",
+  decorateResponse: (response) => withMyHeaders(response),
+});
+```
+
+> **Mounting at `/` — set `takeover: "first-wins"` and `canRegister`.**
+> The default is `takeover: "last-wins"` with no `canRegister`, which is what
+> the relay has always done: the last page to REGISTER a key gets it. Before
+> mounts the worst that bought a rogue or buggy same-origin page was
+> `/~<key>/`; with mounts it can claim the **origin root**, and the mount is
+> persisted in IndexedDB, so it outlives the page and every worker restart.
+> On an origin where more than the host's own page can reach the relay,
+> `takeover: "first-wins"` keeps a live holder's key and `canRegister` says
+> which client may ask for it — set both, together, for any mount at `/`.
+
+A root mount claims *every* path under the worker's scope, including the
+host's own navigation. If `exclude` only covers the relay page and its
+worker script, a reload requests the host's own entry page — say
+`/index.html` — through the mount too, the mount has no handler for it, and
+the origin cannot come back. `exclude` needs three things, always: the relay
+page, the worker script, and the host's own entry page. That third one is
+easy to miss because nothing fails until the first reload.
+
+An excluded page is one the worker does not answer, and in Firefox such a
+page can load **uncontrolled** even while the worker is running — then its
+own `fetch()` never reaches the worker and its mounts look dead. The remedy
+is the one this package already ships for that case: call
+`awaitServiceWorkerControl(registration)` (exported from the package root)
+before relying on `fetch()` from an excluded page. A page *served by* a mount
+is a navigation the worker answers, so it is controlled from its first byte
+and needs nothing.
+
+#### `self.RELAY_OPTIONS` — options for the prebuilt worker
+
+`dist/relay-sw.js` is an IIFE loaded via classic `importScripts`, so a host
+that uses the shipped worker (rather than building its own from
+`startRelayServiceWorker`) cannot pass options as arguments. It reads them
+instead from `self.RELAY_OPTIONS`, which the host's own tiny worker script
+sets *before* importing the bundle:
+
+```js
+// relay-sw.js — served next to your relay page.
+self.RELAY_OPTIONS = {
+  exclude: (url) => url.pathname === "/index.html" || url.pathname === "/relay.html" || url.pathname === "/relay-sw.js",
+  takeover: "first-wins",
+};
+importScripts("/path/to/node_modules/@statewalker/webrun-http-browser/dist/relay-sw.js");
+```
+
+This is the only way a prebuilt-worker host reaches `exclude`, `takeover`,
+`canRegister` or `decorateResponse` — omit it and the worker boots with `{}`,
+exactly as it did before mounts. The bundle ships no declarations, so to type
+that object (in a TypeScript loader script, or to check it before shipping)
+import the type from the runtime entry:
+
+```ts
+import type { RelayServiceWorkerOptions } from "@statewalker/webrun-http-browser/relay-worker";
+
+declare const self: ServiceWorkerGlobalScope & { RELAY_OPTIONS?: RelayServiceWorkerOptions };
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `mounts` | none | A fixed table, for a host that knows its services at build time. Each entry is `{ key, path? , match? }`. A key declared here is the host's: a page's REGISTER or UNREGISTER for the same key never replaces or removes it, so the page can register with no `path` of its own. |
+| `exclude` | none | Paths the relay never claims — neither through the table nor through the `/~<key>/` spelling. Checked first. |
+| `canRegister` | everyone | Refuse a registration from the wrong page. |
+| `takeover` | `"last-wins"` | `"first-wins"` keeps a live holder's key. |
+| `decorateResponse` | none | Stamp headers on responses the relay makes; not applied to network fetches. |
+
 ### Same-origin mode
 
 Your page registers its own SW, handlers are local to the page:
@@ -277,13 +397,15 @@ imports keep working after those extractions. Its own surface is below.
 | `newRemoteRelayChannel(opts?)` | function | Embeds the hidden relay iframe, handshakes a `MessageChannel`, resolves a `RemoteRelayChannel`. |
 | `RemoteRelayChannelOptions` | interface | `baseUrl`, `url`, `container` — where the relay lives and what to append the iframe to. |
 | `RemoteRelayChannel` | interface | `{ baseUrl, port, close() }`. |
-| `initHttpService(handler, opts)` | function | Registers `handler` as the server for a service `key` on the relay. Returns a cleanup. |
+| `initHttpService(handler, opts)` | function | Registers `handler` as the server for a service `key` on the relay, optionally mounted at `path`. Several services may share one `port`. Returns a cleanup. |
 | `callHttpService(request, opts)` | function | Sends a `Request` to the service under `key`; resolves its `Response`. |
-| `ServiceOptions` | interface | `{ key: string; port: MessageTarget }` — shared by the two above. |
+| `ServiceOptions` | interface | `{ key: string; path?: string; port: MessageTarget }` — shared by the two above. `path` mounts the service (see [Mounting a service at a path](#mounting-a-service-at-a-path)); omitted, it stays at `/~<key>/`. |
 | `getRelayWindowMessageHandler(opts?)` | function | The `window.onmessage` handler that runs *inside* the relay iframe. |
 | `RelayWindowHandlerOptions` | interface | `swUrl`, `scopeUrl` for that handler. |
-| `splitServiceUrl(url, separator?)` | function | Splits a relay URL into service key + remaining path (default separator `~`). |
+| `splitServiceUrl(url, separator?)` | function | Splits a relay URL into service key + remaining path (default separator `~`); anchored to the pathname, so a query string like `?q=~foo` is never read as a service. |
 | `SplitServiceUrl` | interface | Its result shape. |
+| `startRelayServiceWorker(self, opts?)` | function | The SW side of the relay: routes `fetch` to the client that registered a mount, and answers `REGISTER`/`UNREGISTER`/`CONNECT`. Not re-exported from the package root — it is what the prebuilt `dist/relay-sw.js` calls internally; see [`self.RELAY_OPTIONS`](#selfrelay_options--options-for-the-prebuilt-worker). |
+| `RelayServiceWorkerOptions` | interface | `{ mounts?, exclude?, canRegister?, takeover?, decorateResponse? }` — see the options table in [Mounting a service at a path](#mounting-a-service-at-a-path). |
 
 ### ServiceWorker lifecycle
 
@@ -341,7 +463,7 @@ imports keep working after those extractions. Its own surface is below.
 | Entry | Purpose |
 | --- | --- |
 | `@statewalker/webrun-http-browser/sw` | `SwHttpAdapter` — the same-origin ServiceWorker adapter. |
-| `@statewalker/webrun-http-browser/relay-sw` | IIFE relay SW runtime, loadable via `importScripts(...)`. |
+| `@statewalker/webrun-http-browser/relay-sw` | IIFE relay SW runtime, loadable via `importScripts(...)`. Reads its options from `self.RELAY_OPTIONS`, set before the `importScripts` call. |
 | `@statewalker/webrun-http-browser/sw-worker` | IIFE same-origin SW runtime, loadable via `importScripts(...)`. |
 
 ## Internals

package/dist/index.js

@@ -2660,25 +2660,54 @@ async function sendHttpRequest(communicationPort, request) {
 */
 function splitServiceUrl(url, separator = "~") {
 	const str = `${url}`;
-	const idx = str.indexOf(separator);
-	let baseUrl = "";
-	let key = "";
-	let path = "";
-	if (idx >= 0) {
-		baseUrl = str.substring(0, idx + separator.length);
-		str.substring(idx + separator.length).replace(/^([^/]+)/, (match, $1) => {
-			baseUrl += match;
-			if (baseUrl.length < str.length) baseUrl += "/";
-			key = $1;
-			path = str.substring(baseUrl.length);
-			return "";
-		});
-	}
+	const empty = {
+		url: str,
+		key: "",
+		baseUrl: "",
+		path: ""
+	};
+	const hashIdx = str.indexOf("#");
+	const queryIdx = str.indexOf("?");
+	let strippedEnd = str.length;
+	if (hashIdx >= 0) strippedEnd = Math.min(strippedEnd, hashIdx);
+	if (queryIdx >= 0) strippedEnd = Math.min(strippedEnd, queryIdx);
+	const stripped = str.slice(0, strippedEnd);
+	let prefixEnd = 0;
+	const schemeMatch = stripped.match(/^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//);
+	if (schemeMatch) {
+		prefixEnd = schemeMatch[0].length;
+		const slashIdx = stripped.indexOf("/", prefixEnd);
+		if (slashIdx >= 0) prefixEnd = slashIdx;
+		else return empty;
+	} else if (stripped.startsWith("//")) {
+		prefixEnd = 2;
+		const slashIdx = stripped.indexOf("/", prefixEnd);
+		if (slashIdx >= 0) prefixEnd = slashIdx;
+		else return empty;
+	}
+	const prefix = stripped.slice(0, prefixEnd);
+	const pathPart = stripped.slice(prefixEnd);
+	let keyStart;
+	let rooted = false;
+	if (prefix === "") {
+		if (pathPart.startsWith(`/${separator}`)) {
+			rooted = true;
+			keyStart = separator.length + 1;
+		} else if (pathPart.startsWith(separator)) keyStart = separator.length;
+		else return empty;
+	} else {
+		if (!pathPart.startsWith(`/${separator}`)) return empty;
+		keyStart = separator.length + 1;
+	}
+	const rest = pathPart.slice(keyStart);
+	const slash = rest.indexOf("/");
+	const key = slash < 0 ? rest : rest.slice(0, slash);
+	if (key === "") return empty;
 	return {
 		url: str,
 		key,
-		baseUrl,
-		path
+		baseUrl: `${prefix === "" ? rooted ? "/" : "" : `${prefix}/`}${separator}${key}${slash < 0 ? "" : "/"}`,
+		path: slash < 0 ? "" : rest.slice(slash + 1)
 	};
 }
 //#endregion
@@ -2735,9 +2764,10 @@ async function registerServiceWorker({ swUrl, scopeUrl, type, timeout = DEFAULT_
 * Registers `handler` as the server for the given service `key` on the relay.
 * Returns a cleanup function that unregisters the service.
 */
-async function initHttpService(handler, { key, port }) {
+async function initHttpService(handler, { key, path, port }) {
 	return await registerConnectionsHandler({
 		key,
+		path,
 		communicationPort: port,
 		handler: async (_event, _data, callPort) => {
 			handleHttpRequests(callPort, handler);
@@ -2859,14 +2889,56 @@ async function initializeConnection({ key, communicationPort, ...options }) {
 	}
 	return channel.port1;
 }
-async function registerConnectionsHandler({ key, handler, communicationPort }) {
+async function registerConnectionsHandler({ key, path, handler, communicationPort }) {
 	const [register, cleanup] = newRegistry();
-	await callChannel(communicationPort, "REGISTER", { key });
+	await callChannel(communicationPort, "REGISTER", path == null ? { key } : {
+		key,
+		path
+	});
 	register(() => callChannel(communicationPort, "UNREGISTER", { key }));
-	register(handleChannelCalls(communicationPort, "CONNECT", async (event, data, port) => {
+	register(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, callType, key, handler) {
+	const listener = async (event) => {
+		const data = event.data;
+		if (!data || data.type !== callType) return;
+		if (data.params?.key !== key) return;
+		const [port, ...transfers] = event.ports ?? [];
+		const response = {};
+		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);
+}
 //#endregion
 export { CLAIM_CALL, DEFAULT_SERVICE_WORKER_TIMEOUT, DuplexSiteBuilder, HttpError, HttpParseError, PEER_ERROR_HEADER, ServiceWorkerControlError, TransportClosedError, awaitActiveServiceWorker, awaitServiceWorkerControl, callChannel, callHttpService, collect, collectBytes, collectString, decodeJsonl, decodeMessage, decodeText, defaultCodec, deserializeError, emulateMux, encodeJsonl, encodeMessage, encodeText, fetchOverDuplex, fromReadableStream, getRelayWindowMessageHandler, handleChannelCalls, handleClaimRequests, handleHttpRequests, handleStreams, httpCodec, httpFetch, httpServe, initHttpService, initServiceWorker, initializeConnection, joinLines, jsonEnvelopeCodec, map, newAsyncGenerator, newCreditGrantor, newCreditLedger, newHttpClientStub, newHttpCodec, newHttpServerStub, newInvokationChannel, newRegistry, newRemoteRelayChannel, newServiceWorkerPort, newSniffingCodec, normalizeToUint8Array, recieveIterator, registerConnectionsHandler, sendHttpRequest, sendIterator, sendStream, serializeError, serveFetchOverDuplex, splitLines, splitServiceUrl, toChunks, toReadableStream };

package/dist/relay/index-sw.d.ts

@@ -1,7 +1,92 @@
+import { type MountSpec, type MountTable } from "./mount-table.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 declare function readStoredEntry(value: unknown): RegisteredClient | undefined;
+/**
+ * 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 declare function resolveServiceKey(url: URL, table: MountTable, selfOrigin: string): string | undefined;
+/**
+ * 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 declare function resolveAfterRestore(restored: Promise<void>, url: URL, table: MountTable, selfOrigin: string): Promise<string | undefined>;
+/**
+ * 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 declare function applyRegisteredMount(table: MountTable, key: string, path: string | undefined, hostKeys?: ReadonlySet<string>): void;
+/**
+ * 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 declare function removeRegisteredMount(table: MountTable, key: string, hostKeys?: ReadonlySet<string>): void;
+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 declare function mayRegister(args: {
+    current?: RegisteredClient;
+    candidateId: string;
+    isCurrentLive: boolean;
+    takeover: "first-wins" | "last-wins";
+}): boolean;
 /**
  * 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 declare function startRelayServiceWorker(self: ServiceWorkerGlobalScope): () => void;
+export declare function startRelayServiceWorker(self: ServiceWorkerGlobalScope, options?: RelayServiceWorkerOptions): () => void;
 //# sourceMappingURL=index-sw.d.ts.map

package/dist/relay/index-sw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-sw.d.ts","sourceRoot":"","sources":["../../src/relay/index-sw.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,IAAI,CA4ElF"}
+{"version":3,"file":"index-sw.d.ts","sourceRoot":"","sources":["../../src/relay/index-sw.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAGlF,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,EACvB,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,IAAI,CAGN;AAED,MAAM,WAAW,yBAAyB;IACxC,uEAAuE;IACvE,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAC5C,8DAA8D;IAC9D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IAChC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,uEAAuE;IACvE,QAAQ,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC;IACtC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC;CACvE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,YAAY,GAAG,WAAW,CAAC;CACtC,GAAG,OAAO,CAIV;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,EAC9B,OAAO,GAAE,yBAA8B,GACtC,MAAM,IAAI,CAwJZ"}

package/dist/relay/index.d.ts

@@ -30,13 +30,18 @@ export interface InitServiceWorkerOptions {
 export declare function initServiceWorker(options: InitServiceWorkerOptions): Promise<ServiceWorker>;
 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;
 }
 /**
  * Registers `handler` as the server for the given service `key` on the relay.
  * Returns a cleanup function that unregisters the service.
  */
-export declare function initHttpService(handler: HttpHandler, { key, port }: ServiceOptions): Promise<() => void>;
+export declare function initHttpService(handler: HttpHandler, { key, path, port }: ServiceOptions): Promise<() => void>;
 /**
  * Sends a `Request` to the service registered under `key` on the relay and
  * resolves with the corresponding `Response`.
@@ -79,8 +84,10 @@ export interface InitializeConnectionOptions {
 export declare function initializeConnection({ key, communicationPort, ...options }: InitializeConnectionOptions): Promise<MessagePort | null>;
 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 declare function registerConnectionsHandler({ key, handler, communicationPort, }: RegisterConnectionsHandlerOptions): Promise<() => void>;
+export declare function registerConnectionsHandler({ key, path, handler, communicationPort, }: RegisterConnectionsHandlerOptions): Promise<() => void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/relay/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/relay/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAGpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAQ/D,cAAc,wBAAwB,CAAC;AAavC;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,CAAC,EAAE,yBAAyB,GAAG,WAAW,CAU1F;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC,CAEjG;AAgBD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,WAAW,EACpB,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,cAAc,GAC5B,OAAO,CAAC,MAAM,IAAI,CAAC,CASrB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,cAAc,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAInB;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,KAAgD,EAChD,QAAyC,EACzC,OAAO,GACR,GAAE,yBAA8B,GAAG,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CA2BtE;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,GAAG,CAAC;IACb,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,OAAgD,EAChD,GAAoC,EACpC,SAAyB,GAC1B,GAAE,yBAA8B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+C9D;AAED,MAAM,WAAW,2BAA2B;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,EAAE,aAAa,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAsB,oBAAoB,CAAC,EACzC,GAAG,EACH,iBAAiB,EACjB,GAAG,OAAO,EACX,EAAE,2BAA2B,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAc3D;AAED,MAAM,WAAW,iCAAiC;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/F,iBAAiB,EAAE,aAAa,CAAC;CAClC;AAED,wBAAsB,0BAA0B,CAAC,EAC/C,GAAG,EACH,OAAO,EACP,iBAAiB,GAClB,EAAE,iCAAiC,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAUzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/relay/index.ts"],"names":[],"mappings":"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"}

package/dist/relay/mount-table.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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;
+}
+export declare function newMountTable(options?: MountTableOptions): MountTable;
+//# sourceMappingURL=mount-table.d.ts.map

package/dist/relay/mount-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-table.d.ts","sourceRoot":"","sources":["../../src/relay/mount-table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2EAA2E;IAC3E,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;CACjC;AAyBD,wBAAgB,aAAa,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAyCzE"}

package/dist/relay/split-service-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"split-service-url.d.ts","sourceRoot":"","sources":["../../src/relay/split-service-url.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,EAAE,SAAS,SAAM,GAAG,eAAe,CAiBnF"}
+{"version":3,"file":"split-service-url.d.ts","sourceRoot":"","sources":["../../src/relay/split-service-url.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,EAAE,SAAS,SAAM,GAAG,eAAe,CA6EnF"}