@statewalker/httpeers-libp2p 0.1.3

package/dist/hop-reserve.js

@@ -0,0 +1,269 @@
+/**
+ * Asking the RELAY whether this node is still reserved -- and renewing the
+ * reservation in the same breath.
+ *
+ * THE QUESTION THIS MODULE EXISTS TO ANSWER. `node.getMultiaddrs()` reports
+ * what the node's own transport reservation store believes, and in the
+ * 2026-09-19 incident that belief was wrong for hours: the relay held no
+ * reservation, the websocket was still up, every member got
+ * `NO_RESERVATION`, and the hub saw nothing to repair. The only authority on
+ * "is there a reservation" is the relay, so this asks it, over the wire.
+ *
+ * WHY NOT LIBP2P'S OWN CALL. `@libp2p/circuit-relay-v2`'s transport keeps a
+ * `ReservationStore` whose `addRelay(peer, type)` is the renewal entry point,
+ * and it is unusable as a probe for three separate reasons:
+ *
+ *   1. It SHORT-CIRCUITS. If it still holds an entry, the connection is open
+ *      and the recorded expiry is more than ten minutes away, it returns the
+ *      cached entry without sending a byte -- so a proactive call answers from
+ *      the very belief we are trying to check.
+ *   2. It is NOT REACHABLE. The store is a private component of the transport;
+ *      nothing on `Libp2p` exposes it.
+ *   3. Its failure paths are SURPRISING. A dial or protocol failure puts the
+ *      relay in a "previously invalid" cuckoo filter (`relayFilter`) so later
+ *      attempts are refused locally, and a discovered reservation can be
+ *      refused with `HadEnoughRelaysError` when no pending slot is free.
+ *
+ * So we speak HOP ourselves. A `RESERVE` request on the relay's own protocol
+ * is two bytes, and the answer is the relay's, not ours.
+ *
+ * IT REUSES THE SLOT, IT DOES NOT LEAK A SECOND ONE. The relay's reservation
+ * store is keyed by peer id: `reserve()` finds the existing entry, resets its
+ * expiry signal in place and returns OK (see `server/reservation-store.js` in
+ * the installed 4.2.11). A peer cannot hold two reservations on one relay, so
+ * "renew" and "re-reserve" are the same request -- which is also why this one
+ * call both DETECTS a loss and REPAIRS it.
+ *
+ * IT DOES NOT DISTURB LIVE CIRCUITS. It opens one short-lived stream on a
+ * connection that already exists; already-established circuits are separate
+ * connections and are untouched, and the relay's refresh path does not close
+ * anything.
+ *
+ * THE CODEC IS HAND-WRITTEN, four fields wide, because it has to be:
+ * `@libp2p/circuit-relay-v2` publishes only `.` in its `exports` map, so its
+ * generated `pb/index.js` cannot be imported, and vendoring protons to
+ * regenerate a message we send ONE variant of would be more code than this.
+ * The wire format is pinned by `tests/hop-reserve.test.ts` against bytes taken
+ * from that generated encoder, and end to end by `tests/reservation-renewal.test.ts`
+ * against a real relay -- which is the check that actually matters, since a
+ * codec that agrees only with its own tests proves nothing.
+ */
+import { RELAY_V2_HOP_CODEC } from "@libp2p/circuit-relay-v2";
+import { peerIdFromString } from "@libp2p/peer-id";
+import { pbStream } from "@libp2p/utils";
+/** circuit-relay v2 `Status`, by number. The relay answers one of these. */
+export const HOP_STATUS_NAMES = {
+    0: "UNUSED",
+    100: "OK",
+    200: "RESERVATION_REFUSED",
+    201: "RESOURCE_LIMIT_EXCEEDED",
+    202: "PERMISSION_DENIED",
+    203: "CONNECTION_FAILED",
+    204: "NO_RESERVATION",
+    400: "MALFORMED_MESSAGE",
+    401: "UNEXPECTED_MESSAGE",
+};
+/** `Status.OK`. */
+export const HOP_STATUS_OK = 100;
+/**
+ * `HopMessage{ type: RESERVE }` on the wire: field 1, varint, value 0.
+ *
+ * protobuf3 would normally omit a zero-valued field; protons generates
+ * `if (obj.type != null) { w.uint32(8); ... }` for this `optional` field, so
+ * the tag IS written and a relay that requires it (go-libp2p does) sees it.
+ * Constant, because every request this module sends is this one.
+ */
+const RESERVE_REQUEST = Uint8Array.from([0x08, 0x00]);
+/** How long one RESERVE round trip may take, matching libp2p's own `DEFAULT_RESERVATION_COMPLETION_TIMEOUT`. */
+export const HOP_RESERVE_TIMEOUT_MS = 5_000;
+/** The relay answered, and the answer was not OK. `status` is its own `Status` number. */
+export class RelayReservationRefusedError extends Error {
+    relayPeerId;
+    status;
+    constructor(relayPeerId, status) {
+        super(`hop: the relay (${relayPeerId}) refused a reservation with ` +
+            `${HOP_STATUS_NAMES[status] ?? `status ${status}`}`);
+        this.relayPeerId = relayPeerId;
+        this.status = status;
+        this.name = "RelayReservationRefusedError";
+    }
+}
+/** There is no connection this node could ask the relay over. Not a refusal: nothing was asked. */
+export class RelayNotConnectedError extends Error {
+    relayPeerId;
+    constructor(relayPeerId) {
+        super(`hop: no open, unlimited connection to the relay (${relayPeerId}) to ask for a reservation over`);
+        this.relayPeerId = relayPeerId;
+        this.name = "RelayNotConnectedError";
+    }
+}
+/**
+ * Read the fields of a `HopMessage` this module needs, skipping the rest.
+ *
+ * Deliberately lenient about everything it does not use -- an unknown field,
+ * a voucher, a limit -- because a decoder that throws on a field a future
+ * relay adds would turn a healthy relay into a lost reservation.
+ */
+export function decodeHopAnswer(data) {
+    const bytes = data instanceof Uint8Array ? data : data.subarray();
+    const answer = {};
+    const reader = new Reader(bytes);
+    while (reader.hasMore()) {
+        const tag = reader.varint();
+        const field = tag >>> 3;
+        const wire = tag & 7;
+        if (field === 1 && wire === 0)
+            answer.type = reader.varint();
+        else if (field === 5 && wire === 0)
+            answer.status = reader.varint();
+        else if (field === 3 && wire === 2) {
+            const reservation = new Reader(reader.bytes());
+            while (reservation.hasMore()) {
+                const innerTag = reservation.varint();
+                if (innerTag >>> 3 === 1 && (innerTag & 7) === 0)
+                    answer.expire = reservation.varint();
+                else
+                    reservation.skip(innerTag & 7);
+            }
+        }
+        else
+            reader.skip(wire);
+    }
+    return answer;
+}
+/**
+ * Request (or renew) this node's reservation on `relayPeerId`, and return what
+ * the relay granted. Throws `RelayReservationRefusedError` on any non-OK
+ * status, `RelayNotConnectedError` when there is nothing to ask over, and
+ * whatever the stream threw otherwise. Every one of those means "not reserved
+ * as far as the relay is concerned", which is the only judgement the caller
+ * needs.
+ */
+export async function requestRelayReservation(node, relayPeerId, options = {}) {
+    const connection = openConnectionTo(node, relayPeerId);
+    if (connection == null)
+        throw new RelayNotConnectedError(relayPeerId);
+    const signal = options.signal ?? AbortSignal.timeout(HOP_RESERVE_TIMEOUT_MS);
+    const stream = await connection.newStream(RELAY_V2_HOP_CODEC, { signal });
+    let answer;
+    try {
+        const hop = pbStream(framed(stream)).pb({
+            encode: () => RESERVE_REQUEST,
+            decode: decodeHopAnswer,
+        });
+        await hop.write({}, { signal });
+        answer = await hop.read({ signal });
+    }
+    catch (error) {
+        stream.abort(error);
+        throw error;
+    }
+    // Closing the write end is enough and is not awaited past its own timeout:
+    // the answer is already in hand, and a relay that is slow to acknowledge the
+    // close must not turn a granted reservation into a reported loss.
+    await stream.close({ signal }).catch(() => stream.abort(new Error("hop: close failed")));
+    if (answer.status !== HOP_STATUS_OK) {
+        throw new RelayReservationRefusedError(relayPeerId, answer.status ?? 0);
+    }
+    const expiresAt = answer.expire != null ? answer.expire * 1_000 : null;
+    return { expiresAt, ttlMs: expiresAt != null ? expiresAt - Date.now() : null };
+}
+/**
+ * A ONE-VERSION TYPE GAP, NOT A RUNTIME ONE.
+ *
+ * This workspace pins `@libp2p/interface` at 3.2.5 everywhere, and
+ * `@libp2p/utils` requires `^3.3.0` — whose `MessageStream` grew a
+ * `readableEnded` property. `pbStream` therefore refuses a 3.2.5 `Stream` by
+ * type while accepting it perfectly at runtime: the property is implemented by
+ * `AbstractMessageStream`, which every real libp2p stream extends, and
+ * `stream-utils.js` never reads it in the first place (checked in the
+ * installed 7.4.1). The narrow cast is the honest statement of that; widening
+ * the pin across seven packages to satisfy one call site would be a much
+ * larger change for the same behaviour.
+ */
+function framed(stream) {
+    return stream;
+}
+/**
+ * A connection to the relay a reservation may be requested over: open, and not
+ * itself relayed.
+ *
+ * NOT RELAYED, because a relay refuses to reserve over a circuit
+ * (libp2p calls it `DoubleRelayError` on its own side), and a limited
+ * connection would in any case be spent on the attempt. `limits != null` is
+ * how libp2p marks one.
+ */
+function openConnectionTo(node, relayPeerId) {
+    let peerId;
+    try {
+        peerId = peerIdFromString(relayPeerId);
+    }
+    catch {
+        return undefined;
+    }
+    return node
+        .getConnections(peerId)
+        .find((connection) => connection.status === "open" && connection.limits == null);
+}
+/** A protobuf reader for the handful of field types `HopMessage` uses. */
+class Reader {
+    buf;
+    pos = 0;
+    constructor(buf) {
+        this.buf = buf;
+    }
+    hasMore() {
+        return this.pos < this.buf.length;
+    }
+    /**
+     * An unsigned varint, as a `number`.
+     *
+     * Assembled with multiplication rather than `<<`, because `<<` is a 32-bit
+     * operation in JavaScript and `Reservation.expire` is a uint64 of Unix
+     * seconds -- a shift would wrap it into a negative number and turn a valid
+     * expiry into nonsense. Ten bytes is the maximum a uint64 can occupy.
+     */
+    varint() {
+        let value = 0;
+        let shift = 1;
+        for (let i = 0; i < 10; i++) {
+            if (!this.hasMore())
+                throw new Error("hop: truncated varint");
+            const byte = this.buf[this.pos++];
+            value += (byte & 0x7f) * shift;
+            if ((byte & 0x80) === 0)
+                return value;
+            shift *= 128;
+        }
+        throw new Error("hop: varint longer than 10 bytes");
+    }
+    /** A length-delimited field's payload. */
+    bytes() {
+        const length = this.varint();
+        const end = this.pos + length;
+        if (end > this.buf.length)
+            throw new Error("hop: truncated length-delimited field");
+        const slice = this.buf.subarray(this.pos, end);
+        this.pos = end;
+        return slice;
+    }
+    /** Step over a field of the given wire type. */
+    skip(wire) {
+        switch (wire) {
+            case 0:
+                this.varint();
+                return;
+            case 1:
+                this.pos += 8;
+                return;
+            case 2:
+                this.bytes();
+                return;
+            case 5:
+                this.pos += 4;
+                return;
+            default:
+                throw new Error(`hop: unsupported protobuf wire type ${wire}`);
+        }
+    }
+}

