@statewalker/webrun-http-browser 0.5.0 → 0.6.2

package/dist/relay-sw.js

@@ -1533,6 +1533,51 @@
 		})(request);
 	}
 	//#endregion
+	//#region src/relay/mount-table.ts
+	/** `/` stays `/`; `/peers` and `/peers/` both become `/peers/`. */
+	function normalise(path) {
+		if (path === "" || path === "/") return "/";
+		const withSlash = path.startsWith("/") ? path : `/${path}`;
+		return withSlash.endsWith("/") ? withSlash : `${withSlash}/`;
+	}
+	/** Does `prefix` own `pathname`? `/peers/` owns `/peers/`, `/peers` and `/peers/x`. */
+	function owns(prefix, pathname) {
+		if (prefix === "/") return true;
+		if (pathname.startsWith(prefix)) return true;
+		return `${pathname}/` === prefix;
+	}
+	function newMountTable(options = {}) {
+		const entries = /* @__PURE__ */ new Map();
+		let seq = 0;
+		return {
+			set(key, spec) {
+				entries.set(key, {
+					key,
+					prefix: spec.path == null ? "" : normalise(spec.path),
+					match: spec.match,
+					seq: seq++
+				});
+			},
+			remove(key) {
+				entries.delete(key);
+			},
+			excludes(url) {
+				return options.exclude?.(url) === true;
+			},
+			find(url) {
+				if (options.exclude?.(url) === true) return void 0;
+				let best;
+				for (const entry of entries.values()) {
+					if (entry.prefix === "" || !owns(entry.prefix, url.pathname)) continue;
+					if (best == null || entry.prefix.length > best.prefix.length) best = entry;
+				}
+				if (best != null) return best.key;
+				const predicates = [...entries.values()].filter((entry) => entry.match != null).sort((a, b) => a.seq - b.seq);
+				for (const entry of predicates) if (entry.match?.(url) === true) return entry.key;
+			}
+		};
+	}
+	//#endregion
 	//#region src/relay/split-service-url.ts
 	/**
 	* Splits a URL of the form `<base>/<separator><key>/<path>` into parts.
@@ -1540,36 +1585,165 @@
 	*/
 	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-sw.ts
 	/**
+	* 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.
+	*/
+	function readStoredEntry(value) {
+		if (typeof value === "string") return { clientId: value };
+		if (typeof value !== "object" || value === null) return void 0;
+		const { clientId, path } = value;
+		if (typeof clientId !== "string" || clientId === "") return void 0;
+		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.
+	*/
+	function resolveServiceKey(url, table, selfOrigin) {
+		if (url.origin !== selfOrigin) return void 0;
+		if (table.excludes(url)) return void 0;
+		const mounted = table.find(url);
+		if (mounted != null) return mounted;
+		const { key } = splitServiceUrl(url);
+		return key === "" ? void 0 : 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.
+	*/
+	async function resolveAfterRestore(restored, url, table, selfOrigin) {
+		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).
+	*/
+	function applyRegisteredMount(table, key, path, hostKeys = /* @__PURE__ */ new Set()) {
+		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.
+	*/
+	function removeRegisteredMount(table, key, hostKeys = /* @__PURE__ */ new Set()) {
+		if (hostKeys.has(key)) return;
+		table.remove(key);
+	}
+	/**
+	* 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.
+	*/
+	function mayRegister(args) {
+		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.
 	*/
-	function startRelayServiceWorker(self) {
+	function startRelayServiceWorker(self, options = {}) {
 		const [register, clear] = newRegistry();
+		const mounts = newMountTable({ exclude: options.exclude });
+		const hostKeys = /* @__PURE__ */ new Set();
+		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) => {
 			e.waitUntil(self.skipWaiting());
 		});
@@ -1577,15 +1751,35 @@
 			e.waitUntil(self.clients.claim());
 		});
 		const clientsRegistry = newClientsRegistry({ self });
+		const restored = clientsRegistry.restoreMounts(mounts, hostKeys);
+		let restoreSettled = false;
+		const latch = () => {
+			restoreSettled = true;
+		};
+		restored.then(latch, latch);
 		register(handleClaimRequests(self));
 		register(handleChannelCalls(self, "REGISTER", async (event, data) => {
 			const source = event.source;
 			if (!source) return false;
-			const { key } = data;
-			return await clientsRegistry.addClient(key, source);
+			const { key, path } = data;
+			if (options.canRegister != null && !await options.canRegister(source, key)) throw new Error(`this client may not register "${key}"`);
+			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;
+			removeRegisteredMount(mounts, key, hostKeys);
 			return await clientsRegistry.removeClient(key);
 		}));
 		register(handleChannelCalls(self, "CONNECT", async (_event, data, port) => {
@@ -1594,30 +1788,43 @@
 			if (!client) throw new Error(`Target client was not found. Target key: "${key}".`);
 			return await callChannel(client, "CONNECT", data, port);
 		}));
+		/** Answers `request` as the service registered under `key`. */
+		async function serve(key, request, url) {
+			const params = splitServiceUrl(url);
+			try {
+				const channel = new MessageChannel();
+				const client = await clientsRegistry.getClient(key);
+				if (!client) throw HttpError.errorResourceGone(params);
+				if (!await callChannel(client, "CONNECT", {
+					type: "http",
+					key
+				}, channel.port2)) 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) => {
 			const request = event.request;
-			const params = splitServiceUrl(request.url);
-			const { key } = params;
-			if (!key) return;
+			const url = new URL(request.url);
+			if (restoreSettled) {
+				const key = resolveServiceKey(url, mounts, self.location.origin);
+				if (key == null) return;
+				event.respondWith(serve(key, request, url));
+				return;
+			}
 			event.respondWith((async () => {
-				try {
-					const channel = new MessageChannel();
-					const client = await clientsRegistry.getClient(key);
-					if (!client) throw HttpError.errorResourceGone(params);
-					if (!await callChannel(client, "CONNECT", {
-						type: "http",
-						key
-					}, channel.port2)) 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);
 			})());
 		};
 		self.addEventListener("fetch", fetchListener);
@@ -1629,7 +1836,11 @@
 		async function loadClientsIndex() {
 			if (!_index) {
 				const entries = await get(key) ?? [];
-				_index = Object.fromEntries(entries);
+				_index = {};
+				for (const [clientKey, value] of entries) {
+					const entry = readStoredEntry(value);
+					if (entry) _index[clientKey] = entry;
+				}
 			}
 			return _index;
 		}
@@ -1638,11 +1849,14 @@
 			await set(key, Object.entries(index));
 			return index;
 		}
-		async function addClient(clientKey, client) {
+		async function addClient(clientKey, client, path) {
 			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;
 		}
@@ -1653,11 +1867,21 @@
 			await storeClientsIndex();
 			return true;
 		}
+		async function getMount(clientKey) {
+			return (await loadClientsIndex())[clientKey];
+		}
+		async function restoreMounts(table, hostKeys = /* @__PURE__ */ new Set()) {
+			const index = await loadClientsIndex();
+			for (const [clientKey, entry] of Object.entries(index)) {
+				if (hostKeys.has(clientKey)) continue;
+				if (entry.path != null) table.set(clientKey, { path: entry.path });
+			}
+		}
 		async function getClient(clientKey) {
 			const index = await loadClientsIndex();
-			const clientId = index[clientKey];
-			if (!clientId) return void 0;
-			const client = await self.clients.get(clientId);
+			const entry = index[clientKey];
+			if (!entry) return void 0;
+			const client = await self.clients.get(entry.clientId);
 			if (!client) {
 				delete index[clientKey];
 				await storeClientsIndex();
@@ -1666,12 +1890,14 @@
 		}
 		return {
 			getClient,
+			getMount,
 			addClient,
-			removeClient
+			removeClient,
+			restoreMounts
 		};
 	}
 	//#endregion
 	//#region src/relay-sw.ts
-	startRelayServiceWorker(self);
+	startRelayServiceWorker(self, self.RELAY_OPTIONS ?? {});
 	//#endregion
 })();

