@statewalker/httpeers-member 0.1.4

package/src/browser.ts

@@ -0,0 +1,103 @@
+/**
+ * The BROWSER half of a member: the platform object, the two IndexedDB
+ * stores, and one function that assembles a page session out of them.
+ *
+ * EVERYTHING BROWSER-BOUND IS BEHIND THIS ENTRY, and that is a load-bearing
+ * arrangement rather than tidiness. `idb-keyval` needs a real IndexedDB;
+ * `@libp2p/webrtc`'s Node build loads a native module and throws on import;
+ * `@statewalker/webrun-http-browser/sw` is a ServiceWorker adapter. Any of
+ * them reachable from `./index.ts` would make a Node member fail at import
+ * time, which `tests/boundary.test.ts` now measures by reachability.
+ *
+ * `createSession` IS THE ONLY THING HERE THAT IS NOT A RE-EXPORT. It is the
+ * defaults `session.ts` deliberately does not carry: the platform, the two
+ * stores, `location.search` and the reload. A page that wants to substitute
+ * any of them passes it and this steps aside.
+ */
+
+import { del, get, set } from "idb-keyval";
+import { browserPlatform } from "./browser-platform.js";
+import type { AsyncBytesBackend, AsyncKeyValueBackend } from "./kv.js";
+import { createMeshMemory } from "./mesh-memory.js";
+import type { PeerSession, PeerSessionInit } from "./session.js";
+import { createIdentityStore, createPeerSession } from "./session.js";
+
+export { type BrowserPlatformInit, browserPlatform } from "./browser-platform.js";
+export {
+  type CreateBrowserNodeInit,
+  createBrowserNode,
+  dialNeedsPermissiveGater,
+} from "./browser-profile.js";
+export {
+  DEFAULT_CONTROL_TIMEOUT_MS,
+  DEFAULT_SERVICE_WORKER_URL,
+  type MountEdgeInit,
+  mountEdge,
+  UncontrolledPageError,
+} from "./edge.js";
+export {
+  type WakeDocument,
+  type WakeWindow,
+  type WatchPageWakeInit,
+  watchPageWake,
+} from "./page-wake.js";
+
+// THE SESSION ITSELF IS NOT RE-EXPORTED HERE. It is isomorphic and lives at
+// the root, and two import paths to one symbol is how a package ends up with
+// two versions of a type that look identical and are not.
+
+/** The page's own globals, declared locally — see `./page-wake.ts` for why not `lib: dom`. */
+declare const location: { search: string; reload(): void };
+
+/** The real thing: the same IndexedDB store `@statewalker/webrun-http-browser` already uses. */
+export function idbBackend(): AsyncKeyValueBackend {
+  return {
+    get: async (key) => (await get<string>(key)) ?? undefined,
+    set: async (key, value) => await set(key, value),
+    delete: async (key) => await del(key),
+  };
+}
+
+export function idbBytesBackend(): AsyncBytesBackend {
+  return {
+    get: async (key) => (await get<Uint8Array>(key)) ?? undefined,
+    set: async (key, value) => await set(key, value),
+    delete: async (key) => await del(key),
+  };
+}
+
+/**
+ * `PeerSessionInit` with every browser-supplied part made optional.
+ *
+ * The four that become optional are exactly the four `session.ts` refuses to
+ * default, and they are listed there with the reason. `serviceWorkerUrl` and
+ * `dev` are here rather than there because they are `browserPlatform`'s
+ * arguments, and a page that passes its own `platform` has no use for them.
+ */
+export interface CreateSessionInit
+  extends Omit<PeerSessionInit, "platform" | "identity" | "meshMemory" | "reload" | "search"> {
+  platform?: PeerSessionInit["platform"];
+  identity?: PeerSessionInit["identity"];
+  meshMemory?: PeerSessionInit["meshMemory"];
+  reload?: () => void;
+  /** Defaults to `location.search`, read once at `start()`. */
+  search?: string;
+  /** Where the ServiceWorker script lives — see `mountEdge`. */
+  serviceWorkerUrl?: string;
+  /** Relax libp2p's dial gater for loopback and private addresses. Off in production. */
+  dev?: boolean;
+}
+
+export function createSession(init: CreateSessionInit): PeerSession {
+  return createPeerSession({
+    ...init,
+    search: init.search ?? location.search,
+    platform:
+      init.platform ??
+      browserPlatform({ serviceWorkerUrl: init.serviceWorkerUrl, dev: init.dev ?? false }),
+    identity: init.identity ?? createIdentityStore({ backend: idbBytesBackend() }),
+    meshMemory: init.meshMemory ?? createMeshMemory({ backend: idbBackend() }),
+    reload: init.reload ?? ((): void => location.reload()),
+  });
+}
+export { type ResetResult, resetBrowserState } from "./reset.js";

