@serfab/cadre-core 1.17.0 → 1.19.0

package/dist/peer-join-backfill.d.ts

@@ -1,13 +1,7 @@
 import type { Libp2p, PeerId } from '@libp2p/interface';
-import type { IPeerNetwork } from '@optimystic/db-core';
+import { type IPeerNetwork } from '@optimystic/db-core';
 import { BlockTransferClient, type IRawStorage } from '@optimystic/db-p2p';
-/**
- * The block-transfer protocol's hard cap on one length-prefixed message. Mirrors
- * `MAX_BLOCK_MESSAGE_BYTES` in `@optimystic/db-p2p`'s `protocol-limits.ts` (8 MiB), which
- * that package does not re-export from its index — keep the two in sync if upstream ever
- * changes it or starts exporting it.
- */
-export declare const MAX_BLOCK_MESSAGE_BYTES: number;
+import type { Libp2pNodeWithRepo } from './types.js';
 /**
  * Consecutive failed catch-up runs against ONE peer before the module says so on
  * `console.warn` rather than only in its DEBUG log. At the default backoff that is reached
@@ -19,11 +13,18 @@ export declare const PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES = 3;
 export interface PeerJoinBackfillConfig {
     /** Default true. False disables the catch-up entirely (the pre-existing behaviour). */
     enabled?: boolean;
-    /** Settle time after a connection opens before catching that peer up, ms. Default 1000. */
+    /**
+     * Settle time before re-running a peer this instance has already run for (a denied or failed
+     * peer's next schedule), ms. Default 1000. A peer never run for is run at once.
+     */
     debounceMs?: number;
     /** Ceiling on blocks copied in one catch-up. Default 10_000. Reaching it is LOGGED, never silent. */
     maxBlocks?: number;
-    /** Soft byte budget per push message. Default 1 MiB. Protocol hard cap is {@link MAX_BLOCK_MESSAGE_BYTES} (8 MiB). */
+    /**
+     * Soft byte budget per push message, as the sum of its blocks' `jsonEncodedBytes` (the form they
+     * travel in). Default 1 MiB. A single block over it still ships alone; one over `MAX_BLOCK_BYTES`
+     * never ships (see {@link PeerJoinBackfillResult.oversized}).
+     */
     maxChunkBytes?: number;
     /** Max blocks per push message. Default 64. */
     maxChunkBlocks?: number;
