@statewalker/webrun-http-browser 0.4.2 → 0.6.0

package/dist/index.js

@@ -1125,6 +1125,192 @@ function newRegistry(onError = console.error) {
 	});
 }
 //#endregion
+//#region src/core/deadline.ts
+/**
+* Settles like `promise` if it settles before `deadline` (a `Date.now()`
+* value). Otherwise calls `onTimeout`: an `Error` it returns rejects, any
+* other value resolves. Internal; not re-exported.
+*/
+function withDeadline(deadline, promise, onTimeout) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			const outcome = onTimeout();
+			if (outcome instanceof Error) reject(outcome);
+			else resolve(outcome);
+		}, Math.max(0, deadline - Date.now()));
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+	});
+}
+//#endregion
+//#region src/core/service-worker-control.ts
+/**
+* How long, by default, the page waits for its ServiceWorker to activate and
+* to take control before giving up. Generous: a first install downloads and
+* evaluates the worker script, which on a slow link takes seconds.
+*/
+const DEFAULT_SERVICE_WORKER_TIMEOUT = 3e4;
+/**
+* How long the page waits for `controllerchange` once the worker has
+* answered the `CLAIM` request. `clients.claim()` resolves only after the
+* browser has queued that event, so this is a grace period for delivery, not
+* a second budget.
+*/
+const CLAIM_GRACE_MS = 1e3;
+/** Channel call a page sends to ask its ServiceWorker to `clients.claim()` it. */
+const CLAIM_CALL = "CLAIM";
+/**
+* Why a page could not get a working ServiceWorker. `reason` says which wait
+* failed; check it (or `name`) rather than `instanceof`, because each of this
+* package's bundles carries its own copy of this class.
+*/
+var ServiceWorkerControlError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "ServiceWorkerControlError";
+		this.reason = reason;
+	}
+};
+/**
+* Resolves with the registration's worker once it is `activated`. Rejects
+* with a `ServiceWorkerControlError` (`reason: "activation-timeout"`) if that
+* takes longer than `timeout` — an install that throws or never finishes
+* would otherwise leave the caller waiting forever.
+*/
+async function awaitActiveServiceWorker(registration, { timeout = DEFAULT_SERVICE_WORKER_TIMEOUT } = {}) {
+	return await withDeadline(Date.now() + timeout, waitForActivated(registration), () => {
+		const worker = registration.installing ?? registration.waiting ?? registration.active;
+		return new ServiceWorkerControlError("activation-timeout", `ServiceWorker ${scriptUrl(worker)} (scope ${registration.scope}) did not activate within ${timeout} ms` + (worker ? `; it is "${worker.state}"` : "") + ". Check the worker script for errors during install (DevTools → Application → Service Workers), or raise the `timeout` option.");
+	});
+}
+/**
+* Resolves with the ServiceWorker that controls this page, once `registration`
+* has an activated worker and the page is controlled by it.
+*
+* A page can stay uncontrolled while its worker is active, and then no
+* `controllerchange` ever fires on its own:
+* - a hard reload (Ctrl+Shift+R) bypasses the worker for that load, and the
+*   worker's `clients.claim()` already ran when it activated;
+* - Firefox can leave a page loaded while the worker is running uncontrolled.
+*
+* So when the page is uncontrolled, this asks the active worker to claim it
+* again (a `CLAIM` channel call — this package's workers answer it) and waits
+* for `controllerchange`. Every wait is bounded by `timeout`. If control never
+* comes it reloads once (`reloadIfUncontrolled`) or rejects with a
+* `ServiceWorkerControlError` (`reason: "uncontrolled"`) that says what
+* happened and what to do.
+*/
+async function awaitServiceWorkerControl(registration, { timeout = DEFAULT_SERVICE_WORKER_TIMEOUT, reloadIfUncontrolled = false, container = navigator.serviceWorker } = {}) {
+	const deadline = Date.now() + timeout;
+	const controlled = waitForController(container);
+	try {
+		const active = await awaitActiveServiceWorker(registration, { timeout });
+		let controller = container.controller;
+		if (!controller) controller = await withDeadline(deadline, (async () => {
+			await Promise.race([callChannel(active, CLAIM_CALL, {}), controlled.promise]);
+			return await Promise.race([controlled.promise, delay(CLAIM_GRACE_MS, null)]);
+		})(), () => null);
+		if (controller) {
+			forgetReload(registration);
+			return controller;
+		}
+		if (reloadIfUncontrolled && markReload(registration)) {
+			location.reload();
+			return await new Promise(() => {});
+		}
+		forgetReload(registration);
+		throw new ServiceWorkerControlError("uncontrolled", `This page is not controlled by its ServiceWorker ${scriptUrl(active)} (scope ${registration.scope}), although the worker is active, and the worker did not take control when asked (clients.claim()) within ${timeout} ms. This happens after a hard reload (Ctrl+Shift+R / Cmd+Shift+R), which bypasses ServiceWorkers for that load, and in Firefox for some pages opened while the worker was already running. Requests from this page would not reach the worker. Reload the page normally, pass \`reloadIfUncontrolled: true\` to do that automatically, check that the page is inside the worker's scope, and that the worker answers the "${CLAIM_CALL}" request (this package's workers do).`);
+	} finally {
+		controlled.cancel();
+	}
+}
+/**
+* ServiceWorker side: answers the page's `CLAIM` request with
+* `clients.claim()`, which takes over every uncontrolled client in scope.
+* Returns a function that stops answering.
+*/
+function handleClaimRequests(self) {
+	return handleChannelCalls(self, CLAIM_CALL, (event) => {
+		const claimed = self.clients.claim().then(() => true);
+		event.waitUntil?.(claimed);
+		return claimed;
+	});
+}
+function waitForActivated(registration) {
+	return new Promise((resolve) => {
+		const watched = /* @__PURE__ */ new Set();
+		const check = () => {
+			const active = registration.active;
+			if (active?.state === "activated") {
+				registration.removeEventListener("updatefound", watch);
+				for (const worker of watched) worker.removeEventListener("statechange", check);
+				resolve(active);
+				return;
+			}
+			watch();
+		};
+		function watch() {
+			for (const worker of [
+				registration.installing,
+				registration.waiting,
+				registration.active
+			]) {
+				if (!worker || watched.has(worker)) continue;
+				watched.add(worker);
+				worker.addEventListener("statechange", check);
+			}
+		}
+		registration.addEventListener("updatefound", watch);
+		check();
+	});
+}
+function waitForController(container) {
+	let cancel = () => {};
+	return {
+		promise: new Promise((resolve) => {
+			const onChange = () => {
+				if (!container.controller) return;
+				cancel();
+				resolve(container.controller);
+			};
+			cancel = () => container.removeEventListener("controllerchange", onChange);
+			container.addEventListener("controllerchange", onChange);
+		}),
+		cancel
+	};
+}
+function delay(ms, value) {
+	return new Promise((resolve) => setTimeout(() => resolve(value), ms));
+}
+function scriptUrl(worker) {
+	return worker?.scriptURL ? `"${worker.scriptURL}"` : "(no worker)";
+}
+function reloadKey(registration) {
+	return `webrun-http-browser:reloaded-uncontrolled:${registration.scope}`;
+}
+/** Records the reload about to happen. `false` if one already happened, or if it cannot be recorded. */
+function markReload(registration) {
+	try {
+		const key = reloadKey(registration);
+		if (sessionStorage.getItem(key)) return false;
+		sessionStorage.setItem(key, "1");
+		return true;
+	} catch {
+		return false;
+	}
+}
+function forgetReload(registration) {
+	try {
+		sessionStorage.removeItem(reloadKey(registration));
+	} catch {}
+}
+//#endregion
 //#region ../webrun-http-streams/dist/index.js
 const CR = 13;
 const LF = 10;
