@serfab/cadre-core 1.7.0 → 1.9.0

package/dist/strand-peer-book-swap.js

@@ -1,284 +0,0 @@
-/**
- * The per-strand driver of the strand peer book SWAP (`strand-peer-book-protocol.ts`
- * has the wire format, the signatures and the reasons): one of these per running
- * strand, armed on the strand's libp2p node right after it exists and released with
- * it, so a hibernation wake re-arms one on the rebuilt node. It owns three things:
- *
- * - **This node's own signed entry.** Built from the node's own bound addresses
- *   (`dialableAddrs`, the binding the observer applies to a remote), stamped with the
- *   local clock, signed with the strand transport key, and filed in the book under
- *   the node's own peer id. Signed at arm time and RE-SIGNED whenever the address set
- *   changes — `self:peer:update`, debounced because a relay reservation landing fires
- *   it more than once — which is what makes a rotation propagate. An unchanged
- *   address set is deliberately not re-signed on a timer: freshness is about change,
- *   and a periodic re-sign would only make every peer rewrite its slot.
- * - **The receiver**, registered through `node.handle` so a closed strand's revocation
- *   gate judges every inbound stream first.
- * - **The exchanges.** One when a strand peer is identified (the same `peer:identify`
- *   + `speaksBlockTransfer` gate the observer and the peer-join catch-up use, plus
- *   "lists the swap protocol", so an older node is skipped rather than dialed),
- *   throttled to one per peer per {@link STRAND_PEER_BOOK_SWAP_THROTTLE_MS}; and one
- *   with EVERY connected strand peer whenever the own entry is re-signed, unthrottled,
- *   so a rotation reaches everyone while connections are up. Both sides do this, so
- *   one connection produces two small exchanges; accepted as simpler than electing an
- *   initiator. A failed exchange is logged, never fatal, and never retried before the
- *   throttle expires.
- *
- * What lands in the book: the sender's own statement is filed as seen now (there is a
- * live connection to it); a forwarded third party's is filed as never seen, so it ages
- * from the signer's `issuedAt` alone. The store's merge rule does the rest — a signed
- * entry displaces an unsigned observation, and between two signed the greater
- * `issuedAt` wins — so a stale forward never displaces a fresher statement already
- * held. The seed and refresh read the book unchanged: a forwarded third party is
- * dialed like any other peer, and a rotated peer's newer addresses displace its old.
- *
- * The own entry the node SENDS is the in-memory one, never re-read from the store, so
- * the store's aging cannot lose it; the stored copy is a record for diagnostics and
- * the seed's self-skip. Nothing here throws into a libp2p event handler.
- */
-import debug from 'debug';
-import { circuitRequestBudgetMs } from './link-budget.js';
-import { speaksBlockTransfer } from './peer-join-backfill.js';
-import { STRAND_PEER_BOOK_PROTOCOL, StrandPeerBookService, exchangeStrandPeerBook, signStrandPeerEntry, trimBookFrameToFit } from './strand-peer-book-protocol.js';
-import { connectedIdentifiedPeers, dialableAddrs } from './strand-peer-observer.js';
-const log = debug('sereus:cadre:strand-peer-book-swap');
-/** Minimum gap between two exchanges with ONE peer, unless this node's own entry was re-signed. */
-export const STRAND_PEER_BOOK_SWAP_THROTTLE_MS = 10 * 60 * 1000;
-/** How long after the last `self:peer:update` the own entry is rebuilt — the event fires in bursts. */
-export const OWN_ENTRY_RESIGN_DEBOUNCE_MS = 1000;
-/**
- * Bytes allowance on top of the link round trips in the exchange deadline. A frame is
- * at most 64 KiB, so this is a token, not the 1 MiB push allowance.
- */
-const SWAP_TRANSFER_ALLOWANCE_MS = 1000;
-export class StrandPeerBookSwap {
-    constructor(deps, options) {
-        this.deps = deps;
-        /** Last exchange per peer id, for the throttle. */
-        this.exchangedAt = new Map();
-        /** Peers with an exchange in flight, so identify and a walk cannot double up. */
-        this.inFlight = new Set();
-        /**
-         * Peers whose in-flight exchange carries a since-replaced own entry: one more
-         * exchange follows the moment it settles. Without this a re-sign that lands while
-         * the identify exchange is still on the wire — the relay reservation arriving a
-         * second after the bootstrap dials do, which is routine — would never reach that
-         * peer until the next connection.
-         */
-        this.resendAfter = new Set();
-        /** Serialises own-entry refreshes: a burst of triggers signs at most once per change. */
-        this.selfChain = Promise.resolve();
-        this.started = false;
-        this.stopped = false;
-        this.selfPeerId = deps.libp2p.peerId.toString();
-        this.signingKey = usableSigningKey(deps.privateKey, this.selfPeerId, deps.strandId);
-        this.throttleMs = options?.throttleMs ?? STRAND_PEER_BOOK_SWAP_THROTTLE_MS;
-        this.debounceMs = options?.debounceMs ?? OWN_ENTRY_RESIGN_DEBOUNCE_MS;
-        this.timeoutMs = options?.timeoutMs ?? circuitRequestBudgetMs(deps.linkRoundTripMs, SWAP_TRANSFER_ALLOWANCE_MS);
-        this.now = options?.now ?? Date.now;
-        this.service = new StrandPeerBookService({
-            strandId: deps.strandId,
-            selfPeerId: this.selfPeerId,
-            localEntries: (forPeerId) => this.frameFor(forPeerId).entries,
-            onEntries: (entries, fromPeerId) => this.accept(entries, fromPeerId),
-            readTimeoutMs: this.timeoutMs,
-            now: this.now
-        });
-        this.onPeerIdentify = (evt) => {
-            const { peerId, protocols, connection } = evt.detail;
-            if (this.isSwapPeer(peerId, protocols)) {
-                void this.exchangeWith(peerId, connection, false, 'identify');
-            }
-        };
-        this.onSelfUpdate = () => {
-            if (this.debounceTimer)
-                clearTimeout(this.debounceTimer);
-            this.debounceTimer = setTimeout(() => {
-                this.debounceTimer = undefined;
-                this.queueSelfRefresh('self:peer:update');
-            }, this.debounceMs);
-        };
-    }
-    /** This node's current signed entry, or `undefined` before the first signing or without a key. */
-    get ownEntry() {
-        return this.own;
-    }
-    /**
-     * Register the receiver, subscribe, sign the own entry, and exchange with the strand
-     * peers already connected — identify for an early peer may have fired before this
-     * object existed.
-     */
-    start() {
-        if (this.started || this.stopped)
-            return;
-        this.started = true;
-        this.deps.libp2p.addEventListener('peer:identify', this.onPeerIdentify);
-        this.deps.libp2p.addEventListener('self:peer:update', this.onSelfUpdate);
-        void this.service.initialize(this.deps.libp2p).catch((error) => {
-            log('[%s] registering the swap handler failed — this node answers no swaps: %o', this.deps.strandId, error);
-        });
-        this.queueSelfRefresh('start');
-    }
-    /** Unsubscribe and unregister; an exchange in flight finishes on its own. */
-    async stop() {
-        if (this.stopped)
-            return;
-        this.stopped = true;
-        if (this.debounceTimer) {
-            clearTimeout(this.debounceTimer);
-            this.debounceTimer = undefined;
-        }
-        if (this.started) {
-            this.deps.libp2p.removeEventListener('peer:identify', this.onPeerIdentify);
-            this.deps.libp2p.removeEventListener('self:peer:update', this.onSelfUpdate);
-        }
-        try {
-            await this.service.shutdown();
-        }
-        catch (error) {
-            log('[%s] unregistering the swap handler failed (ignored): %o', this.deps.strandId, error);
-        }
-        this.exchangedAt.clear();
-        log('[%s] stopped', this.deps.strandId);
-    }
-    /** A strand peer that also speaks the swap; never self. */
-    isSwapPeer(peerId, protocols) {
-        if (peerId.toString() === this.selfPeerId || !speaksBlockTransfer(protocols, this.deps.protocolPrefix)) {
-            return false;
-        }
-        if (!protocols.includes(STRAND_PEER_BOOK_PROTOCOL)) {
-            log('[%s] strand peer %s does not speak the swap (older node) — not dialing it', this.deps.strandId, peerId.toString());
-            return false;
-        }
-        return true;
-    }
-    queueSelfRefresh(reason) {
-        this.selfChain = this.selfChain
-            .then(() => this.refreshSelf(reason))
-            .catch((error) => log('[%s] own-entry refresh (%s) failed: %o', this.deps.strandId, reason, error));
-    }
-    /** Re-sign the own entry if the address set changed, then exchange — unthrottled after a re-sign. */
-    async refreshSelf(reason) {
-        if (this.stopped)
-            return;
-        const resigned = await this.refreshOwnEntry(reason);
-        await this.exchangeWithConnected(resigned, reason);
-    }
-    /** Returns whether a new own entry was signed. */
-    async refreshOwnEntry(reason) {
-        if (!this.signingKey)
-            return false;
-        const addrs = dialableAddrs(this.selfPeerId, this.deps.libp2p.getMultiaddrs(), []);
-        const addrKey = [...addrs].sort().join('\n');
-        if (addrKey === this.ownAddrKey)
-            return false;
-        // Strictly increasing past every statement this node is known to have made — the
-        // one in memory, and on a fresh driver the copy the store kept from the previous
-        // run — so the receiver's "greater issuedAt wins" always prefers the later one.
-        // The stored floor is what survives a restart on a clock that went backwards:
-        // without it every peer would keep the old statement until the clock passed it.
-        const issuedAt = Math.max(this.now(), this.lastOwnIssuedAt() + 1);
-        const entry = await signStrandPeerEntry(this.signingKey, this.deps.strandId, addrs, issuedAt);
-        if (this.stopped)
-            return false;
-        this.own = entry;
-        this.ownAddrKey = addrKey;
-        this.remember(entry, this.now());
-        log('[%s] own entry signed (%s): %d addr(s), issuedAt=%d', this.deps.strandId, reason, addrs.length, issuedAt);
-        return true;
-    }
-    /** The greatest `issuedAt` this node has signed: in memory, else the stored own entry's, else 0. */
-    lastOwnIssuedAt() {
-        if (this.own)
-            return this.own.issuedAt;
-        return this.deps.store.entries(this.deps.strandId).find((held) => held.peerId === this.selfPeerId)?.issuedAt ?? 0;
-    }
-    /** Exchange with every connected, identified strand peer that speaks the swap. */
-    async exchangeWithConnected(bypassThrottle, reason) {
-        const peers = await connectedIdentifiedPeers(this.deps.libp2p, this.deps.strandId);
-        await Promise.all(peers
-            .filter(({ peerId, protocols }) => this.isSwapPeer(peerId, protocols))
-            .map(({ peerId, connections }) => this.exchangeWith(peerId, connections[0], bypassThrottle, reason)));
-    }
-    /**
-     * One exchange with one peer over `connection`, throttled unless told otherwise (a
-     * re-sign) — in which case an exchange already in flight, which carries the old
-     * entry, is followed by one more once it settles. Never throws.
-     */
-    async exchangeWith(peerId, connection, bypassThrottle, reason) {
-        if (this.stopped)
-            return;
-        const id = peerId.toString();
-        if (this.inFlight.has(id)) {
-            if (bypassThrottle)
-                this.resendAfter.add(id);
-            return;
-        }
-        const now = this.now();
-        const last = this.exchangedAt.get(id);
-        if (!bypassThrottle && last !== undefined && now - last < this.throttleMs)
-            return;
-        this.exchangedAt.set(id, now);
-        this.inFlight.add(id);
-        try {
-            const request = this.frameFor(id);
-            const received = await exchangeStrandPeerBook(connection, request, {
-                selfPeerId: this.selfPeerId,
-                timeoutMs: this.timeoutMs,
-                now: this.now
-            });
-            this.accept(received, id);
-            log('[%s] swapped with %s (%s): sent %d, received %d', this.deps.strandId, id, reason, request.entries.length, received.length);
-        }
-        catch (error) {
-            log('[%s] swap with %s (%s) failed — next try after the throttle: %o', this.deps.strandId, id, reason, error);
-        }
-        finally {
-            this.inFlight.delete(id);
-        }
-        if (this.resendAfter.delete(id)) {
-            await this.exchangeWith(peerId, connection, true, `${reason}, re-signed meanwhile`);
-        }
-    }
-    /**
-     * What this node sends `remotePeerId`: its own entry first, then every signed entry
-     * held for anyone else, freshest first, minus the recipient's own — trimmed from the
-     * stale end to the frame's entry and byte caps (the own entry can push the store's
-     * cap over by one, and long addresses can push the bytes over).
-     */
-    frameFor(remotePeerId) {
-        const entries = this.own ? [this.own] : [];
-        for (const held of this.deps.store.entries(this.deps.strandId)) {
-            if (held.sig === undefined || held.peerId === this.selfPeerId || held.peerId === remotePeerId)
-                continue;
-            entries.push({ peerId: held.peerId, addrs: held.addrs, issuedAt: held.issuedAt, sig: held.sig });
-        }
-        return trimBookFrameToFit({ strandId: this.deps.strandId, entries });
-    }
-    /** File verified entries: the sender's own as seen now, a forwarded third party's as never seen. */
-    accept(entries, fromPeerId) {
-        const now = this.now();
-        for (const entry of entries) {
-            this.remember(entry, entry.peerId === fromPeerId ? now : 0);
-        }
-    }
-    /** Fire-and-log, like every book write: visible synchronously, the promise tracks durability. */
-    remember(entry, lastSeenAt) {
-        void this.deps.store.merge(this.deps.strandId, { ...entry, lastSeenAt }).catch((error) => {
-            log('[%s] persisting entry for %s failed (continuing): %o', this.deps.strandId, entry.peerId, error);
-        });
-    }
-}
-/** The key, if it is Ed25519 and actually the node's own; else `undefined`, logged. */
-function usableSigningKey(privateKey, selfPeerId, strandId) {
-    if (!privateKey) {
-        log('[%s] no strand transport key — no own entry will be signed', strandId);
-        return undefined;
-    }
-    if (privateKey.type !== 'Ed25519' || privateKey.publicKey.toString() !== selfPeerId) {
-        log('[%s] the supplied key is not this node\'s Ed25519 transport key — no own entry will be signed', strandId);
-        return undefined;
-    }
-    return privateKey;
-}
-//# sourceMappingURL=strand-peer-book-swap.js.map