@@ -76,6 +77,12 @@ export interface PeerJoinBackfillDeps {
      * see the module comment for why the strand no-gate argument does not carry over.
      */
     authorizePeer?: (peerId: string) => Promise<boolean>;
+    /**
+     * The node's `reportBlockHeld` ({@link Libp2pNodeWithRepo.reportBlockHeld}), told of each block a
+     * peer accepted so Optimystic's under-replication drain does not push the peer the same block
+     * again, one request per block. Absent = nothing reported, and the drain re-sends.
+     */
+    reportBlockHeld?: Libp2pNodeWithRepo['reportBlockHeld'];
     /**
      * Test seam: build the per-peer push client. Defaults to a real
      * `BlockTransferClient` over {@link peerNetwork} + {@link protocolPrefix}.
@@ -84,11 +91,21 @@ export interface PeerJoinBackfillDeps {
 }
 /** What one peer's catch-up actually did. Returned for tests and logged at the end of each run. */
 export interface PeerJoinBackfillResult {
-    /** Blocks offered: had a committed `latest` AND materialized content locally. */
+    /** Blocks offered: had a committed `latest` AND materialized content locally, and the peer was not known to hold it. */
     offered: number;
+    /**
+     * Skipped: the peer already accepted or refused this revision from this node, or signed its
+     * commit (see "What is pushed" in the module comment). Not offered, so not counted toward
+     * `maxBlocks`.
+     */
+    alreadyHeld: number;
     /** Blocks the remote reported it persisted. */
     accepted: number;
-    /** Block ids the remote reported in `missing` (parse or persist failure on its side). */
+    /**
+     * Block ids the remote reported in `missing` (unparseable, not persisted, or pushed without a
+     * commit proof it accepts). Remembered per revision; not offered to that peer again until the
+     * local revision moves.
+     */
     rejected: string[];
     /** Skipped: metadata has no `latest` (pending-only — not yet a durability claim here). */
     uncommitted: number;
@@ -96,7 +113,7 @@ export interface PeerJoinBackfillResult {
     unmaterialized: number;
     /** Not attempted because `maxBlocks` was reached. */
     capped: number;
-    /** Skipped: a single block whose wire size alone exceeds {@link MAX_BLOCK_MESSAGE_BYTES}. */
+    /** Skipped: a block whose `jsonEncodedBytes` exceeds db-core's per-block limit, `MAX_BLOCK_BYTES`. */
     oversized: string[];
     /** True when the `authorizePeer` gate refused (or threw) — nothing was pushed, peer not memoized. */
     denied: boolean;
@@ -109,8 +126,8 @@ export interface PeerJoinBackfillResult {
  *
  * Best-effort throughout: nothing here throws into a libp2p event handler or into a
  * runtime bring-up; a failed chunk is logged and the run continues. A peer is marked
- * fully caught up ONLY after a run with no thrown chunk and an empty `missing` list, so
- * the next `peer:identify` from a peer whose catch-up failed retries it.
+ * caught up only after a run with no thrown chunk, so a peer whose catch-up failed is
+ * retried; each block is pushed to each peer once (see "What is pushed" in the module comment).
  */
 export declare class PeerJoinBackfill {
     private readonly deps;
@@ -119,10 +136,22 @@ export declare class PeerJoinBackfill {
     private started;
     private stopped;
     /**
-     * Peers fully caught up this runtime (never rescheduled until the runtime is rebuilt; only
-     * {@link forceCatchUpPeer} pushes to one again).
+     * Peers caught up since their current connection opened. Cleared for a peer when its last
+     * connection closes, so a reconnect re-runs; {@link forceCatchUpPeer} runs past it.
      */
     private readonly done;
+    /**
+     * Peers that disconnected while their run was in flight, so that run does not mark them
+     * {@link done} after the disconnect cleared it. Cleared when the run ends.
+     */
+    private readonly disconnectedInFlight;
+    /** Per-peer, per-block verdicts from push replies; see {@link PeerMemo}. */
+    private readonly memos;
+    /**
+     * Peers a run has been started for. A peer not in it is run at once on its first schedule;
+     * later schedules wait out `debounceMs`.
+     */
+    private readonly contacted;
     /**
      * Peers with a catch-up currently running, each with that run (suppresses concurrent
      * duplicates; {@link forceCatchUpPeer} waits on the run).
@@ -130,9 +159,9 @@ export declare class PeerJoinBackfill {
     private readonly inFlight;
     /**
      * Peers whose (re-)schedule arrived while their OWN run was in flight, replayed once
-     * that run finishes. Load-bearing for the gated path: the gate's authorization check is
-     * a control-database read, so the window between it and the run's end is wide enough for
-     * the very membership commit that would have authorized the peer to land inside it —
+     * that run finishes. Load-bearing for the gated path: the gate is judged once, at the start
+     * of a run, and the run's pushes take long enough for the very membership commit that would
+     * have authorized the peer to land after that check —
      * dropping that schedule (rather than deferring it) leaves the denied peer waiting for a
      * reconnect, which is exactly what the re-arm exists to avoid.
      */
@@ -150,17 +179,32 @@ export declare class PeerJoinBackfill {
     /** Peers already reported on `console.warn`; reset when a run finally lands cleanly. */
     private readonly warned;
     private readonly onPeerIdentify;
+    private readonly onPeerDisconnect;
     private loggedNoListBlockIds;
     constructor(deps: PeerJoinBackfillDeps, config?: PeerJoinBackfillConfig);
     /**
      * Subscribe to `peer:identify` AND schedule a catch-up for already-connected peers whose
      * stored protocols already name this network's block-transfer protocol — a peer that does
-     * not speak it (a bare circuit relay, a bootstrap node) is never scheduled at all. See
-     * {@link speaksBlockTransfer} and the module comment.
+     * not speak it (a bare circuit relay, a bootstrap node) is never scheduled at all. Also
+     * subscribes to `peer:disconnect`, so a peer caught up before it went away is run again on
+     * its return. See {@link speaksBlockTransfer} and the module comment.
      */
     start(): void;
     /** Unsubscribe, clear timers; in-flight runs observe the stopped flag and bail. */
     stop(): void;
+    /**
+     * A peer's last connection closed: it is no longer caught up, so its next `peer:identify`
+     * re-runs. Only `done` is cleared. The memo stays (it keeps the re-run to what moved),
+     * `contacted` stays (a link flapping inside one settle window costs one run), and the
+     * backoff state stays (clearing it re-dials an unreachable peer on every reconnect; see the
+     * module comment's retry paragraph).
+     *
+     * When the returning peer wrote while away with a cohort that named this node, its own
+     * re-run pushes those blocks here and reports them through `reportBlockHeld`, so its
+     * under-replication drain does not push them again. Revisit if a measurement shows reconnect
+     * re-runs dominating push traffic.
+     */
+    private forgetCaughtUp;
     /**
      * (Re-)schedule a debounced catch-up for every currently-connected peer whose protocols, as
      * already stored in the libp2p peer store, name this network's block-transfer protocol. A
@@ -177,7 +221,11 @@ export declare class PeerJoinBackfill {
     scheduleConnectedPeers(): Promise<number>;
     /** Schedules `peerId` only if the peer store already knows it speaks this network's protocol. */
     private scheduleIfKnownToSpeak;
-    /** Debounced entry point for connection churn: one run per peer per settle window. */
+    /**
+     * Entry point for connection churn: one run per peer per settle window, except that a peer
+     * never run for is run at once (on a zero-delay timer, so a burst of identify events in one
+     * turn still collapses, and no work happens inside the libp2p event dispatch).
+     */
     private schedulePeer;
     /**
      * Run one peer's catch-up now, bypassing the debounce. Never rejects. Returns an
@@ -186,14 +234,16 @@ export declare class PeerJoinBackfill {
      */
     catchUpPeer(peerId: PeerId): Promise<PeerJoinBackfillResult>;
     /**
-     * Run one peer's catch-up now and wait for it, whatever this instance remembers about the
-     * peer: wait out a run already in flight for it, then push the whole store again even when
-     * the peer is memoized as caught up. Never rejects; an all-zero result only when stopped.
+     * Run one peer's catch-up now and wait for it, even when the peer is memoized as caught up:
+     * wait out a run already in flight for it, then run again. The run still skips every block the
+     * peer is known to hold (it accepted or refused that revision, or signed it), so for a peer that
+     * holds the whole store it pushes nothing and returns `alreadyHeld` equal to the store size.
+     * Never rejects; an all-zero result only when stopped.
      *
      * For a caller that must know the peer holds this store before it proceeds, where
      * {@link catchUpPeer}'s empty answer would hide a run that was denied (a `peer:identify`
-     * run can pass the gate a moment before the caller authorized the peer) or a memo older
-     * than the commits since.
+     * run can pass the gate a moment before the caller authorized the peer) or commits made
+     * since the peer was caught up.
      */
     forceCatchUpPeer(peerId: PeerId): Promise<PeerJoinBackfillResult>;
     /**
@@ -218,10 +268,26 @@ export declare class PeerJoinBackfill {
      * timeout. Reset when a run finally lands cleanly, so a peer that recovers can report again.
      */
     private warnPersistentFailure;
+    /** This peer's memo, created empty on first use. */
+    private memoFor;
+    /**
+     * Tell the node which blocks of one push reply the peer accepted, at the revision pushed.
+     * Best-effort: a failed report is logged and costs only the drain's duplicate push.
+     */
+    private reportAccepted;
     /**
-     * The actual copy. `clean` = every chunk pushed and the remote persisted every block.
+     * The actual copy. `clean` = the gate admitted the peer, the store is listable and no push
+     * threw (a block the receiver refused is remembered per block instead, see {@link PeerMemo}).
      * `pushFailed` = at least one push THREW, which is the only non-clean outcome a retry can
-     * change; the others are verdicts (denied, inert store, blocks the receiver refused).
+     * change; the others are verdicts (denied, inert store).
      */
     private runCatchUp;
+    /**
+     * Read one block for the push to `key`, or count why it is skipped in `result` and return
+     * nothing: not committed, already held by the peer (memo or its own commit signature), not
+     * materialized, or over the per-block size limit. The proof is read for EXACTLY the revision the
+     * meta will name, from the same `latest`; absent is normal (nothing retained a proof for that
+     * revision), and the block still ships with its meta for the receiver to decide.
+     */
+    private readOffer;
 }