@@ -2474,37 +2660,78 @@ 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
 //#region src/relay/index.ts
 /**
+* The URL of this module, kept in a variable on purpose. Bundlers (Vite
+* among them) rewrite every literal `new URL("<path>", import.meta.url)` into
+* an emitted asset at build time, before tree-shaking — so the defaults below
+* made every Vite consumer of this entry emit a dead copy of the package's
+* own `dist/index.js` (`"../"` resolves to the package, hence to its `main`).
+* Resolving against a variable is the same URL at run time and invisible to
+* that transform.
+*/
+const moduleUrl = import.meta.url;
+/**
 * Returns a MessagePort that transparently bridges messages to/from the
-* ServiceWorker controlling this page.
+* page's ServiceWorker: the one controlling the page, or — when the page is
+* not controlled (a hard reload, or a page Firefox left uncontrolled) — the
+* active worker of `registration`, which answers messages all the same.
 */
-function newServiceWorkerPort() {
+function newServiceWorkerPort(registration) {
 	const channel = new MessageChannel();
 	channel.port1.onmessage = (event) => {
-		navigator.serviceWorker.controller?.postMessage(event.data, [...event.ports]);
+		(navigator.serviceWorker.controller ?? registration?.active)?.postMessage(event.data, [...event.ports]);
 	};
 	navigator.serviceWorker.addEventListener("message", (event) => {
 		channel.port1.postMessage(event.data, [...event.ports]);
@@ -2512,53 +2739,35 @@ function newServiceWorkerPort() {
 	return channel.port2;
 }
 /**
-* Registers a ServiceWorker and resolves once it's activated and controlling the page.
+* Registers a ServiceWorker and resolves with it once it is activated: the
+* worker controlling the page, or the registration's active worker when the
+* page is not controlled. Messaging works either way, which is all the relay
+* needs; nothing here waits for control, because an uncontrolled page (hard
+* reload; Firefox) may never get it. Rejects with a
+* `ServiceWorkerControlError` if activation takes longer than `timeout`.
 */
-async function initServiceWorker({ swUrl, scopeUrl, type }) {
-	await navigator.serviceWorker.register(swUrl, {
+async function initServiceWorker(options) {
+	return (await registerServiceWorker(options)).worker;
+}
+async function registerServiceWorker({ swUrl, scopeUrl, type, timeout = DEFAULT_SERVICE_WORKER_TIMEOUT }) {
+	const registration = await navigator.serviceWorker.register(swUrl, {
 		type,
 		scope: scopeUrl
 	});
-	const worker = await getServiceWorkerController();
-	await awaitServiceWorkerActivation(worker);
-	return worker;
-}
-function getServiceWorkerController() {
-	return new Promise((resolve) => {
-		const container = navigator.serviceWorker;
-		if (container.controller) {
-			resolve(container.controller);
-			return;
-		}
-		const onChange = () => {
-			if (!container.controller) return;
-			resolve(container.controller);
-			container.removeEventListener("controllerchange", onChange);
-		};
-		container.addEventListener("controllerchange", onChange);
-	});
-}
-function awaitServiceWorkerActivation(worker) {
-	return new Promise((resolve) => {
-		if (worker.state === "activated") {
-			resolve();
-			return;
-		}
-		const onStateChange = () => {
-			if (worker.state !== "activated") return;
-			worker.removeEventListener("statechange", onStateChange);
-			resolve();
-		};
-		worker.addEventListener("statechange", onStateChange);
-	});
+	const active = await awaitActiveServiceWorker(registration, { timeout });
+	return {
+		registration,
+		worker: navigator.serviceWorker.controller ?? active
+	};
 }
 /**
 * 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);
@@ -2581,9 +2790,11 @@ async function callHttpService(request, { key, port }) {
 /**
 * Returns a `window.onmessage` handler for use inside the relay iframe:
 * it accepts a CONNECT message, starts the relay ServiceWorker, and bridges
-* the parent's MessagePort with the SW.
+* the parent's MessagePort with the SW. If the worker cannot be started, every
+* call the parent makes on that port is answered with the error, so the
+* parent's `initHttpService` / `callHttpService` reject instead of waiting.
 */
-function getRelayWindowMessageHandler({ swUrl = `${new URL("./index-sw.js", import.meta.url)}`, scopeUrl = `${new URL("../", import.meta.url)}` } = {}) {
+function getRelayWindowMessageHandler({ swUrl = `${new URL("./index-sw.js", moduleUrl)}`, scopeUrl = `${new URL("../", moduleUrl)}`, timeout } = {}) {
 	let externalPort;
 	return async (ev) => {
 		if (ev.data?.type !== "CONNECT") return;
@@ -2594,11 +2805,19 @@ function getRelayWindowMessageHandler({ swUrl = `${new URL("./index-sw.js", impo
 			return;
 		}
 		externalPort = newExternalPort;
-		await initServiceWorker({
-			swUrl,
-			scopeUrl
-		});
-		const serviceWorkerPort = newServiceWorkerPort();
+		let registration;
+		try {
+			({registration} = await registerServiceWorker({
+				swUrl,
+				scopeUrl,
+				timeout
+			}));
+		} catch (error) {
+			const serialized = serializeError(error);
+			externalPort.onmessage = (event) => event.ports[0]?.postMessage({ error: serialized });
+			throw error;
+		}
+		const serviceWorkerPort = newServiceWorkerPort(registration);
 		serviceWorkerPort.onmessage = (event) => {
 			externalPort?.postMessage(event.data, [...event.ports]);
 		};
@@ -2611,7 +2830,7 @@ function getRelayWindowMessageHandler({ swUrl = `${new URL("./index-sw.js", impo
 * Embeds a hidden relay iframe, establishes a MessageChannel with it, and
 * returns the port to be used with `initHttpService` / `callHttpService`.
 */
-async function newRemoteRelayChannel({ baseUrl = new URL("../public-relay/", import.meta.url), url = new URL("relay.html", baseUrl), container = document.body } = {}) {
+async function newRemoteRelayChannel({ baseUrl = new URL("../public-relay/", moduleUrl), url = new URL("relay.html", baseUrl), container = document.body } = {}) {
 	const messageChannel = new MessageChannel();
 	const { iframe, promise } = newIFrame(url);
 	Object.assign(iframe.style, {
@@ -2670,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 { DuplexSiteBuilder, HttpError, HttpParseError, PEER_ERROR_HEADER, TransportClosedError, callChannel, callHttpService, collect, collectBytes, collectString, decodeJsonl, decodeMessage, decodeText, defaultCodec, deserializeError, emulateMux, encodeJsonl, encodeMessage, encodeText, fetchOverDuplex, fromReadableStream, getRelayWindowMessageHandler, handleChannelCalls, 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 };
+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":"AAOA;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAwElF"}
+{"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

@@ -3,27 +3,45 @@ import type { MessageTarget } from "../core/message-target.js";
 export * from "./split-service-url.js";
 /**
  * Returns a MessagePort that transparently bridges messages to/from the
- * ServiceWorker controlling this page.
+ * page's ServiceWorker: the one controlling the page, or — when the page is
+ * not controlled (a hard reload, or a page Firefox left uncontrolled) — the
+ * active worker of `registration`, which answers messages all the same.
  */
-export declare function newServiceWorkerPort(): MessagePort;
+export declare function newServiceWorkerPort(registration?: ServiceWorkerRegistration): MessagePort;
 export interface InitServiceWorkerOptions {
     swUrl: string;
     scopeUrl?: string;
     type?: WorkerType;
+    /**
+     * Upper bound, in ms, for the wait for the worker to activate; past it the
+     * promise rejects with a `ServiceWorkerControlError`. Default
+     * `DEFAULT_SERVICE_WORKER_TIMEOUT` (30 s).
+     */
+    timeout?: number;
 }
 /**
- * Registers a ServiceWorker and resolves once it's activated and controlling the page.
+ * Registers a ServiceWorker and resolves with it once it is activated: the
+ * worker controlling the page, or the registration's active worker when the
+ * page is not controlled. Messaging works either way, which is all the relay
+ * needs; nothing here waits for control, because an uncontrolled page (hard
+ * reload; Firefox) may never get it. Rejects with a
+ * `ServiceWorkerControlError` if activation takes longer than `timeout`.
  */
-export declare function initServiceWorker({ swUrl, scopeUrl, type, }: InitServiceWorkerOptions): Promise<ServiceWorker>;
+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`.
@@ -32,13 +50,17 @@ export declare function callHttpService(request: Request, { key, port }: Service
 export interface RelayWindowHandlerOptions {
     swUrl?: string;
     scopeUrl?: string;
+    /** Passed to `initServiceWorker`: how long to wait for the relay worker to activate. */
+    timeout?: number;
 }
 /**
  * Returns a `window.onmessage` handler for use inside the relay iframe:
  * it accepts a CONNECT message, starts the relay ServiceWorker, and bridges
- * the parent's MessagePort with the SW.
+ * the parent's MessagePort with the SW. If the worker cannot be started, every
+ * call the parent makes on that port is answered with the error, so the
+ * parent's `initHttpService` / `callHttpService` reject instead of waiting.
  */
-export declare function getRelayWindowMessageHandler({ swUrl, scopeUrl, }?: RelayWindowHandlerOptions): (ev: MessageEvent) => Promise<void>;
+export declare function getRelayWindowMessageHandler({ swUrl, scopeUrl, timeout, }?: RelayWindowHandlerOptions): (ev: MessageEvent) => Promise<void>;
 export interface RemoteRelayChannelOptions {
     baseUrl?: URL;
     url?: URL;
@@ -62,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;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI/D,cAAc,wBAAwB,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,CASlD;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,KAAK,EACL,QAAQ,EACR,IAAI,GACL,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC,CAKnD;AAiCD,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;CACnB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,KAAsD,EACtD,QAA+C,GAChD,GAAE,yBAA8B,GAAG,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAoBtE;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,OAAsD,EACtD,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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"}