package/dist/relay-worker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The relay ServiceWorker runtime, for a host that builds its own worker.
+ *
+ * TWO WAYS TO SHIP THE RELAY WORKER, and this is the typed one. A host that
+ * takes the prebuilt bundle loads `@statewalker/webrun-http-browser/relay-sw`
+ * through classic `importScripts` and passes its options in
+ * `self.RELAY_OPTIONS`, which cannot be typed from the outside because that
+ * bundle ships no declarations. A host that bundles its own worker imports
+ * this module instead and calls `startRelayServiceWorker(self, { … })`
+ * directly, with `RelayServiceWorkerOptions` to type the options — including
+ * `self.RELAY_OPTIONS`, for a host writing the tiny loader script by hand.
+ *
+ * Kept as its own entry rather than re-exported from the package root: this
+ * code only runs inside a ServiceWorker, and the root entry is what pages
+ * import.
+ */
+export type { RelayServiceWorkerOptions } from "./relay/index-sw.js";
+export { startRelayServiceWorker } from "./relay/index-sw.js";
+export type { MountSpec } from "./relay/mount-table.js";
+//# sourceMappingURL=relay-worker.d.ts.map

package/dist/relay-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-worker.d.ts","sourceRoot":"","sources":["../src/relay-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,YAAY,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,YAAY,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC"}