package/dist/hub-link.d.ts

@@ -0,0 +1,131 @@
+/**
+ * A member's link to its hub: reach it, reserve on it, and address other
+ * members through it. See `./hub-relay.ts` for the hub's side and why.
+ *
+ * TRANSPORT-NEUTRAL, like `./reservation.ts`: nothing here is browser-only,
+ * so the same code runs in a page and under the Node tests.
+ */
+import type { Connection, Libp2p } from "@libp2p/interface";
+import { type RelaySupervisor } from "./reservation.js";
+/**
+ * The address a member dials another member at: through their hub, with a
+ * WebRTC upgrade. The `/webrtc` step is what turns the hub's circuit into a
+ * signalling channel -- dialled without it, the result is a limited
+ * connection through the hub, which carries nothing.
+ *
+ * COMPOSED, NEVER TAKEN FROM A PEER'S OWN ADDRESSES. A reservation on the
+ * hub makes libp2p report a double-circuit address
+ * (`<relay>/p2p-circuit/webrtc/p2p/<hub>/p2p-circuit/p2p/<member>`) that
+ * nothing can dial. This works because the circuit transport reuses the
+ * connection it already holds to the hub.
+ */
+export declare function hubRoute(hubPeerId: string, peerId: string): string;
+/**
+ * Reach the hub over WebRTC through the public relay, and keep ONLY the
+ * WebRTC connection.
+ *
+ * WHY THE SIGNALLING CIRCUIT IS CLOSED. Reaching the hub leaves two
+ * connections to it: the limited circuit through the public relay that
+ * carried the SDP exchange, and the WebRTC one. The circuit transport relays
+ * through `getConnections(relay)[0]` -- the FIRST connection to the relay,
+ * limited or not -- so while the limited one is open, every dial THROUGH the
+ * hub fails with `LimitedConnectionError`. Found by the `proto/hub-relay`
+ * prototype; the "connects two members directly" test fails without it.
+ */
+export declare function reachHub(node: Libp2p, relayAddr: string, hubPeerId: string): Promise<void>;
+/**
+ * Reach the hub through the public relay WITHOUT the WebRTC upgrade, and KEEP
+ * the circuit: the fallback for when `reachHub` cannot work (a hub in Docker on
+ * a bridge network has nothing a WebRTC dial can reach).
+ *
+ * The result is a LIMITED connection, and nothing crosses it unless both ends
+ * opt in: the hub serves with `serveOnLimitedConnection: true`, and the member
+ * calls with `callOnLimitedConnection` allowing the hub (`servePeer`,
+ * `createRemote`), which then opens its streams on this connection rather than
+ * dialling again.
+ *
+ * RETURNED AS LIBP2P RETURNS IT, and not always limited: if an unlimited
+ * connection to the hub already exists (a WebRTC upgrade that did come up),
+ * `dial` hands that back instead of opening a circuit. Check `limits` if it
+ * matters; the intended caller only gets here after `reachHub` failed, or
+ * after it succeeded but the hub refused a reservation -- and then hangs up
+ * the WebRTC connection first (`startMember`).
+ *
+ * NOT CLOSED, unlike `reachHub`'s circuit, because it is the data path. Two
+ * consequences for the caller: `reserveOnHub` has nothing to reserve over, so
+ * other members cannot reach this one; and `leaveRelay` would hang up the
+ * circuit itself.
+ */
+export declare function reachHubRelayed(node: Libp2p, relayAddr: string, hubPeerId: string): Promise<Connection>;
+/**
+ * Why a hub did not grant a reservation, as far as libp2p lets us tell.
+ *
+ *   - `"store-full"` -- `RESERVATION_REFUSED`: the hub's relay already holds
+ *     as many reservations as it grants (libp2p's `maxReservations`). A
+ *     capacity condition on the hub; nothing about this peer.
+ *   - `"resource-limit"` -- `RESOURCE_LIMIT_EXCEEDED`: the same kind of thing,
+ *     from a relay that meters resources rather than counting reservations.
+ *   - `"not-a-member"` -- `PERMISSION_DENIED`: the hub's `membershipGater`
+ *     does not count this peer as a member. (libp2p also answers it to a
+ *     reservation asked for over a relayed connection, which `reserveOnHub`
+ *     never does: it runs over `reachHub`'s WebRTC connection.)
+ *   - `"no-relay"` -- the hub does not speak the relay protocol at all
+ *     (`UnsupportedProtocolError`): a hub deployed without `hubRelayService`.
+ *   - `"no-answer"` -- no status came back: a timeout, a link that dropped
+ *     mid-request. Nothing was refused; nothing was granted either.
+ *   - `"other"` -- any other status, named verbatim in the message.
+ */
+export type HubReservationRefusal = "store-full" | "resource-limit" | "not-a-member" | "no-relay" | "no-answer" | "other";
+/** `reserveOnHub`'s failure: which refusal, the relay's own status when it sent one, and libp2p's error as `cause`. */
+export declare class HubReservationError extends Error {
+    readonly hubPeerId: string;
+    /** The circuit-relay v2 status the hub answered (`"RESERVATION_REFUSED"`, ...), or `null` when it answered none. */
+    readonly status: string | null;
+    readonly refusal: HubReservationRefusal;
+    constructor(hubPeerId: string, 
+    /** The circuit-relay v2 status the hub answered (`"RESERVATION_REFUSED"`, ...), or `null` when it answered none. */
+    status: string | null, refusal: HubReservationRefusal, options: {
+        cause: unknown;
+    });
+}
+/**
+ * Reserve on the hub, over the WebRTC connection `reachHub` left open.
+ * Returns the reserved address. Only a member is granted one -- call this
+ * after the hub has accepted this peer, not before.
+ *
+ * A REFUSAL IS A `HubReservationError` that names the relay's own status --
+ * see `HubReservationRefusal`. libp2p reports every refusal alike, as "Some
+ * configured addresses failed to be listened on"; a full store and a
+ * non-member used to read the same, and in production a full store was
+ * diagnosed as a membership problem.
+ *
+ * A CONFIGURED RELAY, NOT A DISCOVERED ONE: libp2p will not restore it on
+ * its own if the link to the hub drops, which is `superviseHubReservation`'s
+ * job, below. Each call adds a listener; after a lost link -- or a refused
+ * reservation -- the old one sits empty. That is one small object per
+ * attempt, accepted rather than reaching into libp2p's internals to reuse it.
+ */
+export declare function reserveOnHub(node: Libp2p, hubPeerId: string): Promise<string>;
+/**
+ * Close this member's connection to the public relay, once its hub link is
+ * up. A member holds no reservation there any more, and other members reach
+ * it through the hub, so the socket would only spend the relay's capacity.
+ * It is reopened on demand: `reachHub` dials through the relay whenever the
+ * hub has to be reached again.
+ */
+export declare function leaveRelay(node: Libp2p, relayAddr: string): Promise<void>;
+export interface SuperviseHubReservationInit {
+    node: Libp2p;
+    /** The public relay the hub is reached through -- `reachHub`'s. */
+    relayAddr: string;
+    hubPeerId: string;
+    minRetryDelayMs?: number;
+    maxRetryDelayMs?: number;
+}
+/**
+ * Keep this member's reservation on its hub: whenever it is lost, reach the
+ * hub again and re-reserve, with `superviseRelay`'s backoff and `poke()`.
+ * Call once the first `reserveOnHub` has succeeded.
+ */
+export declare function superviseHubReservation(init: SuperviseHubReservationInit): RelaySupervisor;
+//# sourceMappingURL=hub-link.d.ts.map