package/src/connection-kind.ts

@@ -0,0 +1,53 @@
+/**
+ * Is this peer reached directly, or through the relay?
+ *
+ * WHY THIS EXISTS. libp2p does not upgrade a circuit to WebRTC on its own:
+ * `join.ts`'s `preDialPeer` dials `<relay>/p2p-circuit/webrtc/p2p/<peer>`
+ * explicitly, and the circuit's only job there is to carry the SDP exchange.
+ * When that dial fails -- symmetric NAT on a mobile carrier, a VPN, no reachable
+ * STUN -- `edge-dispatch.ts` SWALLOWS the failure by design and the call is
+ * attempted anyway. `remote()` then dials by peer id, which resolves through the
+ * peerStore to a bare `/p2p-circuit` address, and every byte crosses the relay.
+ *
+ * That fallback works. What it does not do is announce itself, and the silence
+ * is the problem: it is 10-100x slower, it spends the relay operator's
+ * bandwidth instead of going peer-to-peer, and while the relay applied a
+ * per-connection data cap it truncated transfers mid-stream. The visible
+ * symptom was broken images in a gallery, with one of them loading fine in a
+ * fresh tab -- which reads as random corruption rather than as a transport
+ * that quietly changed underneath.
+ *
+ * Reading the open connection's own address is the whole diagnosis, and it is
+ * one call. Strings in, so this module needs no libp2p import and is testable
+ * under plain Node.
+ */
+
+export type ConnectionKind = "direct" | "relayed" | "none";
+
+/**
+ * Classify the connections open to one peer, from their multiaddrs.
+ *
+ * `/webrtc` present means the WebRTC upgrade completed and the relay is no
+ * longer in the data path. A `/p2p-circuit` WITHOUT it means it did not, and
+ * traffic is being relayed. Direct wins when both are open, because that is the
+ * one libp2p will actually use.
+ */
+export function classifyConnection(remoteAddrs: readonly string[]): ConnectionKind {
+  if (remoteAddrs.length === 0) return "none";
+  if (remoteAddrs.some((addr) => addr.includes("/webrtc"))) return "direct";
+  if (remoteAddrs.some((addr) => addr.includes("/p2p-circuit"))) return "relayed";
+  // Anything else -- a plain TCP or WebSocket address -- is a direct dial.
+  return "direct";
+}
+
+/** One line a page can render unconditionally, saying what the kind means rather than naming it. */
+export function describeConnection(kind: ConnectionKind): string {
+  switch (kind) {
+    case "direct":
+      return "direct (WebRTC) — data goes peer to peer, the relay is not involved";
+    case "relayed":
+      return "relayed — the WebRTC upgrade did not succeed, so every byte crosses the relay: expect it to be slow";
+    case "none":
+      return "not connected yet";
+  }
+}

package/src/describe-error.ts

