@statewalker/httpeers-libp2p 0.1.3

package/dist/reservation.js

@@ -0,0 +1,396 @@
+/**
+ * Dialing the relay, and waiting for the reservation it grants afterwards.
+ *
+ * TRANSPORT-NEUTRAL ON PURPOSE, AND THAT IS WHY IT LIVES HERE. Both halves
+ * of this module touch nothing but `Libp2p.dial` and `Libp2p.getMultiaddrs`,
+ * so they are identical for a browser node (`browser/node-profile.ts`), a
+ * Node hub (`hub/node-profile.ts`) and a test peer (`tests/e2e/harness.ts`).
+ * They used to live in `browser/node-profile.ts`, whose top-level imports
+ * include `@libp2p/webrtc` -- which is why `tests/e2e/harness.ts` grew a
+ * second, hand-copied poll loop rather than import them (Task 14 reported
+ * that duplication as a finding). `@libp2p/webrtc` now loads under Node
+ * (its `node-datachannel` binary is installed, Task 20 Step 1), so the
+ * import would work today; the copy is still gone because ONE poll loop
+ * with one timing contract is the point, not because importing was
+ * impossible.
+ *
+ * READINESS IS POLLED, NOT AWAITED (design note 17 §4). `node.dial(relay)`
+ * resolving means the connection to the relay opened -- it says nothing
+ * about whether the relay has finished granting a reservation. That
+ * reservation lands asynchronously afterwards, so `waitForCircuitReservation`
+ * polls `getMultiaddrs()` until a `p2p-circuit` address actually appears, on
+ * the same schedule (250 ms x 40 attempts = 10 s ceiling) the validated
+ * relay test used (`prototypes/16-.../src/relay.test.ts`). Treating `dial`'s
+ * resolution as "ready" is exactly the race that note documents this project
+ * already got bitten by once.
+ */
+import { multiaddr } from "@multiformats/multiaddr";
+import { requestRelayReservation } from "./hop-reserve.js";
+import { lastPeerIdOf } from "./multiaddr-parts.js";
+import { globalTimers } from "./timers.js";
+/** Dial the relay named by `relayAddr` (`httpeers.json`'s `relayAddrs[0]`). Resolving means the link is up -- NOT that a circuit reservation exists yet; see `waitForCircuitReservation`. */
+export async function dialRelay(node, relayAddr) {
+    await node.dial(multiaddr(relayAddr));
+}
+/** How often `waitForCircuitReservation` re-checks `getMultiaddrs()`. */
+export const RESERVATION_POLL_INTERVAL_MS = 250;
+/** How many times it checks before giving up -- 40 x 250 ms = 10 s, the ceiling the validated relay test (`relay.test.ts`) used. */
+export const RESERVATION_POLL_ATTEMPTS = 40;
+/**
+ * Poll `node.getMultiaddrs()` until a `p2p-circuit` address appears,
+ * returning it as a string. See this module's own "READINESS IS POLLED,
+ * NOT AWAITED" note for why this exists instead of trusting `dialRelay`'s
+ * resolution: the reservation is granted by the relay asynchronously,
+ * after the dial itself has already resolved.
+ */
+export async function waitForCircuitReservation(node, init = {}) {
+    const intervalMs = init.intervalMs ?? RESERVATION_POLL_INTERVAL_MS;
+    const attempts = init.attempts ?? RESERVATION_POLL_ATTEMPTS;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const found = node.getMultiaddrs().find((addr) => addr.toString().includes("p2p-circuit"));
+        if (found != null)
+            return found.toString();
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    throw new Error(`reservation: no p2p-circuit reservation appeared within ${attempts * intervalMs}ms of dialing the relay -- ` +
+        "the relay may be unreachable, or its reservation limits already exhausted.");
+}
+/** How long one restore attempt waits for the reservation after its dial resolved -- 20 x 250 ms = 5 s. */
+const RESTORE_POLL_ATTEMPTS = 20;
+/** The backstop check, for a loss no event reported. */
+const SUPERVISOR_CHECK_INTERVAL_MS = 10_000;
+/** How soon after starting the supervisor first asks the relay. See `scheduleRenewal`. */
+const INITIAL_VERIFY_DELAY_MS = 1_000;
+/**
+ * The floor and ceiling on the renewal cadence, and the cadence used when the
+ * relay has not told us a TTL yet.
+ *
+ * A QUARTER OF THE TTL is the rule (`renewalIntervalMs`). Against the relay
+ * this project runs -- `apps/relay/src/limits.ts`, TTL two hours, restated
+ * there precisely so a library change is visible -- that is thirty minutes,
+ * and it means three consecutive renewals can fail before the reservation
+ * would lapse on its own. A half would leave room for one, which is no margin
+ * at all; an eighth would double the traffic for a margin nobody needs.
+ *
+ * The CEILING is the same thirty minutes, so a relay that one day advertises a
+ * longer TTL does not stretch the cadence with it: the incident was not a
+ * reservation that expired, it was one that vanished, and how fast that is
+ * repaired is bounded by this number, not by the TTL. The FLOOR keeps a relay
+ * with an implausibly short TTL from being asked every few seconds.
+ */
+export const MIN_RENEWAL_INTERVAL_MS = 60_000;
+export const MAX_RENEWAL_INTERVAL_MS = 30 * 60_000;
+export const DEFAULT_RENEWAL_INTERVAL_MS = 20 * 60_000;
+/** The renewal cadence for a reservation the relay says lasts `ttlMs`. See the constants above. */
+export function renewalIntervalMs(ttlMs) {
+    if (ttlMs == null || !(ttlMs > 0))
+        return DEFAULT_RENEWAL_INTERVAL_MS;
+    return Math.min(Math.max(ttlMs / 4, MIN_RENEWAL_INTERVAL_MS), MAX_RENEWAL_INTERVAL_MS);
+}
+/**
+ * The actual wait before the next renewal: `intervalMs` jittered DOWN into its
+ * upper quarter, never up.
+ *
+ * Down, because the interval is already the deadline -- stretching it past a
+ * quarter of the TTL would spend the margin the quarter exists to buy. The
+ * spread is what keeps a fleet of hubs that started together, or came back
+ * together after a relay restart, from asking the relay in the same instant
+ * for ever after.
+ */
+export function renewalDelayMs(intervalMs, random = Math.random) {
+    return intervalMs * 0.75 + intervalMs * 0.25 * random();
+}
+/**
+ * How long a lost reservation may go unrepaired before the hub should call
+ * itself unhealthy.
+ *
+ * TWO MINUTES. A restore normally completes in seconds: the loss is noticed
+ * either at once (the address disappears) or at the next renewal, the restore
+ * dials and waits at most five seconds for the reservation, and the retry
+ * backoff caps at thirty. Two minutes is therefore at least four attempts
+ * including capped retries -- long enough that a relay restart or a dropped
+ * link never shows up as an unhealthy appliance, short enough to be a small
+ * fraction of the two-hour TTL, so a hub that truly cannot get back is
+ * reported long before members would notice on their own.
+ */
+export const RESERVATION_LOSS_GRACE_MS = 120_000;
+/** Is this state healthy -- reserved, or lost for less than `graceMs`? See `RESERVATION_LOSS_GRACE_MS`. */
+export function reservationHealthy(state, graceMs = RESERVATION_LOSS_GRACE_MS, now = Date.now()) {
+    if (state.status === "reserved")
+        return true;
+    if (state.status === "stopped")
+        return false;
+    return state.lostSince != null && now - state.lostSince < graceMs;
+}
+/**
+ * Keep this node's reservation on the relay at `relayAddr`: renew it against
+ * the relay on a schedule, and re-dial whenever it is lost. Call once the
+ * first reservation has landed.
+ */
+export function superviseRelay(init) {
+    const { node, relayAddr } = init;
+    const minDelayMs = init.minRetryDelayMs ?? 1_000;
+    const maxDelayMs = init.maxRetryDelayMs ?? 30_000;
+    const relayPeerId = lastPeerIdOf(multiaddr(relayAddr)) ?? null;
+    const timers = init.timers ?? globalTimers;
+    const now = init.now ?? Date.now;
+    const random = init.random ?? Math.random;
+    const log = init.log ?? defaultRelayLog;
+    const verify = init.verify === false
+        ? undefined
+        : (init.verify ??
+            (relayPeerId != null
+                ? (options) => requestRelayReservation(node, relayPeerId, options)
+                : undefined));
+    const state = {
+        status: "reserved",
+        relayAddr,
+        relayPeerId,
+        verifiedAt: null,
+        expiresAt: null,
+        lostSince: null,
+        consecutiveFailures: 0,
+        renewals: 0,
+        restores: 0,
+        lastError: null,
+    };
+    let retryTimer;
+    let renewalTimer;
+    let restoring = false;
+    let renewing = false;
+    let stopped = false;
+    const snapshot = () => ({ ...state });
+    const report = (event, reason) => {
+        const where = relayPeerId ?? relayAddr;
+        log(`relay: ${event} on ${where}${reason != null ? ` -- ${reason}` : ""}` +
+            ` (failures=${state.consecutiveFailures}, renewals=${state.renewals}, restores=${state.restores})`, { event, state: snapshot() });
+    };
+    /**
+     * The address check, used ONLY to prove a loss. `true` here means nothing:
+     * it is precisely the belief that was wrong during the incident.
+     */
+    const addressGone = () => !node.getMultiaddrs().some((addr) => {
+        const s = addr.toString();
+        return relayPeerId == null
+            ? s.includes("/p2p-circuit")
+            : s.includes(`/p2p/${relayPeerId}/p2p-circuit`);
+    });
+    const markReserved = (grant, event) => {
+        state.status = "reserved";
+        state.verifiedAt = now();
+        state.expiresAt = grant.expiresAt;
+        state.lostSince = null;
+        state.consecutiveFailures = 0;
+        if (event === "renewed")
+            state.renewals++;
+        if (event === "restored")
+            state.restores++;
+        report(event);
+    };
+    const markLost = (reason) => {
+        state.lastError = reason;
+        if (state.status === "lost")
+            return;
+        state.status = "lost";
+        state.lostSince = now();
+        report("lost", reason);
+    };
+    const scheduleRetry = (delayMs) => {
+        timers.clearTimeout(retryTimer);
+        retryTimer = timers.setTimeout(() => {
+            retryTimer = undefined;
+            void restore();
+        }, delayMs);
+    };
+    /**
+     * THE FIRST RENEWAL IS PROMPT, the rest are on the TTL's cadence.
+     *
+     * A supervisor is started the moment a reservation lands, so one request a
+     * second later costs a two-byte round trip and buys two things the caller
+     * cannot get otherwise: the relay's own expiry -- which is what every later
+     * interval is derived from, instead of the blind `DEFAULT_RENEWAL_INTERVAL_MS`
+     * -- and a `verifiedAt` an operator can read straight after a restart rather
+     * than twenty minutes into one.
+     */
+    const scheduleRenewal = (first = false) => {
+        if (stopped || verify == null)
+            return;
+        timers.clearTimeout(renewalTimer);
+        const interval = init.renewalIntervalMs ?? renewalIntervalMs(ttlOf(state, now()));
+        const delayMs = first && init.renewalIntervalMs == null
+            ? INITIAL_VERIFY_DELAY_MS
+            : renewalDelayMs(interval, random);
+        renewalTimer = timers.setTimeout(() => {
+            renewalTimer = undefined;
+            void renew();
+        }, delayMs);
+    };
+    /**
+     * One relay-verified renewal. This is the whole point of the module: the
+     * request renews a reservation that is there and re-creates one that is not,
+     * so the ordinary case never reaches `restore` at all.
+     */
+    async function renew() {
+        if (stopped || verify == null || renewing || restoring) {
+            scheduleRenewal();
+            return;
+        }
+        renewing = true;
+        try {
+            const grant = await verify({});
+            if (stopped)
+                return;
+            markReserved(grant, state.status === "reserved" ? "renewed" : "restored");
+        }
+        catch (error) {
+            if (stopped)
+                return;
+            state.consecutiveFailures++;
+            const reason = messageOf(error);
+            state.lastError = reason;
+            report("renewal-failed", reason);
+            markLost(reason);
+            scheduleRetry(0);
+        }
+        finally {
+            renewing = false;
+            scheduleRenewal();
+        }
+    }
+    /**
+     * Get the reservation back the hard way: re-dial (or the caller's `restore`),
+     * then ASK THE RELAY. A restore that only re-listens has proved nothing --
+     * that is the same local belief that failed before -- so when a `verify` is
+     * available, its answer is what ends the outage.
+     */
+    async function restore() {
+        if (stopped || restoring)
+            return;
+        restoring = true;
+        report("restoring", state.lastError ?? undefined);
+        try {
+            if (init.restore != null) {
+                await init.restore();
+            }
+            else {
+                await dialRelay(node, relayAddr);
+                await waitForCircuitReservation(node, { attempts: RESTORE_POLL_ATTEMPTS });
+            }
+            if (stopped)
+                return;
+            if (verify != null) {
+                markReserved(await verify({}), "restored");
+            }
+            else {
+                if (addressGone())
+                    throw new Error("restore resolved without a reservation");
+                markReserved({ expiresAt: null, ttlMs: null }, "restored");
+            }
+        }
+        catch (error) {
+            if (stopped)
+                return;
+            state.consecutiveFailures++;
+            const reason = messageOf(error);
+            state.lastError = reason;
+            markLost(reason);
+            report("restore-failed", reason);
+            scheduleRetry(retryDelayMs(state.consecutiveFailures - 1, minDelayMs, maxDelayMs, random));
+        }
+        finally {
+            restoring = false;
+        }
+    }
+    /** The fast loss detector: an address that has gone is proof; one that is there is not. */
+    const check = () => {
+        if (stopped || restoring || renewing || retryTimer != null)
+            return;
+        if (!addressGone())
+            return;
+        markLost("the node's own circuit address is gone (the relay connection closed)");
+        scheduleRetry(0);
+    };
+    node.addEventListener("connection:close", check);
+    node.addEventListener("self:peer:update", check);
+    const interval = timers.setInterval(check, init.checkIntervalMs ?? SUPERVISOR_CHECK_INTERVAL_MS);
+    report("reserved");
+    scheduleRenewal(true);
+    return {
+        poke() {
+            if (stopped)
+                return;
+            timers.clearTimeout(retryTimer);
+            retryTimer = undefined;
+            state.consecutiveFailures = 0;
+            if (verify != null)
+                void renew();
+            else
+                check();
+        },
+        state: snapshot,
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            state.status = "stopped";
+            timers.clearTimeout(retryTimer);
+            timers.clearTimeout(renewalTimer);
+            retryTimer = undefined;
+            renewalTimer = undefined;
+            timers.clearInterval(interval);
+            node.removeEventListener("connection:close", check);
+            node.removeEventListener("self:peer:update", check);
+            report("stopped");
+        },
+    };
+}
+/** What is left of the reservation the relay last granted, for the next renewal's cadence. */
+function ttlOf(state, nowMs) {
+    return state.expiresAt != null ? state.expiresAt - nowMs : null;
+}
+function messageOf(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+/** One line per transition on stdout. Replaceable, but never absent — see the module comment. */
+const defaultRelayLog = (message) => {
+    console.log(message);
+};
+/**
+ * The wait before retry number `failures` (0-based): doubling from
+ * `minDelayMs`, capped at `maxDelayMs`, then jittered into its upper half
+ * so a relay restart does not bring every peer back in the same instant.
+ */
+export function retryDelayMs(failures, minDelayMs, maxDelayMs, random = Math.random) {
+    const base = Math.min(maxDelayMs, minDelayMs * 2 ** failures);
+    return base / 2 + (random() * base) / 2;
+}
+/**
+ * Which of a node's addresses a peer should actually be told.
+ *
+ * After reserving, a node carries several multiaddrs at once and they are NOT
+ * interchangeable: its own transport address is not reachable through a relay
+ * at all, the bare circuit relays every byte, and the `/webrtc` circuit uses
+ * the relay for the handshake only and then talks directly. Handing out the
+ * wrong one is a connection that fails for a reason nobody can read from the
+ * error.
+ *
+ * Each assembly in the prototype picked one inline, and differently — the kind
+ * of triplication the extraction exists to end.
+ */
+export function circuitAddrs(node) {
+    const found = {};
+    for (const addr of node.getMultiaddrs()) {
+        const value = addr.toString();
+        // Not a circuit: the node's own transport address. A dialler reaching it
+        // needs no relay, so it does not belong in either field.
+        if (!value.includes("/p2p-circuit"))
+            continue;
+        // Order matters: every webrtc circuit also contains `/p2p-circuit`, so the
+        // narrower test comes first or every address lands in `bare`.
+        if (value.includes("/webrtc"))
+            found.webrtc ??= value;
+        else
+            found.bare ??= value;
+    }
+    return found;
+}

package/dist/serve-peer.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A mount table, served to the mesh.
+ *
+ * THE SEAM THREE ASSEMBLIES COLLAPSE INTO. The prototype builds a peer three
+ * times — the Node hub, the browser hub and the test hub — each wiring a node,
+ * a reservation, identity registration, a router and mounts in its own order,
+ * and the coverage audit found that the one symbol every assembly turns on was
+ * exported nowhere. This is it.
+ *
+ * WHAT IT DOES NOT DO, and the omission is the design. It does not verify a
+ * token, evaluate a policy, or know what a hub is. `access` is a middleware
+ * the caller supplies — `withAccess` from `@statewalker/httpeers-access`, or
+ * nothing at all for a peer that trusts its transport — because this package
+ * must not learn about Biscuit and `httpeers-access` must not learn about
+ * libp2p. They meet at a `FetchHandler`, which is the only contract either
+ * needs.
+ *
+ * IDENTITY IS REGISTERED BEFORE ANYTHING DOWNSTREAM RUNS. `serveTransport`
+ * gives every inbound stream its own `Duplex` closing over that stream's
+ * Noise-proven `remotePeer`, and calls `registerPeer` on the request before
+ * the handler sees it. That ordering is the whole basis of the binding check:
+ * a token's subject is compared against what the TRANSPORT proved, never
+ * against anything the caller said.
+ */
+import type { Libp2p } from "@libp2p/interface";
+import type { FetchHandler, Mounts, PeerIdStr } from "@statewalker/httpeers-core";
+import type { CallOnLimitedConnection } from "./link.js";
+export interface ServePeerInit {
+    node: Libp2p;
+    /**
+     * What this peer serves. A value, or a factory taking the peer's own id —
+     * a hub's endpoints need to know which mesh they are, and the alternative
+     * is for this package to learn what a hub is.
+     */
+    mounts: Mounts | ((self: PeerIdStr) => Mounts);
+    /**
+     * Everything between the transport and the mounts: identity binding and
+     * policy. Omitted, requests reach the mounts with only the transport's
+     * proof — which is a legitimate shape for a peer whose mounts are public,
+     * and a serious mistake for one whose are not.
+     *
+     * Passed through to the router, which applies it to LOCAL handling only.
+     * That distinction is load-bearing and easy to lose: wrapping the whole
+     * router instead would run policy over FORWARDED requests too, and an
+     * outbound call is not this peer's business to authorize.
+     */
+    access?: (next: FetchHandler) => FetchHandler;
+    /**
+     * May this request be forwarded to `target`? **Deny by default**, and the
+     * default is inherited rather than restated here.
+     *
+     * Relaying is a distinct capability, not a side effect of knowing how to
+     * route: without it any peer can make this one dial a third party and pump
+     * a stream on its behalf. The hole is invisible for a while because it
+     * fails CLOSED at the far end — the third party rejects the tokenless
+     * request, so every observable outcome looks right. The damage is the work
+     * done, not the answer given.
+     */
+    allowForward?: (request: Request, target: PeerIdStr) => Promise<boolean>;
+    protocol?: string;
+    /** Forwarded to the transport; see `transport.ts` for what each bounds. */
+    maxInboundStreams?: number;
+    maxOutboundStreams?: number;
+    drainTimeoutMs?: number;
+    /**
+     * Accept streams on limited connections (relay circuits) -- SERVING ONLY. A
+     * HUB sets it, so members that can reach it only through the public relay
+     * are served; a member never does, so the hub's relay limits still bound
+     * member-to-member traffic.
+     */
+    serveOnLimitedConnection?: boolean;
+    /**
+     * Open streams on limited connections to the peers this allows -- CALLING
+     * ONLY, and it covers every outbound path of this peer (`call`, and the
+     * router's forwarding behind `dispatch`). A member in relay mode passes
+     * `(peerId) => peerId === hubPeerId`. See `CallOnLimitedConnection`.
+     */
+    callOnLimitedConnection?: CallOnLimitedConnection;
+}
+export interface Peer {
+    peerId: PeerIdStr;
+    /** Every multiaddr this node is reachable on, right now. */
+    addrs(): string[];
+    /** Inbound, after identity binding and policy. Exposed so an edge can reuse it locally. */
+    dispatch: FetchHandler;
+    /** Call another peer. The request's URL path is what the far side routes on. */
+    call(peerId: PeerIdStr, request: Request): Promise<Response>;
+    stop(): Promise<void>;
+}
+export declare function servePeer(init: ServePeerInit): Promise<Peer>;
+//# sourceMappingURL=serve-peer.d.ts.map

package/dist/serve-peer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-peer.d.ts","sourceRoot":"","sources":["../src/serve-peer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAElF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAGzD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAC;IAC9C;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,uBAAuB,CAAC;CACnD;AAED,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,4DAA4D;IAC5D,KAAK,IAAI,MAAM,EAAE,CAAC;IAClB,2FAA2F;IAC3F,QAAQ,EAAE,YAAY,CAAC;IACvB,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA6ClE"}

package/dist/serve-peer.js

@@ -0,0 +1,68 @@
+/**
+ * A mount table, served to the mesh.
+ *
+ * THE SEAM THREE ASSEMBLIES COLLAPSE INTO. The prototype builds a peer three
+ * times — the Node hub, the browser hub and the test hub — each wiring a node,
+ * a reservation, identity registration, a router and mounts in its own order,
+ * and the coverage audit found that the one symbol every assembly turns on was
+ * exported nowhere. This is it.
+ *
+ * WHAT IT DOES NOT DO, and the omission is the design. It does not verify a
+ * token, evaluate a policy, or know what a hub is. `access` is a middleware
+ * the caller supplies — `withAccess` from `@statewalker/httpeers-access`, or
+ * nothing at all for a peer that trusts its transport — because this package
+ * must not learn about Biscuit and `httpeers-access` must not learn about
+ * libp2p. They meet at a `FetchHandler`, which is the only contract either
+ * needs.
+ *
+ * IDENTITY IS REGISTERED BEFORE ANYTHING DOWNSTREAM RUNS. `serveTransport`
+ * gives every inbound stream its own `Duplex` closing over that stream's
+ * Noise-proven `remotePeer`, and calls `registerPeer` on the request before
+ * the handler sees it. That ordering is the whole basis of the binding check:
+ * a token's subject is compared against what the TRANSPORT proved, never
+ * against anything the caller said.
+ */
+import { createPeerRouter } from "@statewalker/httpeers-core";
+import { createRemote, PROTOCOL, serveTransport } from "./transport.js";
+export async function servePeer(init) {
+    const peerId = init.node.peerId.toString();
+    const protocol = init.protocol ?? PROTOCOL;
+    const mounts = typeof init.mounts === "function" ? init.mounts(peerId) : init.mounts;
+    const remote = createRemote({
+        node: init.node,
+        protocol,
+        maxOutboundStreams: init.maxOutboundStreams,
+        callOnLimitedConnection: init.callOnLimitedConnection,
+    });
+    const dispatch = createPeerRouter({
+        selfPeerId: peerId,
+        mounts,
+        remote,
+        access: init.access,
+        allowForward: init.allowForward,
+    });
+    const stopServing = await serveTransport({
+        node: init.node,
+        dispatch,
+        protocol,
+        maxInboundStreams: init.maxInboundStreams,
+        maxOutboundStreams: init.maxOutboundStreams,
+        drainTimeoutMs: init.drainTimeoutMs,
+        runOnLimitedConnection: init.serveOnLimitedConnection,
+    });
+    let stopped = false;
+    return {
+        peerId,
+        addrs: () => init.node.getMultiaddrs().map((a) => a.toString()),
+        dispatch,
+        call: async (target, request) => remote(target, request),
+        async stop() {
+            // Idempotent: an assembly that tears down twice — a page unloading while
+            // a test also cleans up — must not see the second call throw.
+            if (stopped)
+                return;
+            stopped = true;
+            await stopServing();
+        },
+    };
+}

package/dist/timers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The timer seam: the four calls anything long-lived in this package schedules
+ * with, behind an interface instead of the global functions.
+ *
+ * WHY, AND IT IS NOT TESTABILITY. A browser throttles `setTimeout` and
+ * `setInterval` in a background tab -- to once a minute, and on some engines
+ * far less -- and a hub running in a tab is a hub whose relay reservation is
+ * renewed on the browser's schedule rather than on the relay's. The fix is
+ * `worker-timers`, which schedules from a Web Worker and is not throttled; the
+ * fix is NOT to shorten the interval, which changes nothing about what the
+ * browser does to it. That wiring is deliberately not here yet (the Node hub is
+ * what runs today); this seam is what makes it a one-line change later:
+ *
+ *   import { clearInterval, clearTimeout, setInterval, setTimeout } from "worker-timers";
+ *   const timers: Timers = { setTimeout, clearTimeout, setInterval, clearInterval };
+ *
+ * Tests get the seam for free, and that is the cheaper of the two reasons.
+ *
+ * `TimerHandle` IS `unknown` ON PURPOSE. Node's timers return an object,
+ * browsers return a number, `worker-timers` returns a number of its own that
+ * only its own `clearTimeout` understands. An implementation must therefore
+ * only ever hand its OWN handles back to its OWN clear functions -- which is
+ * exactly what an opaque type states and a `number` alias would quietly
+ * permit callers to violate.
+ */
+/** A handle from one `Timers` implementation, meaningful only to that same one. */
+export type TimerHandle = unknown;
+export interface Timers {
+    setTimeout(handler: () => void, delayMs: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+    setInterval(handler: () => void, delayMs: number): TimerHandle;
+    clearInterval(handle: TimerHandle): void;
+}
+/** The global timers, which is what everything uses unless it is told otherwise. */
+export declare const globalTimers: Timers;
+//# sourceMappingURL=timers.d.ts.map

package/dist/timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../src/timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC;AAElC,MAAM,WAAW,MAAM;IACrB,UAAU,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9D,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACxC,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAAC;IAC/D,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CAC1C;AAED,oFAAoF;AACpF,eAAO,MAAM,YAAY,EAAE,MAS1B,CAAC"}

package/dist/timers.js

@@ -0,0 +1,38 @@
+/**
+ * The timer seam: the four calls anything long-lived in this package schedules
+ * with, behind an interface instead of the global functions.
+ *
+ * WHY, AND IT IS NOT TESTABILITY. A browser throttles `setTimeout` and
+ * `setInterval` in a background tab -- to once a minute, and on some engines
+ * far less -- and a hub running in a tab is a hub whose relay reservation is
+ * renewed on the browser's schedule rather than on the relay's. The fix is
+ * `worker-timers`, which schedules from a Web Worker and is not throttled; the
+ * fix is NOT to shorten the interval, which changes nothing about what the
+ * browser does to it. That wiring is deliberately not here yet (the Node hub is
+ * what runs today); this seam is what makes it a one-line change later:
+ *
+ *   import { clearInterval, clearTimeout, setInterval, setTimeout } from "worker-timers";
+ *   const timers: Timers = { setTimeout, clearTimeout, setInterval, clearInterval };
+ *
+ * Tests get the seam for free, and that is the cheaper of the two reasons.
+ *
+ * `TimerHandle` IS `unknown` ON PURPOSE. Node's timers return an object,
+ * browsers return a number, `worker-timers` returns a number of its own that
+ * only its own `clearTimeout` understands. An implementation must therefore
+ * only ever hand its OWN handles back to its OWN clear functions -- which is
+ * exactly what an opaque type states and a `number` alias would quietly
+ * permit callers to violate.
+ */
+/** The global timers, which is what everything uses unless it is told otherwise. */
+export const globalTimers = {
+    setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+    clearTimeout: (handle) => {
+        if (handle !== undefined)
+            clearTimeout(handle);
+    },
+    setInterval: (handler, delayMs) => setInterval(handler, delayMs),
+    clearInterval: (handle) => {
+        if (handle !== undefined)
+            clearInterval(handle);
+    },
+};