package/dist/strand-peer-book-swap.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"strand-peer-book-swap.js","sourceRoot":"","sources":["../src/strand-peer-book-swap.ts"],"names":[],"mappings":"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"}

package/dist/strand-peer-book.d.ts

@@ -1,159 +0,0 @@
-import { type DurableSlot } from './node-local-snapshot.js';
-/**
- * Cap on the peers remembered per strand. When full, the entry with the smallest
- * `max(issuedAt, lastSeenAt)` is evicted. Sixteen is generous for the parties a
- * strand has today (two, occasionally a few), and it bounds the worst case of a
- * launch dialing dead entries: a failed relayed dial costs up to 14 s at the
- * declared link, so the cap — with aging — is what keeps a stale book from
- * stalling bring-up for minutes.
- */
-export declare const MAX_STRAND_PEERS = 16;
-/**
- * Default age after which an entry nobody has refreshed is dropped: 14 days from
- * `max(issuedAt, lastSeenAt)`. A live peer refreshes its entry on every connection,
- * so only a peer this node has not reached in two weeks ages out. Overridable per
- * store via {@link StrandPeerBookOptions.maxAgeMs}.
- */
-export declare const STRAND_PEER_MAX_AGE_MS: number;
-/**
- * One strand peer this node knows an address for. `sig` is set only on an entry the
- * peer signed itself and the book swap carried here (`strand-peer-book-protocol.ts`),
- * or on this node's own entry, which the swap files under the node's own strand
- * transport id; a formation-carried or observed entry is unsigned and local-only.
- */
-export interface StrandPeerEntry {
-    /** The peer's STRAND transport peer id (never a control peer id). */
-    peerId: string;
-    /**
-     * Multiaddr strings, each bound to `peerId` (trailing `/p2p/<peerId>`, a relay
-     * hop only with that destination behind it), signaling-first, at most
-     * `MAX_STRAND_ADDRS`. Anything that does not attribute to `peerId` is dropped
-     * at merge.
-     */
-    addrs: string[];
-    /**
-     * Signer's clock, ms: when the peer itself issued these addresses. 0 for an
-     * entry this node observed or was handed unsigned.
-     */
-    issuedAt: number;
-    /**
-     * base64url Ed25519 signature by the peer's strand transport key over the canonical
-     * JSON of `{ v, strandId, peerId, addrs, issuedAt }` (`signedStrandPeerEntryPayload`);
-     * absent = local-only, never forwarded.
-     */
-    sig?: string;
-    /**
-     * This node's clock, ms: when it last held a connection to the peer — or, for a
-     * formation-carried entry, when the responder disclosed the addresses live — and 0
-     * for an entry it has never connected to. Local, never on the wire.
-     */
-    lastSeenAt: number;
-}
-export interface StrandPeerBookStore {
-    /** Party this store is scoped to. */
-    readonly partyId: string;
-    /**
-     * Snapshot of one strand's LIVE entries, freshest first
-     * (`max(issuedAt, lastSeenAt)` descending). Empty for an unknown strand. Aged-out
-     * entries are never returned. Every backend copies the entries per call, so the
-     * result is decoupled from later {@link merge} / {@link forget} calls.
-     */
-    entries(strandId: string): StrandPeerEntry[];
-    /**
-     * Insert or replace by `(strandId, entry.peerId)` under the merge rule
-     * ({@link mergeStrandPeerEntry}): a signed entry never yields to an unsigned
-     * one; between two signed the greater `issuedAt` wins; between two unsigned the
-     * greater `lastSeenAt` wins; `lastSeenAt` is always the max of old and new. Then
-     * the strand's aged-out entries are dropped and, past {@link MAX_STRAND_PEERS},
-     * the stalest evicted.
-     *
-     * Implementations MUST reflect the merge in {@link entries} SYNCHRONOUSLY; the
-     * returned promise tracks durability only. An entry whose peer id does not parse
-     * is logged and dropped rather than thrown — every writer is a best-effort event
-     * handler.
-     */
-    merge(strandId: string, entry: StrandPeerEntry): Promise<void>;
-    /**
-     * Drop one peer, or the whole strand when `peerId` is omitted — for a strand this
-     * node unpublished or left, whose peers must not stay dial targets. Forgetting
-     * something absent is a no-op. Same contract as {@link merge}: reflected
-     * synchronously, the promise tracks durability.
-     */
-    forget(strandId: string, peerId?: string): Promise<void>;
-}
-/** Tuning shared by every backend. */
-export interface StrandPeerBookOptions {
-    /** Age after which an unrefreshed entry is dropped. Default {@link STRAND_PEER_MAX_AGE_MS}. */
-    maxAgeMs?: number;
-    /** Clock, for tests. Default `Date.now`. */
-    now?: () => number;
-}
-/** The moment an entry was last vouched for, by whichever clock spoke last. */
-export declare function strandPeerFreshness(entry: StrandPeerEntry): number;
-/**
- * The merge rule, in one place. Returns the entry to hold for `incoming.peerId`
- * given what is already held — always a NEW object, so a held entry is never mutated
- * in place (the persistent backend's snapshot `put` replaces rather than patches).
- * `incoming` is assumed sanitized ({@link sanitizeStrandPeerEntry}).
- *
- * - A signed entry never yields to an unsigned one for the same peer: the peer's own
- *   statement outranks this node's observation of it.
- * - Between two signed entries the greater `issuedAt` wins; between two unsigned
- *   entries the greater `lastSeenAt` wins. A tie goes to `incoming`.
- * - `lastSeenAt` is always the max of old and new whichever entry wins, because it
- *   is this node's own observation and no remote statement can lower it.
- */
-export declare function mergeStrandPeerEntry(existing: StrandPeerEntry | undefined, incoming: StrandPeerEntry): StrandPeerEntry;
-/**
- * Shape an entry for storage: the peer id must parse (else `undefined` — not a dial
- * target at all), and `addrs` is reduced to the entries that attribute to `peerId`
- * under `groupAddrsByPeerId`'s rule, de-duplicated, capped at `MAX_STRAND_ADDRS`, and
- * — for an UNSIGNED entry only — reordered signaling-first. A signed entry keeps the
- * signer's order: its signature covers the address list as signed, and the swap
- * forwards the stored copy, so any reordering here would make every forwarded entry
- * fail verification at the next peer (every signer already orders signaling-first). An
- * entry may legitimately end up with NO addresses — a signed "not reachable right
- * now" from the swap protocol is truthful and displaces a stale reachable list — so
- * an empty list is kept, not rejected.
- */
-export declare function sanitizeStrandPeerEntry(entry: StrandPeerEntry): StrandPeerEntry | undefined;
-/**
- * Ephemeral in-memory book for nodes without durable storage (tests, and the
- * default when nothing is injected). Same contract, no disk: a node using this
- * forgets every strand peer on restart — the #18 shape.
- */
-export declare class MemoryStrandPeerBookStore implements StrandPeerBookStore {
-    readonly partyId: string;
-    private readonly strands;
-    private readonly options;
-    constructor(partyId: string, options?: StrandPeerBookOptions);
-    entries(strandId: string): StrandPeerEntry[];
-    merge(strandId: string, entry: StrandPeerEntry): Promise<void>;
-    forget(strandId: string, peerId?: string): Promise<void>;
-}
-/**
- * Durable {@link StrandPeerBookStore} over an app-supplied {@link DurableSlot} —
- * the cross-platform half of every persistent backend (the Node
- * `FileStrandPeerBookStore` is this class over a file slot).
- *
- * Construct via {@link open}. Load and persist policy — what an absent, corrupt,
- * foreign-party or unreadable slot does (the last one THROWS, as
- * `PersistentBootstrapPeerStore.open` does), and what a failed persist does — is
- * documented once on `NodeLocalSnapshot`; this class only supplies the payload shape
- * and the drop-the-bad-entry policy above. Writes are serialised in-process by the
- * snapshot's write chain, so several strands' identify handlers merging at once
- * cannot interleave partial snapshots.
- */
-export declare class PersistentStrandPeerBookStore implements StrandPeerBookStore {
-    private readonly snapshot;
-    private readonly options;
-    private constructor();
-    /** Load (or cold-start) the party's book from `slot`. */
-    static open(slot: DurableSlot, partyId: string, options?: StrandPeerBookOptions): Promise<PersistentStrandPeerBookStore>;
-    get partyId(): string;
-    entries(strandId: string): StrandPeerEntry[];
-    /** Merge, visible via {@link entries} synchronously, then the full snapshot is persisted. */
-    merge(strandId: string, entry: StrandPeerEntry): Promise<void>;
-    /** Forget, gone from {@link entries} synchronously, then persisted — unless nothing was there. */
-    forget(strandId: string, peerId?: string): Promise<void>;
-}