@@ -0,0 +1,76 @@
+/**
+ * Turn anything thrown into something a person can act on.
+ *
+ * WHY THIS EXISTS. Every "could not reach the relay" message in this app ended
+ * with `Cause: ${String(err)}`, and a failed WebSocket does not reject with an
+ * `Error` -- it rejects with a DOM `Event`. `String(event)` is
+ * **"[object Event]"**. A phone that could not reach the relay reported exactly
+ * that, and it named nothing: not the URL, not whether the socket ever opened,
+ * not whether it was closed or refused. The one message whose entire job was to
+ * explain a connection failure discarded every fact about it.
+ *
+ * The event carries what is needed -- `type`, `target.url`, `target.readyState`
+ * and, for a close event, `code` and `reason`. This reads them defensively,
+ * because an object that is not what we assume must not turn a bad error message
+ * into a second exception thrown while reporting the first.
+ */
+
+/** WebSocket.readyState, in words. The bare number tells a reader nothing. */
+const READY_STATE = ["CONNECTING", "OPEN", "CLOSING", "CLOSED"] as const;
+
+function pick(obj: unknown, key: string): unknown {
+  try {
+    return obj != null && typeof obj === "object"
+      ? (obj as Record<string, unknown>)[key]
+      : undefined;
+  } catch {
+    // A getter that throws must not take the error report down with it.
+    return undefined;
+  }
+}
+
+export function describeError(err: unknown): string {
+  if (err instanceof Error) {
+    const cause = (err as { cause?: unknown }).cause;
+    if (cause == null || cause === err) return err.message;
+    // Compare the DESCRIPTIONS, not the objects. libp2p wraps a WebSocket
+    // error event in an Error whose `cause` is a different object describing
+    // the same failure, so identity comparison lets it print twice --
+    // "socket CLOSED (cause: ... socket CLOSED)" -- which reads like two
+    // problems.
+    const described = describeError(cause);
+    return err.message.includes(described) ? err.message : `${err.message} (cause: ${described})`;
+  }
+
+  const type = pick(err, "type");
+  if (typeof type === "string") {
+    const target = pick(err, "target");
+    const parts: string[] = [`${type} event`];
+
+    const url = pick(target, "url");
+    if (typeof url === "string" && url !== "") parts.push(url);
+
+    const state = pick(target, "readyState");
+    if (typeof state === "number" && READY_STATE[state] != null) {
+      parts.push(`socket ${READY_STATE[state]}`);
+    }
+
+    const code = pick(err, "code");
+    if (typeof code === "number") parts.push(`code ${code}`);
+
+    const reason = pick(err, "reason");
+    if (typeof reason === "string" && reason !== "") parts.push(`reason "${reason}"`);
+
+    // A `error` event on a socket still CONNECTING means the connection was
+    // never established -- DNS, TLS, a proxy or a blocked port -- rather than
+    // anything the peers said to each other. That distinction is the whole
+    // value of printing the state.
+    return parts.join(", ");
+  }
+
+  try {
+    return String(err);
+  } catch {
+    return "an error that could not be converted to a string";
+  }
+}

package/src/edge-control.ts