package/dist/hub-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-link.d.ts","sourceRoot":"","sources":["../src/hub-link.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAI5D,OAAO,EAAE,KAAK,eAAe,EAAkB,MAAM,kBAAkB,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhG;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAErB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,qBAAqB,GAC7B,YAAY,GACZ,gBAAgB,GAChB,cAAc,GACd,UAAU,GACV,WAAW,GACX,OAAO,CAAC;AAEZ,uHAAuH;AACvH,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,oHAAoH;IACpH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAC9B,QAAQ,CAAC,OAAO,EAAE,qBAAqB;IAJzC,YACW,SAAS,EAAE,MAAM;IAC1B,oHAAoH;IAC3G,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,qBAAqB,EACvC,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,EAI5B;CACF;AA2ED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAenF;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG/E;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,2BAA2B,GAAG,eAAe,CAY1F"}

package/dist/hub-link.js

@@ -0,0 +1,217 @@
+/**
+ * A member's link to its hub: reach it, reserve on it, and address other
+ * members through it. See `./hub-relay.ts` for the hub's side and why.
+ *
+ * TRANSPORT-NEUTRAL, like `./reservation.ts`: nothing here is browser-only,
+ * so the same code runs in a page and under the Node tests.
+ */
+import { peerIdFromString } from "@libp2p/peer-id";
+import { multiaddr } from "@multiformats/multiaddr";
+import { lastPeerIdOf } from "./multiaddr-parts.js";
+import { superviseRelay } from "./reservation.js";
+/**
+ * The address a member dials another member at: through their hub, with a
+ * WebRTC upgrade. The `/webrtc` step is what turns the hub's circuit into a
+ * signalling channel -- dialled without it, the result is a limited
+ * connection through the hub, which carries nothing.
+ *
+ * COMPOSED, NEVER TAKEN FROM A PEER'S OWN ADDRESSES. A reservation on the
+ * hub makes libp2p report a double-circuit address
+ * (`<relay>/p2p-circuit/webrtc/p2p/<hub>/p2p-circuit/p2p/<member>`) that
+ * nothing can dial. This works because the circuit transport reuses the
+ * connection it already holds to the hub.
+ */
+export function hubRoute(hubPeerId, peerId) {
+    return `/p2p/${hubPeerId}/p2p-circuit/webrtc/p2p/${peerId}`;
+}
+/**
+ * Reach the hub over WebRTC through the public relay, and keep ONLY the
+ * WebRTC connection.
+ *
+ * WHY THE SIGNALLING CIRCUIT IS CLOSED. Reaching the hub leaves two
+ * connections to it: the limited circuit through the public relay that
+ * carried the SDP exchange, and the WebRTC one. The circuit transport relays
+ * through `getConnections(relay)[0]` -- the FIRST connection to the relay,
+ * limited or not -- so while the limited one is open, every dial THROUGH the
+ * hub fails with `LimitedConnectionError`. Found by the `proto/hub-relay`
+ * prototype; the "connects two members directly" test fails without it.
+ */
+export async function reachHub(node, relayAddr, hubPeerId) {
+    await node.dial(multiaddr(`${relayAddr}/p2p-circuit/webrtc/p2p/${hubPeerId}`));
+    const limited = node.getConnections(peerIdFromString(hubPeerId)).filter((c) => c.limits != null);
+    await Promise.all(limited.map((c) => c.close()));
+}
+/**
+ * Reach the hub through the public relay WITHOUT the WebRTC upgrade, and KEEP
+ * the circuit: the fallback for when `reachHub` cannot work (a hub in Docker on
+ * a bridge network has nothing a WebRTC dial can reach).
+ *
+ * The result is a LIMITED connection, and nothing crosses it unless both ends
+ * opt in: the hub serves with `serveOnLimitedConnection: true`, and the member
+ * calls with `callOnLimitedConnection` allowing the hub (`servePeer`,
+ * `createRemote`), which then opens its streams on this connection rather than
+ * dialling again.
+ *
+ * RETURNED AS LIBP2P RETURNS IT, and not always limited: if an unlimited
+ * connection to the hub already exists (a WebRTC upgrade that did come up),
+ * `dial` hands that back instead of opening a circuit. Check `limits` if it
+ * matters; the intended caller only gets here after `reachHub` failed, or
+ * after it succeeded but the hub refused a reservation -- and then hangs up
+ * the WebRTC connection first (`startMember`).
+ *
+ * NOT CLOSED, unlike `reachHub`'s circuit, because it is the data path. Two
+ * consequences for the caller: `reserveOnHub` has nothing to reserve over, so
+ * other members cannot reach this one; and `leaveRelay` would hang up the
+ * circuit itself.
+ */
+export async function reachHubRelayed(node, relayAddr, hubPeerId) {
+    return node.dial(multiaddr(`${relayAddr}/p2p-circuit/p2p/${hubPeerId}`));
+}
+/** `reserveOnHub`'s failure: which refusal, the relay's own status when it sent one, and libp2p's error as `cause`. */
+export class HubReservationError extends Error {
+    hubPeerId;
+    status;
+    refusal;
+    constructor(hubPeerId, 
+    /** The circuit-relay v2 status the hub answered (`"RESERVATION_REFUSED"`, ...), or `null` when it answered none. */
+    status, refusal, options) {
+        super(describeRefusal(hubPeerId, status, refusal, options.cause), options);
+        this.hubPeerId = hubPeerId;
+        this.status = status;
+        this.refusal = refusal;
+        this.name = "HubReservationError";
+    }
+}
+/**
+ * Read the refusal out of libp2p's error.
+ *
+ * FROM THE TEXT, BECAUSE THAT IS ALL THERE IS. The transport manager wraps
+ * every failed listen in one `UnsupportedListenAddressesError` whose message
+ * embeds the inner error's stack -- `reservation failed with status <STATUS>`
+ * from the reservation store, or `UnsupportedProtocolError: ...` from protocol
+ * negotiation -- and keeps no reference to the inner error itself. The
+ * patterns are pinned against a real hub by the conformance suite's
+ * `member-reservation-fallback.test.ts`.
+ */
+function classify(err) {
+    const text = err instanceof Error ? `${err.name}: ${err.message}\n${err.stack ?? ""}` : String(err);
+    const status = /reservation failed with status (\w+)/.exec(text)?.[1] ?? null;
+    switch (status) {
+        case "RESERVATION_REFUSED":
+            return { status, refusal: "store-full" };
+        case "RESOURCE_LIMIT_EXCEEDED":
+            return { status, refusal: "resource-limit" };
+        case "PERMISSION_DENIED":
+            return { status, refusal: "not-a-member" };
+        case null:
+            return {
+                status,
+                refusal: /UnsupportedProtocolError|could not negotiate/.test(text)
+                    ? "no-relay"
+                    : "no-answer",
+            };
+        default:
+            return { status, refusal: "other" };
+    }
+}
+function describeRefusal(hubPeerId, status, refusal, cause) {
+    const hub = `hub-link: the hub (${hubPeerId})`;
+    switch (refusal) {
+        case "store-full":
+            return (`${hub} refused a reservation with RESERVATION_REFUSED: the hub's reservation store is ` +
+                "full (it grants a fixed number, each held until it expires). Nothing is wrong with this " +
+                "peer; the hub has no slot for it.");
+        case "resource-limit":
+            return `${hub} refused a reservation with RESOURCE_LIMIT_EXCEEDED: the hub's relay is at a resource limit.`;
+        case "not-a-member":
+            return (`${hub} refused a reservation with PERMISSION_DENIED: this peer is not a member as far ` +
+                "as the hub is concerned (a hub grants reservations to its members only).");
+        case "no-relay":
+            return `${hub} does not relay at all -- it has no circuit-relay service (UnsupportedProtocolError).`;
+        case "no-answer":
+            return `${hub} gave no answer to a reservation request. Cause: ${firstLine(cause)}`;
+        case "other":
+            return `${hub} refused a reservation with ${status}.`;
+    }
+}
+/** The inner error libp2p quotes, or the error itself -- without the stack. */
+function firstLine(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    const lines = text.split("\n").map((line) => line.trim());
+    // libp2p's wrapper: a header line, then `<addr>: <inner error>` per address.
+    const inner = lines.find((line) => line.startsWith("/") && line.includes(": "));
+    return inner != null ? inner.slice(inner.indexOf(": ") + 2) : (lines[0] ?? "");
+}
+/**
+ * Reserve on the hub, over the WebRTC connection `reachHub` left open.
+ * Returns the reserved address. Only a member is granted one -- call this
+ * after the hub has accepted this peer, not before.
+ *
+ * A REFUSAL IS A `HubReservationError` that names the relay's own status --
+ * see `HubReservationRefusal`. libp2p reports every refusal alike, as "Some
+ * configured addresses failed to be listened on"; a full store and a
+ * non-member used to read the same, and in production a full store was
+ * diagnosed as a membership problem.
+ *
+ * A CONFIGURED RELAY, NOT A DISCOVERED ONE: libp2p will not restore it on
+ * its own if the link to the hub drops, which is `superviseHubReservation`'s
+ * job, below. Each call adds a listener; after a lost link -- or a refused
+ * reservation -- the old one sits empty. That is one small object per
+ * attempt, accepted rather than reaching into libp2p's internals to reuse it.
+ */
+export async function reserveOnHub(node, hubPeerId) {
+    try {
+        await transportManagerOf(node).listen([multiaddr(`/p2p/${hubPeerId}/p2p-circuit`)]);
+    }
+    catch (err) {
+        const { status, refusal } = classify(err);
+        throw new HubReservationError(hubPeerId, status, refusal, { cause: err });
+    }
+    const reserved = node
+        .getMultiaddrs()
+        .map((addr) => addr.toString())
+        .find((addr) => addr.includes(`/p2p/${hubPeerId}/p2p-circuit`));
+    if (reserved == null) {
+        throw new Error(`hub-link: listening on the hub (${hubPeerId}) produced no reserved address`);
+    }
+    return reserved;
+}
+/**
+ * Close this member's connection to the public relay, once its hub link is
+ * up. A member holds no reservation there any more, and other members reach
+ * it through the hub, so the socket would only spend the relay's capacity.
+ * It is reopened on demand: `reachHub` dials through the relay whenever the
+ * hub has to be reached again.
+ */
+export async function leaveRelay(node, relayAddr) {
+    const relayPeerId = lastPeerIdOf(multiaddr(relayAddr));
+    if (relayPeerId != null)
+        await node.hangUp(peerIdFromString(relayPeerId));
+}
+/**
+ * Keep this member's reservation on its hub: whenever it is lost, reach the
+ * hub again and re-reserve, with `superviseRelay`'s backoff and `poke()`.
+ * Call once the first `reserveOnHub` has succeeded.
+ */
+export function superviseHubReservation(init) {
+    const { node, relayAddr, hubPeerId } = init;
+    return superviseRelay({
+        node,
+        relayAddr: `/p2p/${hubPeerId}`,
+        minRetryDelayMs: init.minRetryDelayMs,
+        maxRetryDelayMs: init.maxRetryDelayMs,
+        restore: async () => {
+            await reachHub(node, relayAddr, hubPeerId);
+            await reserveOnHub(node, hubPeerId);
+        },
+    });
+}
+/**
+ * The node's transport manager -- the only way to add a listen address after
+ * start. `components` is a public field of the libp2p 3.x node class but not
+ * part of the `Libp2p` interface, hence the narrow cast; pinned by
+ * `tests/e2e/hub-relay.test.ts`, which fails if a libp2p upgrade moves it.
+ */
+function transportManagerOf(node) {
+    return node.components.transportManager;
+}