@statewalker/httpeers-member 0.1.4

package/dist/session.js

@@ -0,0 +1,403 @@
+/**
+ * The page session: one persistent identity, resume-or-redeem on start, and
+ * the three operator controls -- join, disconnect, reset identity -- with
+ * no DOM anywhere in it.
+ *
+ * WHY EVERY CONSUMER PAGE SHARES THIS. Two pages differ in exactly one
+ * thing: what they mount and advertise. Everything else -- read the saved
+ * identity, try to resume, say which of the two "cannot resume" situations
+ * this is, offer an invitation field, disconnect without surrendering
+ * membership, reset the key -- is identical between them, down to the
+ * wording, and duplicating it would have been duplicating the wording too.
+ *
+ * NO DOM, AND NOTHING BROWSER-ONLY IMPORTED. This module decides things --
+ * which mesh to try, resume or redeem, what an operator is told -- and
+ * deciding is exactly what is worth testing, so `tests/session.test.ts`
+ * exercises every branch under Node with no browser, no relay and no
+ * ServiceWorker. That is only possible because the platform, the two stores
+ * and the reload are INJECTED rather than defaulted: `browserPlatform`
+ * reaches `@libp2p/webrtc`, whose Node build loads a native module, so a
+ * default here would have made importing this module a browser-only act.
+ * `./browser.ts`'s `createSession` is where those defaults live instead.
+ *
+ * Pages render `SessionState` and call the four methods; they hold no state
+ * of their own.
+ *
+ * THE CONFIG IS RESOLVED HERE, because `startMember` requires one and will
+ * not fetch anything itself (see `StartMemberInit.config`). That moved the
+ * `httpeers.json` read up into this module, which is the only place that
+ * knows which of the three candidates -- a blob's mesh, the remembered one,
+ * the deployment's -- applies to the attempt at hand.
+ *
+ * WHICH MESH IS TRIED, AND THE ONE RULE THAT MUST NOT BEND. When someone
+ * supplies an invitation, the invitation decides: a join blob names its own
+ * mesh, and a BARE invitation id still means "the mesh `httpeers.json`
+ * names", i.e. the Node hub's -- the contract `./join-blob.ts` states and
+ * the reason both deployments keep working. Only a RESUME (nobody supplied
+ * anything) consults `./mesh-memory.ts`, and only because a mesh whose hub
+ * is a browser page cannot be named any other way after the `?join=` query
+ * has gone. See `./mesh-memory.ts`.
+ *
+ * DISCONNECT IS NOT LEAVING. `MemberHandle.stop()` drops presence and
+ * keeps membership, which is what makes the page resumable afterwards with
+ * no new invitation; see that method's own doc comment. This module never
+ * calls anything that surrenders membership, and the one control that
+ * destroys something -- `resetIdentity` -- says what it costs and is named
+ * separately.
+ */
+import { clearIdentity, loadOrCreateIdentity, peerIdOf, readIdentity } from "./identity.js";
+import { readJoinInputFromSearch, readJoinInputFromText } from "./join-blob.js";
+import { parseMeshConfig } from "./mesh-config.js";
+import { MemberJoinError, startMember } from "./start-member.js";
+export function createIdentityStore(init) {
+    return {
+        read: () => readIdentity(init),
+        loadOrCreate: () => loadOrCreateIdentity(init),
+        clear: () => clearIdentity(init),
+    };
+}
+function controlsFor(phase) {
+    switch (phase.kind) {
+        case "live":
+            return { join: false, disconnect: true, reconnect: false, reset: true };
+        case "disconnected":
+            return { join: false, disconnect: false, reconnect: true, reset: true };
+        // Every remaining phase leaves the invitation field open -- including
+        // `failed`. A page that could not reach the relay will not be fixed by
+        // an invitation, but an operator who has just been handed a link to a
+        // DIFFERENT mesh has every reason to try it, and a form that vanished on
+        // the wrong kind of failure would be the page deciding that for them.
+        case "blocked":
+            return { join: false, disconnect: false, reconnect: false, reset: true };
+        case "checking":
+        case "starting":
+            return { join: false, disconnect: false, reconnect: false, reset: false };
+        default:
+            return { join: true, disconnect: false, reconnect: false, reset: true };
+    }
+}
+/** A blob names its own mesh; a bare invitation id means "whichever mesh `httpeers.json` names" -- `./join-blob.ts`. */
+function configOf(input) {
+    return input.kind === "blob"
+        ? { relayAddrs: input.blob.relayAddrs, hubPeerId: input.blob.hubPeerId }
+        : undefined;
+}
+function invitationIdOf(input) {
+    return input.kind === "blob" ? input.blob.invitationId : input.invitationId;
+}
+/**
+ * Where a deployment publishes the mesh it names.
+ *
+ * A SITE-ABSOLUTE PATH, so every page of an origin reads the same file
+ * whatever directory it was served from. It left with `peer-runtime.ts` and
+ * is declared here because this module is now the only thing that reads it.
+ */
+export const DEFAULT_HTTPEERS_CONFIG_URL = "/httpeers.json";
+async function readDeploymentConfigOverHttp() {
+    try {
+        const res = await fetch(DEFAULT_HTTPEERS_CONFIG_URL);
+        if (!res.ok)
+            return null;
+        // PARSED, NOT CAST. A hub-page deployment publishes `relayAddrs` with no
+        // `hubPeerId` -- there is no stable one to publish -- and casting that let
+        // it reach `startMember` as `hubPeerId: undefined`. `null` is the honest
+        // answer and the session already renders it as "paste an invitation".
+        return parseMeshConfig(await res.json());
+    }
+    catch {
+        // A diagnostic that cannot be read is simply not added to the message.
+        return null;
+    }
+}
+/**
+ * The sentence added to a "this hub does not know you" message when the
+ * deployment has visibly moved underneath the page.
+ *
+ * THE CASE THIS EXISTS FOR: `pnpm bootstrap` was re-run, so `httpeers.json`
+ * now names a hub with a different peerId than the one this page last
+ * joined. Everything about the page is fine, the hub it is talking to is
+ * fine, and the membership is simply in a mesh that no longer exists. With
+ * nothing said, that presents as "please paste an invitation" for reasons
+ * an operator cannot see. Exported for its own test.
+ */
+export function describeMeshDrift(tried, deployment) {
+    if (deployment == null || deployment.hubPeerId === tried)
+        return null;
+    return (` This deployment's httpeers.json now names a different hub (${deployment.hubPeerId}), ` +
+        "which is a different mesh -- so a membership in the old one cannot carry over. Re-running " +
+        '"pnpm bootstrap" does that, and so does moving between the Node hub and a hub page.');
+}
+export function createPeerSession(init) {
+    const startPeer = init.startPeer ?? startMember;
+    const identityStore = init.identity;
+    const meshMemory = init.meshMemory;
+    const readDeployment = init.readDeploymentConfig ?? readDeploymentConfigOverHttp;
+    const reload = init.reload;
+    let phase = { kind: "checking" };
+    let identity = null;
+    let handle = null;
+    /** One attempt at a time. Two concurrent `startBrowserPeer` calls would build two libp2p nodes on ONE identity -- the very duplicate this session refuses when someone else does it. */
+    let busy = false;
+    const state = () => ({
+        phase,
+        identity,
+        handle,
+        hubLink: phase.kind === "live" ? (handle?.hubLink() ?? null) : null,
+        controls: controlsFor(phase),
+    });
+    const set = (next) => {
+        phase = next;
+        init.onChange(state());
+    };
+    /**
+     * One join attempt, whichever way it was provoked (page load, the form,
+     * reconnect). `input` is what someone supplied, or `null` for a pure
+     * resume.
+     */
+    const attempt = async (input) => {
+        if (busy)
+            return;
+        busy = true;
+        /** The mesh this attempt actually tried, for the drift diagnostic below. */
+        let tried = null;
+        try {
+            set({ kind: "starting", peerState: "loading-config" });
+            // WHICH MESH, AND IN WHICH ORDER. A blob names its own and that is the
+            // end of it. A BARE invitation id skips the memory entirely and means
+            // the deployment's -- the contract `./join-blob.ts` states. Only a pure
+            // resume consults the memory, falling back to the deployment for a page
+            // that has only ever joined the Node hub.
+            const preferred = input != null ? configOf(input) : ((await meshMemory.read()) ?? undefined);
+            const config = preferred ?? (await readDeployment()) ?? undefined;
+            if (config == null) {
+                // `startMember` requires a config and there is none to give it, so
+                // nothing is started and the key is left untouched.
+                set({
+                    kind: "needs-invitation",
+                    reason: "no-mesh",
+                    message: "There is no mesh to join: this page remembers none, and this deployment's " +
+                        `${DEFAULT_HTTPEERS_CONFIG_URL} does not name one either. Paste a join link or a ` +
+                        "join blob -- either names its own mesh.",
+                });
+                return;
+            }
+            tried = config;
+            const key = await identityStore.loadOrCreate();
+            identity = peerIdOf(key);
+            const joined = await startPeer({
+                key: init.key,
+                mounts: init.mounts,
+                rules: init.rules,
+                advertisements: init.advertisements,
+                // The three things a page does differently, as one object — see
+                // `browser-platform.ts` for why this replaced a second lifecycle.
+                platform: init.platform,
+                privateKey: key,
+                invitationId: input == null ? undefined : invitationIdOf(input),
+                config,
+                onState: (peerState) => {
+                    // Late lifecycle callbacks from a peer that has since been stopped
+                    // must not repaint the page: `stop()` fires `"stopped"`, and a
+                    // disconnect that then redrew itself as "starting" would be a lie.
+                    if (phase.kind === "starting")
+                        set({ kind: "starting", peerState });
+                },
+                onPresenceRefused: (refusal) => {
+                    void onLostPresence(refusal);
+                },
+            });
+            handle = joined;
+            identity = joined.peerId;
+            // Remembered only now, and only from the handle -- see
+            // `./mesh-memory.ts`'s "WRITTEN ONLY AFTER A JOIN ACTUALLY SUCCEEDS".
+            await meshMemory.write({
+                relayAddrs: [joined.relayAddr],
+                hubPeerId: joined.hubPeerId,
+            });
+            set({
+                kind: "live",
+                joinedBy: joined.joinedBy,
+                note: [
+                    joined.joinedBy === "resumed" && input != null
+                        ? "This page was already a member of this mesh, so it resumed instead of " +
+                            "redeeming -- the invitation you supplied was not used and is still unspent. " +
+                            "Reset this page's identity if you meant to join as a new peer."
+                        : null,
+                    // Why the link is `relay` when it could have been direct -- see `MemberHandle.hubLinkNote`.
+                    joined.hubLinkNote ?? null,
+                ]
+                    .filter((line) => line != null)
+                    .join(" ") || null,
+            });
+        }
+        catch (err) {
+            handle = null;
+            await onAttemptFailed(err, input, tried);
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const onAttemptFailed = async (err, input, tried) => {
+        if (err instanceof MemberJoinError) {
+            if (err.reason === "duplicate-identity") {
+                set({ kind: "blocked", message: err.message });
+                return;
+            }
+            if (err.reason === "invitation-refused") {
+                set({ kind: "needs-invitation", reason: "invitation-refused", message: err.message });
+                return;
+            }
+            if (err.reason === "not-a-member") {
+                // Only a RESUME gets the drift diagnostic: if an invitation was
+                // supplied, the mesh came from that invitation and comparing it
+                // against `httpeers.json` would be comparing two things nobody
+                // claimed were the same.
+                const drift = input == null && tried != null
+                    ? describeMeshDrift(tried.hubPeerId, await readDeployment())
+                    : null;
+                set({
+                    kind: "needs-invitation",
+                    reason: "unknown-identity",
+                    message: err.message + (drift ?? ""),
+                });
+                return;
+            }
+        }
+        set({ kind: "failed", message: String(err) });
+        console.error("session: could not join the mesh:", err);
+    };
+    /**
+     * The hub refused a heartbeat of a page that WAS live. Nothing is torn
+     * down here except this peer's own node: a membership that has gone away,
+     * or an identity two nodes are fighting over, will not repair itself on
+     * the next tick, and a page left heartbeating into a refusal would look
+     * joined while being invisible to everyone else.
+     */
+    const onLostPresence = async (refusal) => {
+        if (phase.kind !== "live")
+            return;
+        const stopping = handle;
+        handle = null;
+        if (refusal.kind === "duplicate-identity") {
+            set({
+                kind: "blocked",
+                message: `Another live peer is now using this identity (${identity ?? "unknown"}). This page ` +
+                    "has stopped rather than take turns overwriting its presence -- close the other " +
+                    "tab, or reset this page's identity.",
+            });
+        }
+        else if (refusal.kind === "not-a-member") {
+            set({
+                kind: "needs-invitation",
+                reason: "unknown-identity",
+                message: "This hub no longer lists this peer as a member -- the membership was revoked, or " +
+                    "the hub's state was reset. This page has stopped; an invitation is the way back in.",
+            });
+        }
+        else {
+            set({
+                kind: "failed",
+                message: `The hub refused this page's heartbeat: ${refusal.message}`,
+            });
+        }
+        await stopping?.stop().catch(() => { });
+    };
+    return {
+        async start() {
+            let input;
+            try {
+                input = readJoinInputFromSearch(init.search);
+            }
+            catch (err) {
+                // A half-pasted link is a legible complaint, not a blank page -- and
+                // the form stays open so the operator can paste the whole one.
+                identity = await identityStore
+                    .read()
+                    .then((k) => (k == null ? null : peerIdOf(k)))
+                    .catch(() => null);
+                set({ kind: "needs-invitation", reason: "no-mesh", message: String(err) });
+                return;
+            }
+            const key = await identityStore.read();
+            identity = key == null ? null : peerIdOf(key);
+            if (key == null && input == null) {
+                // A FIRST RUN, SAID AS SUCH. Nothing is generated yet: creating a
+                // key here would make every later load report an identity this
+                // browser has never used for anything, and the difference between
+                // that and "the hub does not know my identity" is exactly what
+                // requirement 3 is about.
+                set({
+                    kind: "needs-invitation",
+                    reason: "no-identity",
+                    message: "This page has no saved identity yet -- it has never joined a mesh from this " +
+                        "browser. Paste an invitation id, a join blob, or a whole join link to join one; " +
+                        "an identity is created and saved at that point, and every later visit resumes " +
+                        "with it.",
+                });
+                return;
+            }
+            // An identity with no remembered mesh is NOT a refusal: `attempt`
+            // leaves the config undefined, `startBrowserPeer` fetches
+            // `httpeers.json`, and the deployment's own mesh is tried -- which is
+            // the only candidate there is, and the right one for every page that
+            // has only ever joined the Node hub.
+            await attempt(input);
+        },
+        async join(text) {
+            let input;
+            try {
+                input = readJoinInputFromText(text);
+            }
+            catch (err) {
+                set({ kind: "needs-invitation", reason: "invitation-refused", message: String(err) });
+                return;
+            }
+            if (input == null)
+                return; // an empty field is not an error, it is nothing happening.
+            await attempt(input);
+        },
+        async disconnect() {
+            const stopping = handle;
+            if (stopping == null)
+                return;
+            handle = null;
+            await stopping.stop();
+            set({
+                kind: "disconnected",
+                message: "Disconnected. This page still IS a member of the mesh -- membership is held by the " +
+                    "hub and nothing here surrendered it -- so reconnecting needs no new invitation. " +
+                    "Presence is a heartbeat, so this peer leaves everyone else's mesh view (and its " +
+                    "advertisements with it) within one presence interval.",
+            });
+        },
+        async reconnect() {
+            await attempt(null);
+        },
+        /**
+         * Forget this origin's key. DESTRUCTIVE, and the cost is worth stating
+         * where the caller can read it: the next run is a DIFFERENT peer, so
+         * this page's current membership becomes an orphaned record on the hub
+         * (visible to an admin, removable by one) and rejoining needs a fresh
+         * invitation. It exists because a stuck key with no way out is worse
+         * than no persistence at all -- the same reason the hub page has one
+         * (`../pages/hub/main.ts`), for a much smaller blast radius.
+         *
+         * The remembered mesh is deliberately KEPT: the new identity will still
+         * be joining the mesh this page was pointed at, and forgetting it would
+         * only mean a bare invitation id could no longer be used against a hub
+         * page.
+         */
+        async resetIdentity() {
+            const stopping = handle;
+            handle = null;
+            // Stopped first, so nothing is still heartbeating as a peer whose key
+            // is about to disappear.
+            await stopping?.stop().catch(() => { });
+            await identityStore.clear();
+            identity = null;
+            reload();
+        },
+        state,
+    };
+}

package/dist/start-member.d.ts

@@ -0,0 +1,176 @@
+/**
+ * `startMember` — the candidate `member` package's entry point.
+ *
+ * THIS IS `src/browser/peer-runtime.ts`'s `startBrowserPeer` WITH THREE
+ * COUPLINGS LIFTED OUT, and nothing else changed. Every step of the join is
+ * the proven one, imported from the stack rather than reimplemented:
+ * `dialRelay`, `reachHub`, `reachHubRelayed`, `createPeer`, `resumeMembership`,
+ * `redeemInvitation`, `reserveOnHub`, `superviseHubReservation`,
+ * `leaveRelay`, `startJoin`, `createRouteEnsurer`, `createEdgeDispatch`.
+ * If this file had to re-implement any of them, the seam would be in the
+ * wrong place and the rung would have failed.
+ *
+ * The three couplings, and why each is a platform boundary rather than a
+ * preference:
+ *
+ *   1. `createNode` — `createBrowserNode` hard-codes the browser transport
+ *      set (webSockets + webRTC + circuitRelay) and reads the identity key
+ *      out of IndexedDB. Node needs `tcp` as well, and its key comes from a
+ *      file. The LISTEN ADDRESSES ARE NOT A PLATFORM CHOICE and are kept
+ *      identical: a member listens on `/p2p-circuit` + `/webrtc` because it
+ *      reserves on its hub, which is what `feat/hub-relay` established.
+ *   2. `mountEdge` — the ServiceWorker is how a *page* turns `fetch()` into
+ *      a mesh call. Node has no ServiceWorker and needs none: the dispatch
+ *      handler IS the edge, callable in process. So the edge is optional,
+ *      and `MemberHandle.fetch` is always present — on both platforms it is
+ *      the same `createEdgeDispatch` handler, which is the whole isomorphism
+ *      claim in one field.
+ *   3. `watchWake` — `page-wake.ts` listens on `window`/`document`. A Node
+ *      process has no such events; the supervisor's own backstop timer is
+ *      what covers it, so the default is a no-op rather than a stub.
+ *
+ * `rules` replaces `policies`: `peer-runtime.ts` calls the app's `appRules`,
+ * which bakes `APP_RULES` — an application's vocabulary — into what ought to
+ * be library code. The caller passes a built `RuleSet` instead.
+ */
+import type { Ed25519PrivateKey, Libp2p } from "@libp2p/interface";
+import type { RuleSet } from "@statewalker/httpeers-access";
+import type { FetchHandler, MeshView, Mounts, PeerIdStr } from "@statewalker/httpeers-core";
+import { type ConnectionKind } from "./connection-kind.js";
+import type { AdvertisementInput, PresenceRefusal } from "./join.js";
+/** The mesh a member joins: exactly `httpeers.json`'s two fields. */
+export interface MeshConfig {
+    relayAddrs: string[];
+    hubPeerId: string;
+}
+/** What a platform's edge gives back. The browser's `mountEdge` already returns this shape. */
+export interface MemberEdge {
+    /** Where this peer's own `fetch()` reaches the mesh, e.g. `https://origin/peers/`. */
+    baseUrl: string;
+    stop(): Promise<void>;
+}
+/** The platform adapters — one per thing that genuinely differs between Node and a page. */
+export interface MemberPlatform {
+    /** Build the libp2p node. Browser: `createBrowserNode`. Node: `createNodeMemberNode` (`./node.ts`). */
+    createNode(init: {
+        privateKey?: Ed25519PrivateKey;
+    }): Promise<Libp2p>;
+    /**
+     * Publish `dispatch` at a local URL. Browser: the ServiceWorker edge, via
+     * `@statewalker/webrun-http-browser`'s `SwHttpAdapter`. Omitted under Node,
+     * where `MemberHandle.fetch` is the edge.
+     */
+    mountEdge?(init: {
+        key: string;
+        dispatch: FetchHandler;
+    }): Promise<MemberEdge>;
+    /** Fires when the host wakes (online / visible / resumed) so the supervisor retries at once. Browser: `watchPageWake`. */
+    watchWake?(onWake: () => void): () => void;
+}
+export interface StartMemberInit {
+    /** Mount-prefix first segment, and the ServiceWorker adapter key where there is one. */
+    key: string;
+    /** This peer's own mount table, served to other members and through its own edge. */
+    mounts: Mounts;
+    /** This peer's rule set, already built. Replaces `peer-runtime.ts`'s `policies` + `appRules`. */
+    rules: RuleSet;
+    /** The mesh to join. A page may read it from `httpeers.json`; that fetch is the caller's, not this function's. */
+    config: MeshConfig;
+    platform: MemberPlatform;
+    invitationId?: string;
+    privateKey?: Ed25519PrivateKey;
+    advertisements?: () => AdvertisementInput[];
+    onPresenceRefused?: (refusal: PresenceRefusal) => void;
+    onState?: (state: MemberState) => void;
+    heartbeatIntervalMs?: number;
+    keepaliveIntervalMs?: number;
+}
+export type MemberState = "connecting-relay" | "starting-peer" | "dialing-hub" | "resuming" | "joining" | "awaiting-reservation" | "mounting-edge" | "ready" | "stopped";
+export type JoinMethod = "resumed" | "redeemed";
+/**
+ * How a member reaches its hub. `"direct"` is the WebRTC upgrade, with a
+ * reservation on the hub so other members can reach this one through it.
+ * `"relay"` is the fallback when that upgrade fails (a hub in Docker on a
+ * bridge network), or when it succeeds but the hub then refuses the
+ * reservation for want of capacity (see `fallsBackToRelay`): a KEPT limited
+ * circuit through the public relay, over which this member calls the hub and
+ * nothing else -- no reservation, so no other member can reach it.
+ *
+ * FIXED FOR A RUN. It is decided once, at join; a relay-mode member re-links
+ * over a new circuit and never retries the upgrade (no automatic re-upgrade in
+ * v1), so it never becomes `"direct"` without direct mode's reservation. A new
+ * join (a reconnect) decides again.
+ */
+export type HubLink = "direct" | "relay";
+export interface MemberHandle {
+    peerId: PeerIdStr;
+    hubPeerId: string;
+    relayAddr: string;
+    joinedBy: JoinMethod;
+    /**
+     * This member's edge, in process. The SAME handler the ServiceWorker
+     * serves in a page — `createEdgeDispatch`'s — so a Node caller writes
+     * `member.fetch(new Request(\`http://local/${key}/${peer}/x\`))` where a
+     * page writes `fetch(\`${baseUrl}${peer}/x\`)`, and both take the identical
+     * path from there on.
+     */
+    fetch: FetchHandler;
+    /** Present only where the platform mounted an edge (a page). */
+    baseUrl?: string;
+    meshView(): MeshView | null;
+    token(): string;
+    connectionKind(peerId: string): ConnectionKind;
+    /** How this member reaches its hub -- see `HubLink`. Constant for the life of this handle. */
+    hubLink(): HubLink;
+    /**
+     * Why this member is in relay mode although its WebRTC upgrade worked -- the
+     * hub refused it a reservation -- in words a page can show. Absent when
+     * there is nothing unexpected to say: a direct link, or a relay link because
+     * the upgrade itself failed (a known deployment shape, see `HubLink`).
+     */
+    hubLinkNote?: string;
+    /**
+     * The libp2p node, as an escape hatch.
+     *
+     * `startBrowserPeer` does not expose it and a page never needs it. It is
+     * here because everything that OBSERVES OR PERTURBS THE TRANSPORT has to
+     * reach it: `connectionKind` above is already such a thing, and claim 7
+     * of this rung — drop the hub link and watch the supervisor restore it —
+     * cannot be written without it. A library that hides the node entirely
+     * makes its own recovery behaviour untestable from outside.
+     */
+    node: Libp2p;
+    stop(): Promise<void>;
+}
+export declare class MemberJoinError extends Error {
+    readonly reason: "not-a-member" | "duplicate-identity" | "presence-refused" | "invitation-refused";
+    constructor(reason: "not-a-member" | "duplicate-identity" | "presence-refused" | "invitation-refused", message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Does a refused reservation on the hub leave the join standing, in relay
+ * mode? Only when the refusal says nothing about THIS member:
+ *
+ *   - `store-full` (`RESERVATION_REFUSED`) and `resource-limit`
+ *     (`RESOURCE_LIMIT_EXCEEDED`) -- the hub is out of capacity. This is the
+ *     production failure: a hub's relay grants a fixed number of
+ *     reservations, and once they were spent every direct-linked page failed
+ *     to join while relay-mode pages worked.
+ *   - `no-answer` -- a timeout or a dropped link; nothing was refused.
+ *
+ * The reservation only lets OTHER members reach this one; everything the
+ * member does itself works in relay mode, so failing the join over it is
+ * strictly worse than degrading.
+ *
+ * NOT for `not-a-member` (`PERMISSION_DENIED`): the hub has just accepted
+ * this peer, so a hub that now denies it membership contradicts itself (a
+ * revocation in between, a gater reading a different store) -- a real fault
+ * to report, not a condition to route around. NOT for `no-relay`: a hub
+ * deployed without its relay service is a configuration error that would put
+ * every member in relay mode silently. NOT for any other status, which is a
+ * protocol fault. And not for errors that are not refusals at all.
+ */
+export declare function fallsBackToRelay(err: unknown): boolean;
+export declare function startMember(init: StartMemberInit): Promise<MemberHandle>;
+//# sourceMappingURL=start-member.d.ts.map

package/dist/start-member.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-member.d.ts","sourceRoot":"","sources":["../src/start-member.ts"],"names":[],"mappings":"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"}