@@ -0,0 +1,94 @@
+/**
+ * Turning a failure to get the page's ServiceWorker into an error a user can
+ * act on.
+ *
+ * THE HANG THIS USED TO GUARD. A page can load UNCONTROLLED while its worker
+ * is already active -- a HARD RELOAD (Ctrl+Shift+R; Firefox's
+ * `location.reload(true)`) bypasses the worker by spec, and Firefox has left a
+ * second tab uncontrolled too. The worker claimed its clients when it
+ * activated, long ago, so no `controllerchange` ever comes. Up to
+ * `@statewalker/webrun-http-browser` 0.4, `SwHttpAdapter.start()` then waited
+ * forever: llm-chat's mesh.html sat at "Joining… (mounting-edge)" after every
+ * hard reload, and this file carried a reload guard of its own.
+ *
+ * SINCE 0.5 THE LIBRARY RECOVERS IT ITSELF. `start()` asks the active worker to
+ * claim the page again (a `CLAIM` call, answered with `clients.claim()` by the
+ * package's own `sw-worker` -- which is what this stack's `/sw.js` is), so a
+ * hard-reloaded page is taken over in place, with no navigation. Every wait is
+ * bounded by `timeout`; past it `start()` rejects with a
+ * `ServiceWorkerControlError` whose `reason` says which wait failed. And with
+ * `reloadIfUncontrolled` it reloads once, guarded by `sessionStorage`, when the
+ * claim did not take. Measured in Chromium and Firefox by
+ * `packages/httpeers-browser-conformance/scripts/edge-reload.mjs`.
+ *
+ * What is left here is the message: `edgeStartError` maps the library's error
+ * onto the ones `mountEdge` has always thrown, so a page shows "close the tab
+ * and reopen it" rather than a library's diagnostic. It matches on `name` and
+ * `reason`, not `instanceof`: every bundle of webrun-http-browser carries its
+ * own copy of the class.
+ */
+
+/** The error a page shows when it cannot get its ServiceWorker's control. */
+export class UncontrolledPageError extends Error {
+  constructor(detail: string, options?: { cause?: unknown }) {
+    super(
+      "This page isn't controlled by its ServiceWorker, so the mesh cannot be reached through " +
+        `it — close the tab and reopen it. (${detail})`,
+      options,
+    );
+    this.name = "UncontrolledPageError";
+  }
+}
+
+/** The shape of webrun-http-browser's `ServiceWorkerControlError`, matched structurally. */
+interface ControlErrorLike {
+  name: "ServiceWorkerControlError";
+  reason: string;
+  message: string;
+}
+
+function isControlError(error: unknown): error is ControlErrorLike {
+  return (
+    error instanceof Error &&
+    error.name === "ServiceWorkerControlError" &&
+    typeof (error as Partial<ControlErrorLike>).reason === "string"
+  );
+}
+
+/**
+ * The error `mountEdge` throws when `SwHttpAdapter.start()` rejects:
+ *
+ *   - `reason: "uncontrolled"` -- the worker is active but did not take the
+ *     page when asked, and the one automatic reload was already spent (or
+ *     could not be guarded) -> `UncontrolledPageError`;
+ *   - `"activation-timeout"` / `"unresponsive"` -- the worker never activated,
+ *     or controls the page but did not answer -> an `Error` naming the worker
+ *     and the bound, and saying what to do;
+ *   - anything else is not a control failure and is returned unchanged.
+ *
+ * The library's own error is kept as `cause`, for DevTools.
+ */
+export function edgeStartError(
+  error: unknown,
+  serviceWorkerUrl: string,
+  timeoutMs: number,
+): unknown {
+  if (!isControlError(error)) return error;
+  if (error.reason === "uncontrolled") {
+    return new UncontrolledPageError(
+      "its ServiceWorker is active but did not take control when asked, and the page " +
+        "has already been reloaded once to recover, or could not be",
+      { cause: error },
+    );
+  }
+  const what =
+    error.reason === "activation-timeout"
+      ? "did not activate"
+      : "did not answer the page, although it controls it,";
+  return new Error(
+    `mountEdge: the ServiceWorker ${serviceWorkerUrl} ${what} within ` +
+      `${Math.round(timeoutMs / 1000)} s. Close the tab and reopen it; if that does not help, ` +
+      "clear this site's data in the browser to remove the ServiceWorker and start clean.",
+    { cause: error },
+  );
+}

package/src/edge-dispatch.ts

@@ -0,0 +1,295 @@
+/**
+ * The one module that sits between a page's own `fetch()` and this peer's
+ * `dispatch`. Everything a request needs in order to survive the crossing
+ * page -> ServiceWorker -> `SwHttpAdapter` -> `peer.dispatch` lives here,
+ * and nowhere else -- above all, NOT in the page.
+ *
+ * IT EXISTS SO THAT A PAGE IS AN ORDINARY HTTP CLIENT. The project's
+ * central bet is that application code calls a mesh peer with a plain
+ * `fetch()` -- no SDK, no client library. A page that had to hand-assemble
+ * a bearer header on every call, strip a mount prefix, or parse an error
+ * message string to tell "gone" from "refused" would have an SDK; it would
+ * just be an undocumented one, reimplemented per page. This module is the
+ * runtime's side of that bet.
+ *
+ * Kept dependency-free of libp2p AND of `@statewalker/webrun-http-browser`
+ * on purpose (only `httpeers.core`, all of it pure): that is what lets
+ * every rule below be proven under plain Node in `tests/browser-edge-
+ * dispatch.test.ts` rather than deferred to Task 15's Playwright run.
+ *
+ * THREE JOBS, IN ORDER.
+ *
+ * 1. STRIP THE EDGE'S OWN MOUNT PREFIX. Verified directly against
+ *    `@statewalker/webrun-http-browser@workspace:0.3.3`, not assumed:
+ *    `SwHttpAdapter._handleHttpRequest` (`src/sw/http-sw-dispatcher.ts`)
+ *    selects a handler by `requestUrl.indexOf(urlPrefix) === 0` and then
+ *    calls `handler(request)` with the ORIGINAL, UNMODIFIED request. So a
+ *    page fetching `${baseUrl}${peerId}/search` -- where `baseUrl` ends in
+ *    `/${key}/`, and `key` must be the first path segment
+ *    (`edge-guard.ts`'s `assertKeyMatchesPrefix`; `SwHttpDispatcher` keys
+ *    its channel lookup on that segment, so mounting at `/` is not
+ *    available) -- reaches `dispatch` with pathname
+ *    `/${key}/${peerId}/search`. `httpeers.core`'s router
+ *    (`router.ts`'s `route`) reads the FIRST segment and asks
+ *    `looksLikePeerId`; `key` is not a peer id, so the request is served
+ *    LOCALLY against a path no mount claims -- a 404 whose body says "not
+ *    found", three layers away from the mistake. Stripping the prefix here
+ *    is what makes the router see `/${peerId}/search`, which is the shape
+ *    it documents.
+ *
+ * 2. ATTACH THE MEMBERSHIP TOKEN (Ruling 59). `peer.call()` turns a
+ *    `{ token }` option into a `MESH_TOKEN_HEADER` header (`peer-request.ts`);
+ *    `fetch()` has no such option, so without this every mesh call from a
+ *    page would arrive at the provider tokenless and be refused 401. The
+ *    token is NOT the page's to hold: it rotates on each 5 s heartbeat
+ *    inside `startJoin`'s closure (`join.ts`), so a page that read one and
+ *    kept it would be sending a stale token within seconds. `token()` is
+ *    therefore called per request, never snapshotted.
+ *
+ * 3. TURN A THROWN `PeerCallError` INTO A RESPONSE (Ruling 60). `remote()`
+ *    THROWS T-2's typed error; nothing between it and the page converts it
+ *    to a Response, and `SwHttpDispatcher`'s own catch
+ *    (`http-sw-dispatcher.ts`) collapses any thrown handler error into a
+ *    bare 500 with no body. A page would then see one indistinguishable
+ *    500 for a departed peer, a reset stream and a timeout -- precisely the
+ *    "no way to tell 'this peer is gone' from 'this peer refused you'
+ *    without parsing a message string" that `httpeers.core`'s `errors.ts`
+ *    exists to end. The mapping below forwards `kind` in the body so the
+ *    page can `switch` on it.
+ *
+ * WHY THE STATUS TABLE LIVES IN THE APP AND NOT IN `httpeers.core`. Same
+ * split the core already uses for `allowForward` (supplied by the caller,
+ * never decided in the router): a status code is policy. `errors.ts`
+ * anticipated this crossing -- `kind` exists, in its own words, "so a
+ * caller can `switch` on it, or forward it across a boundary that cannot
+ * carry a class reference" -- but anticipating the crossing is not owning
+ * the status choice.
+ *
+ * 4. MAKE SURE A ROUTE TO THE TARGET PEER EXISTS FIRST (Task 15). Added
+ *    after the Playwright suite found that this had NEVER worked: a page
+ *    calling ANOTHER PAGE got `peer-unreachable`, every time, while a Node
+ *    peer calling that same browser provider over the same relay got a 200.
+ *    The cause is not in the provider and not in the transport --
+ *    `httpeers.core`'s `remote()` dials by PEER ID, which resolves through
+ *    libp2p's peerStore, and a browser peer's peerStore entry for another
+ *    browser peer is either absent or a bare `/p2p-circuit` address that
+ *    libp2p refuses to open `/httpeers/1.0.0` over. Something has to dial
+ *    `<relay>/p2p-circuit/webrtc/p2p/<peer>` explicitly, exactly as
+ *    `peer-runtime.ts` already does for the HUB at startup, and the page
+ *    cannot be the thing that does it without becoming the SDK this module
+ *    exists to prevent. So the edge does it, through the `ensureRoute` hook
+ *    below -- a callback, so this module stays libp2p-free and testable
+ *    under plain Node (see the note above).
+ *
+ *    IT NEVER FAILS THE CALL ITSELF. A dial that throws is swallowed and
+ *    `dispatch` is attempted anyway: the call that follows produces T-2's
+ *    own typed `PeerCallError` -- with the right `kind` for the page to
+ *    render -- whereas a rethrow here would surface as an untyped 500 from
+ *    `SwHttpDispatcher`'s catch and lose exactly the distinction job 3
+ *    exists to preserve.
+ *
+ * THIS IS A LOCAL INGRESS, AND ONLY THAT. Traffic arriving from other peers
+ * over libp2p does NOT come through here -- `serveTransport` dispatches it to
+ * `peer.dispatch` directly, which is what keeps our token off it (handing our
+ * token to inbound traffic would let any peer that can reach us borrow our
+ * membership for a call to a third party).
+ *
+ * So the first thing this does is STRIP the proven-peer header. A page builds
+ * the requests that enter its own edge; a header here is a claim, not a fact,
+ * and nothing downstream can tell the difference. An earlier version branched
+ * on `lookupPeer(req) !== undefined` to mean "arrived from the network" --
+ * correct while that binding was a WeakMap a page could not write, and a
+ * forgery hole the moment it became a header. `tests/ingress-forgery.test.ts`
+ * holds that shut.
+ */
+import type { FetchHandler, PeerErrorKind, PeerIdStr } from "@statewalker/httpeers-core";
+import {
+  bodyOf,
+  json,
+  MESH_TOKEN_HEADER,
+  PeerCallError,
+  setMeshToken,
+  stripPeerBinding,
+} from "@statewalker/httpeers-core";
+
+/**
+ * `PeerErrorKind` -> HTTP status, the whole table.
+ *
+ * A timeout is a 504 (`Gateway Timeout`) because that is literally what
+ * happened: this peer, acting as the page's gateway onto the mesh, gave up
+ * waiting for the peer behind it. Everything else is a 502 (`Bad Gateway`):
+ * the upstream peer could not be reached, does not speak the protocol, reset
+ * the stream, blew a relay limit, or offered only a limited connection the
+ * call did not opt in to -- all of them "the gateway could not
+ * get an answer from upstream", none of them a fault in the request the page
+ * made. Deliberately never a 5xx that would blame the page's own request
+ * (a 400-family status), and never a 500: a 500 here is reserved for a
+ * genuine bug (see `createEdgeDispatch`'s rethrow).
+ */
+export const PEER_ERROR_STATUS: Readonly<Record<PeerErrorKind, number>> = {
+  "request-timeout": 504,
+  "peer-unreachable": 502,
+  "protocol-unsupported": 502,
+  "stream-reset": 502,
+  "relay-limit-exceeded": 502,
+  "limited-connection": 502,
+  unknown: 502,
+};
+
+/** The body shape a page reads back from a failed mesh call. `kind` is the discriminant to `switch` on; `error` is for a human, never for a `switch`. */
+export interface PeerErrorBody {
+  error: string;
+  kind: PeerErrorKind;
+  peerId: string;
+}
+
+export interface EdgeDispatchInit {
+  /** This peer's own router -- `peer.dispatch`. Never called with a modified request unless the request originated locally; see the module comment. */
+  dispatch: FetchHandler;
+  /** The ServiceWorker adapter key. Requests arriving from the page still carry `/${key}` on their path -- job 1 above. */
+  key: string;
+  /** This peer's current membership token, READ AT CALL TIME -- `JoinHandle.token`. */
+  token: () => string;
+  /**
+   * Establish a usable route to `peerId` before the call rides it -- job 4
+   * above. Optional: omitting it restores the pre-Task-15 behaviour, which
+   * is correct for a caller whose peers are already connected (every Node
+   * suite in this app) and broken for a browser page (see job 4).
+   *
+   * CALLED FOR EVERY PEER-ID-SHAPED FIRST SEGMENT, INCLUDING THIS PEER'S
+   * OWN. This module knows the shape of a peer id (`targetPeerId`) and not
+   * which one it is: `createEdgeDispatch` is never told its own peer id, and
+   * giving it one only to skip a call would duplicate a check the
+   * implementation has to make anyway. `join.ts`'s `createRouteEnsurer` is
+   * where "that is us" is recognised and returns immediately. An
+   * implementation that does not know its own id must therefore tolerate
+   * being asked to route to itself.
+   *
+   * Called once per outbound request that names a peer; an implementation is
+   * expected to be cheap when a route already exists, because it is on the
+   * path of every single mesh call the page makes.
+   */
+  ensureRoute?: (peerId: PeerIdStr) => Promise<void>;
+}
+
+/**
+ * The peer id an outbound request is addressed to -- the first path segment,
+ * when it looks like one -- or `null` for a request this peer serves itself.
+ *
+ * THE SHAPE TEST IS A COPY, AND IT SHOULD NOT BE. `httpeers.core`'s
+ * `router.ts` has exactly this function (`looksLikePeerId`) and it is the
+ * one that decides, three layers down, whether the first segment is treated
+ * as a peer id at all. It is not exported, so this module cannot share it,
+ * and a copy that drifts from it would make `ensureRoute` dial for requests
+ * the router serves locally (harmless -- the dial is skipped for a
+ * non-member) or, worse, skip the dial for requests the router forwards
+ * (the Task 15 bug, back again). Reported to the core package rather than
+ * worked around further; see this task's report.
+ */
+export function targetPeerId(pathname: string): PeerIdStr | null {
+  const [, first = ""] = pathname.split("/");
+  const looksLikePeerId =
+    /^12D3Koo[A-Za-z0-9]{40,}$/.test(first) ||
+    /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/.test(first) ||
+    /^k51[a-z0-9]{55,}$/.test(first);
+  return looksLikePeerId ? first : null;
+}
+
+/**
+ * Removes a leading `/${key}` segment from `pathname`, respecting segment
+ * boundaries: with `key` `"app"`, `/app/x` -> `/x` and `/app` -> `/`, but
+ * `/application/x` is left alone (it is not this prefix, it merely starts
+ * with the same characters -- the same trap `httpeers.core`'s own mount
+ * matching documents in `router.ts`, "`/test` does NOT match `/testing`").
+ *
+ * Exported for its own test: this is pure string logic and there is no
+ * reason to reach it only through a Request.
+ */
+export function stripEdgePrefix(pathname: string, key: string): string {
+  const prefix = `/${key}`;
+  if (pathname === prefix) return "/";
+  if (pathname.startsWith(`${prefix}/`)) return pathname.slice(prefix.length);
+  return pathname;
+}
+
+/**
+ * Wraps `dispatch` with the three jobs above, for mounting on the
+ * ServiceWorker edge (`edge.ts`'s `mountEdge`). The result is still a plain
+ * `FetchHandler`, so `mountEdge` keeps passing a handler through unchanged
+ * and nothing about that contract changes.
+ */
+export function createEdgeDispatch(init: EdgeDispatchInit): FetchHandler {
+  const { dispatch, key } = init;
+
+  return async function edgeDispatch(req: Request): Promise<Response> {
+    // THE EDGE IS A LOCAL INGRESS, ALWAYS. Strip any proven-peer header the
+    // caller supplied: a page builds the requests that enter its own edge, so
+    // a header here is a CLAIM, never a fact, and `withAccess` downstream
+    // cannot tell the two apart.
+    //
+    // This used to return early when a binding was present, on the reading
+    // "it arrived from the network, not ours to touch". That was safe while
+    // the binding lived in a WeakMap no page could write; with a header it
+    // let a page name itself any peer AND skip the token attachment. The
+    // branch is removed rather than repaired, because a network request never
+    // reaches here anyway -- `serveTransport` dispatches to `peer.dispatch`
+    // directly. See `tests/ingress-forgery.test.ts`.
+    stripPeerBinding(req);
+
+    const url = new URL(req.url);
+    url.pathname = stripEdgePrefix(url.pathname, key);
+    // `new Request(url, req)` reads `req.body` off the init object -- and
+    // FIREFOX HAS NO `Request.prototype.body` (checked against 155), so that
+    // read is `undefined` there and the outbound request loses its body
+    // entirely, silently. Rebuilt explicitly through `bodyOf`, the one copy
+    // of this logic, exactly as `gateway.ts` and the ghost's `pin.ts` already
+    // do for the same reason.
+    const body = await bodyOf(req);
+    const outbound = new Request(url, {
+      method: req.method,
+      headers: req.headers,
+      body,
+      ...(body instanceof ReadableStream ? { duplex: "half" as const } : {}),
+      signal: req.signal,
+    });
+    // NEVER OVERWRITE A CALLER'S OWN MEMBERSHIP TOKEN. A page that set one
+    // deliberately -- calling a peer with a token it was handed out of band,
+    // or testing what a provider does with a bad one -- meant it, and
+    // silently replacing it would make that call untestable and its failure
+    // inexplicable.
+    //
+    // `Authorization` is not looked at at all. It is the page's header for
+    // the application it is calling (LiteLLM's dashboard puts its own key
+    // there); when the token lived in it too, a page that set it got no mesh
+    // token and the provider refused the application key `malformed-token`.
+    if (!outbound.headers.has(MESH_TOKEN_HEADER)) {
+      setMeshToken(outbound.headers, init.token());
+    }
+
+    // Job 4. Before the call, not after a failure: a retry-on-failure shape
+    // would turn every genuinely-unreachable peer into two attempts and a
+    // doubled wait, and it would still be wrong for the case that matters
+    // (the first call to a peer this page has never dialed, which is most
+    // of them).
+    const target = targetPeerId(url.pathname);
+    if (init.ensureRoute != null && target != null) {
+      // Swallowed deliberately -- see job 4's second paragraph.
+      await init.ensureRoute(target).catch((err: unknown) => {
+        console.warn(`edge: could not establish a route to ${target}:`, err);
+      });
+    }
+
+    try {
+      return await dispatch(outbound);
+    } catch (err) {
+      // `instanceof` ONLY, and rethrow everything else. A genuine bug in a
+      // handler must still surface as `SwHttpDispatcher`'s 500 rather than
+      // be dressed up as a network condition the page will politely offer
+      // to retry -- the failure mode this mapping exists to prevent, turned
+      // inside out.
+      if (!(err instanceof PeerCallError)) throw err;
+      const body: PeerErrorBody = { error: err.message, kind: err.kind, peerId: err.peerId };
+      return json(body, PEER_ERROR_STATUS[err.kind]);
+    }
+  };
+}