p2p-fret 1.0.2 → 1.1.0

package/dist/src/estimate/size-estimator.js

@@ -81,7 +81,7 @@ function windowGaps(store, m, selfCoord, selfId, filter) {
  * into a tiny, evenly-spaced arc — an eclipse, or a very young ring — scores high here while
  * `n` is wildly wrong, because no statistic over the sampled arc can see the arc that was never
  * sampled. The defense is corroboration from peer-reported estimates (`reportNetworkSize` /
- * `calibrateSizeFromSnapshot`), not a better local formula.
+ * `calibrateSizeFromPeer`), not a better local formula.
  */
 function dispersionFactor(gaps) {
     const count = gaps.length;

package/dist/src/index.d.ts

@@ -18,6 +18,36 @@ export interface FretConfig {
      * spacing window count once, so the run is genuinely spread over time.
      */
     deadAfterFailures?: number;
+    /**
+     * Whole-dial budget, in milliseconds, for a maintenance **redial** — the connection FRET opens
+     * on its own to a routing-table peer it is not connected to (default 10 000 ms).
+     *
+     * A maintenance ping assumes an open connection and is bounded by a 2 s exchange budget; opening
+     * one is a separate step with this budget, run outside the stabilization tick. The default
+     * restates libp2p's own `dialTimeout` default (10 s), because libp2p applies that only to a dial
+     * that carries *no* abort signal — FRET always passes one, so this is the only whole-dial limit
+     * in force (libp2p's per-address `addressDialTimeout` still applies underneath). A host on slow
+     * relayed links sets it from its link budget: a circuit-relay dial that completes in 9 s is
+     * ordinary there. Must be a positive finite number; the constructor throws otherwise.
+     */
+    dialTimeoutMs?: number;
+    /**
+     * The ceiling, in milliseconds, the passive stabilization interval may grow to while nothing in
+     * the network changes (default 60 000 ms).
+     *
+     * Passive stabilization runs every 1.5 s while things are changing and doubles that interval
+     * after every pass that finds nothing to act on — 1.5 → 3 → 6 → 12 → 24 → 48 s, then this
+     * ceiling — snapping back to 1.5 s the moment anything changes (a connection forms or drops, a
+     * peer is discovered, a label or liveness verdict moves, an address becomes known). At the
+     * default an idle node runs about one pass a minute instead of forty. The cost of a higher
+     * ceiling is detection latency for what only a pass can see: a peer that went silent with no
+     * disconnect event is first struck on the next pass (up to one interval away) and dead a few
+     * seconds after, a neighbour's content is re-checked once per interval, and an off-ring peer
+     * whose backoff window expired is re-probed up to one interval late. A host that wants faster
+     * detection sets this lower; a value at or below 1.5 s disables backoff altogether.
+     * Must be a positive finite number; the constructor throws otherwise.
+     */
+    maxPassiveIntervalMs?: number;
     /**
      * This node's libp2p private key — the key `node.peerId` was derived from.
      *
@@ -62,6 +92,13 @@ export interface NeighborSnapshotV1 {
      * an id-keyed object so it truncates like the other lists and has no `__proto__`-key hazard.
      */
     hints?: AddressHintV1[];
+    /**
+     * Fingerprint of the content a receiver acts on — the id lists, the sample's ids, `metadata`,
+     * `hints` (see `snapshotDigest` in `service/near-exchange.ts`). A receiver that merged this
+     * snapshot caches the digest and skips its next fetch while the sender's ping replies carry the
+     * same one. Optional and unversioned like `hints`: absent means "unknown, fetch as before".
+     */
+    digest?: string;
 }
 export interface RouteAndMaybeActV1 {
     v: 1;

package/dist/src/rpc/ping.d.ts

@@ -1,5 +1,6 @@
 import type { Libp2p } from 'libp2p';
 import type { StreamCaps } from './protocols.js';
+import { type RpcRequestOptions } from './request.js';
 import type { RpcOutcome } from './outcome.js';
 import type { BusyResponseV1 } from '../index.js';
 export interface PingResponseV1 {
@@ -7,26 +8,33 @@ export interface PingResponseV1 {
     ts: number;
     size_estimate?: number;
     confidence?: number;
+    /**
+     * The responder's current `NeighborSnapshotV1.digest`, so a neighbour that already merged that
+     * content can skip its snapshot fetch. Optional, no version bump: an older responder omits it
+     * and the sender fetches as before.
+     */
+    snapshot_digest?: string;
 }
-export type SizeEstimateProvider = () => {
-    size_estimate?: number;
-    confidence?: number;
-} | BusyResponseV1 | Promise<{
-    size_estimate?: number;
-    confidence?: number;
-} | BusyResponseV1>;
-export declare function registerPing(node: Libp2p, protocol?: string, getSizeEstimate?: SizeEstimateProvider, onInbound?: (from: string) => void, streamCaps?: StreamCaps): Promise<void>;
+/** The optional fields a responder adds to its pong — see {@link PingResponseV1}. */
+export type PingReplyExtras = Pick<PingResponseV1, 'size_estimate' | 'confidence' | 'snapshot_digest'>;
+/** Supplies {@link PingReplyExtras} per inbound ping, or a busy refusal in place of the pong. */
+export type PingReplyProvider = () => PingReplyExtras | BusyResponseV1 | Promise<PingReplyExtras | BusyResponseV1>;
+export declare function registerPing(node: Libp2p, protocol?: string, getReplyExtras?: PingReplyProvider, onInbound?: (from: string) => void, streamCaps?: StreamCaps): Promise<void>;
 /**
  * Ping `peer` over this network's namespaced protocol. Read-only request (the handler replies
- * without reading); dial 'always'. `ok.value.ok` is the peer's own pong flag; rttMs on the
- * outcome. Truncation/undecodable replies are `decode-error` — the service scores them as
- * proof of life.
+ * without reading). `dial` defaults to `'always'`; the service's maintenance passes pass
+ * `'never'`, because opening a connection is the redial seam's job under its own budget and a
+ * 2 s ping budget cannot cover a dial on a slow link. `ok.value.ok` is the peer's own pong flag;
+ * rttMs on the outcome. Truncation/undecodable replies are `decode-error` — the service scores
+ * them as proof of life.
  */
 export declare function sendPing(node: Libp2p, peer: string, protocol?: string, opts?: {
     signal?: AbortSignal;
     timeoutMs?: number;
+    dial?: RpcRequestOptions<unknown>['dial'];
 }): Promise<RpcOutcome<{
     ok: boolean;
     size_estimate?: number;
     confidence?: number;
+    snapshot_digest?: string;
 }>>;

package/dist/src/rpc/ping.js

@@ -3,7 +3,7 @@ import { rpcRequest } from './request.js';
 import { parseOrThrow, parsePingResponse } from './validate.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('rpc:ping');
-export async function registerPing(node, protocol = PROTOCOL_PING, getSizeEstimate, onInbound, 
+export async function registerPing(node, protocol = PROTOCOL_PING, getReplyExtras, onInbound, 
 // Trailing and optional so existing positional callers keep compiling. Forwarded verbatim to
 // `node.handle`; omitting it leaves libp2p's own per-connection defaults.
 streamCaps = {}) {
@@ -17,51 +17,57 @@ streamCaps = {}) {
         ...streamCaps,
         serve: (connection) => {
             onInbound?.(connection.remotePeer.toString());
-            return pingReply(getSizeEstimate);
+            return pingReply(getReplyExtras);
         },
     });
 }
 /**
- * The body of a ping answer. Split out so the estimate's `try` covers the *provider* alone: while
+ * The body of a ping answer. Split out so the provider's `try` covers the *provider* alone: while
  * it also wrapped the send-and-close tail, a stream that failed mid-reply was logged as a failed
- * estimate and then answered a second time on the same broken stream.
+ * provider and then answered a second time on the same broken stream.
  *
- * A failed estimate is not a failed ping — it degrades to a plain pong.
+ * A failed provider is not a failed ping — it degrades to a plain pong.
  */
-async function pingReply(getSizeEstimate) {
-    // Busy test on the size-estimate *provider's return* — an in-process value, not a wire reply,
-    // so this is not a copy of `rpcRequest`'s busy classification.
+async function pingReply(getReplyExtras) {
+    // Busy test on the *provider's return* — an in-process value, not a wire reply, so this is not
+    // a copy of `rpcRequest`'s busy classification.
     const isBusy = (res) => typeof res === 'object' && res !== null && 'busy' in res && res.busy === true;
     const pong = () => ({ ok: true, ts: Date.now() });
-    if (!getSizeEstimate)
+    if (!getReplyExtras)
         return pong();
-    let sizeInfo;
+    let extras;
     try {
-        sizeInfo = await getSizeEstimate();
+        extras = await getReplyExtras();
     }
     catch (err) {
-        log.error('getSizeEstimate failed - %e', err);
+        log.error('ping reply provider failed - %e', err);
         return pong();
     }
-    if (isBusy(sizeInfo))
-        return sizeInfo;
+    if (isBusy(extras))
+        return extras;
     const response = pong();
-    if (sizeInfo.size_estimate !== undefined) {
-        response.size_estimate = sizeInfo.size_estimate;
-        response.confidence = sizeInfo.confidence;
+    if (extras.size_estimate !== undefined) {
+        response.size_estimate = extras.size_estimate;
+        response.confidence = extras.confidence;
     }
+    if (extras.snapshot_digest !== undefined)
+        response.snapshot_digest = extras.snapshot_digest;
     return response;
 }
 /**
  * Ping `peer` over this network's namespaced protocol. Read-only request (the handler replies
- * without reading); dial 'always'. `ok.value.ok` is the peer's own pong flag; rttMs on the
- * outcome. Truncation/undecodable replies are `decode-error` — the service scores them as
- * proof of life.
+ * without reading). `dial` defaults to `'always'`; the service's maintenance passes pass
+ * `'never'`, because opening a connection is the redial seam's job under its own budget and a
+ * 2 s ping budget cannot cover a dial on a slow link. `ok.value.ok` is the peer's own pong flag;
+ * rttMs on the outcome. Truncation/undecodable replies are `decode-error` — the service scores
+ * them as proof of life.
  */
 export async function sendPing(node, peer, protocol = PROTOCOL_PING, opts = {}) {
     return rpcRequest(node, peer, protocol, {
         ...opts,
-        maxBytes: 1024, // ping reply is tiny, fixed-shape ({ok, size_estimate?, confidence?}); ample headroom
+        // A ping reply is tiny and fixed-shape ({ok, ts, size_estimate?, confidence?,
+        // snapshot_digest?}) — ~140 bytes at its worst against this cap.
+        maxBytes: 1024,
         // The parser replaces the old `Boolean(r.ok)` coercion: a legal value always encodes as a
         // boolean, so the coercion could only ever have hidden a malformed peer. A rejection
         // throws (see `parseOrThrow`) and surfaces as `decode-error` — proof of life, never a

package/dist/src/rpc/validate.d.ts

@@ -48,16 +48,17 @@ export declare const MAYBE_ACT_OVERHEAD_BYTES: number;
  * `FretService.snapshot` produces (53-char peer ids, a 32-byte base64url coordinate per sample
  * entry, `metadata` grown until `JSON.stringify(metadata)` hits
  * {@link MAX_SNAPSHOT_METADATA_BYTES_CORE} exactly, 256 bytes reserved for the still-empty `sig`
- * field, and a `hints` array packed to {@link MAX_SNAPSHOT_HINT_BYTES_CORE}):
+ * field, a `digest` at the parser's 64-character cap, and a `hints` array packed to
+ * {@link MAX_SNAPSHOT_HINT_BYTES_CORE}):
  *
  *   16 successors + 16 predecessors + 8 sample entries (the *merge* caps, which are wider than
- *   today's emission caps of 12/12/8)  ....................................  3,371 bytes
+ *   today's emission caps of 12/12/8), plus the 64-char digest  .............  3,447 bytes
  *   + 8 KiB metadata (including the `,"metadata":` key)  ..................  8,204 bytes
- *   = 11,575 bytes of fixed fields
+ *   = 11,651 bytes of fixed fields
  *   + 48 KiB of hints (the whole array, plus its `,"hints":[]` framing)  ....  49,163 bytes
- *   = 60,738 bytes
+ *   = 60,814 bytes
  *
- * 64 KiB leaves ~4.7 KiB of headroom over that. Sereus used the same 64 KiB for the same payload.
+ * 64 KiB leaves ~4.6 KiB of headroom over that. Sereus used the same 64 KiB for the same payload.
  *
  * The invariant this constant carries, pinned by `test/rpc.codec-properties.spec.ts`: **the
  * largest legal emission of *any* profile — fixed fields, metadata allowance and hint budget
@@ -69,12 +70,12 @@ export declare const MAX_NEIGHBORS_BYTES: number;
  *  application metadata it will carry — not an acceptance limit; acceptance is
  *  {@link MAX_NEIGHBORS_BYTES}, one network-wide number. The invariant the emission budgets must
  *  keep is `largest emission of any profile <= MAX_NEIGHBORS_BYTES`: at the merge caps the Core
- *  fixed fields cost 3,371 bytes, so this allowance plus them lands at 11,575, and the hint budget
- *  ({@link MAX_SNAPSHOT_HINT_BYTES_CORE}) on top of that at 60,738 — under. Over-cap metadata is
+ *  fixed fields cost 3,447 bytes, so this allowance plus them lands at 11,651, and the hint budget
+ *  ({@link MAX_SNAPSHOT_HINT_BYTES_CORE}) on top of that at 60,814 — under. Over-cap metadata is
  *  omitted from the snapshot rather than truncated — see `FretService.snapshot`. */
 export declare const MAX_SNAPSHOT_METADATA_BYTES_CORE: number;
 /** Same, Edge profile: an emission budget, half of Core's because an edge node carries less.
- *  Its worst legal emission is 6,301 bytes of fixed fields plus {@link MAX_SNAPSHOT_HINT_BYTES_EDGE}
+ *  Its worst legal emission is 6,377 bytes of fixed fields plus {@link MAX_SNAPSHOT_HINT_BYTES_EDGE}
  *  of hints, also under {@link MAX_NEIGHBORS_BYTES} — which is the only bound any budget has to
  *  satisfy. Deliberately *not* sized against a per-profile acceptance cap; there is no such thing. */
 export declare const MAX_SNAPSHOT_METADATA_BYTES_EDGE: number;
@@ -86,15 +87,22 @@ export declare const MAX_SNAPSHOT_METADATA_BYTES_EDGE: number;
  * `SelfAddressRecord` omits its own record rather than emit one the receiver would drop.
  */
 export declare const MAX_ADDRESS_RECORD_CHARS = 2048;
+/**
+ * Longest snapshot digest a parser keeps (`NeighborSnapshotV1.digest`,
+ * `PingResponseV1.snapshot_digest`). Wider than the 22 characters `snapshotDigest`
+ * (`service/near-exchange.ts`) emits so a longer digest can be introduced later without a parser
+ * change; a receiver compares digests for equality only, so the width never matters to it.
+ */
+export declare const MAX_SNAPSHOT_DIGEST_CHARS = 64;
 /**
  * Emission budget for the whole `hints` array of a Core snapshot — the sum over hints of
  * `JSON.stringify(hint).length + 1` (the `+ 1` is the separating comma), which is what
  * `FretService.snapshot` counts. Profile-split like the metadata allowance, and for the same
  * reason: it is this node's own choice of how much it forwards, not a limit on what it accepts.
- * Worst case: 11,575 (fixed fields) + 49,152 + the field's own framing < {@link MAX_NEIGHBORS_BYTES}.
+ * Worst case: 11,651 (fixed fields) + 49,152 + the field's own framing < {@link MAX_NEIGHBORS_BYTES}.
  */
 export declare const MAX_SNAPSHOT_HINT_BYTES_CORE: number;
-/** Same, Edge profile: an edge node forwards less. 6,301 + 16,384 + framing is far under the cap. */
+/** Same, Edge profile: an edge node forwards less. 6,377 + 16,384 + framing is far under the cap. */
 export declare const MAX_SNAPSHOT_HINT_BYTES_EDGE: number;
 /**
  * Structural validity of an inbound `RouteAndMaybeAct` — everything downstream code touches
@@ -182,6 +190,7 @@ export declare const parsePingResponse: Parser<{
     ok: boolean;
     size_estimate?: number;
     confidence?: number;
+    snapshot_digest?: string;
 }>;
 /**
  * A NearAnchor reply. The two id lists are hints, so they truncate and drop bad entries; missing

package/dist/src/rpc/validate.js

@@ -78,16 +78,17 @@ export const MAYBE_ACT_OVERHEAD_BYTES = 16 * 1024;
  * `FretService.snapshot` produces (53-char peer ids, a 32-byte base64url coordinate per sample
  * entry, `metadata` grown until `JSON.stringify(metadata)` hits
  * {@link MAX_SNAPSHOT_METADATA_BYTES_CORE} exactly, 256 bytes reserved for the still-empty `sig`
- * field, and a `hints` array packed to {@link MAX_SNAPSHOT_HINT_BYTES_CORE}):
+ * field, a `digest` at the parser's 64-character cap, and a `hints` array packed to
+ * {@link MAX_SNAPSHOT_HINT_BYTES_CORE}):
  *
  *   16 successors + 16 predecessors + 8 sample entries (the *merge* caps, which are wider than
- *   today's emission caps of 12/12/8)  ....................................  3,371 bytes
+ *   today's emission caps of 12/12/8), plus the 64-char digest  .............  3,447 bytes
  *   + 8 KiB metadata (including the `,"metadata":` key)  ..................  8,204 bytes
- *   = 11,575 bytes of fixed fields
+ *   = 11,651 bytes of fixed fields
  *   + 48 KiB of hints (the whole array, plus its `,"hints":[]` framing)  ....  49,163 bytes
- *   = 60,738 bytes
+ *   = 60,814 bytes
  *
- * 64 KiB leaves ~4.7 KiB of headroom over that. Sereus used the same 64 KiB for the same payload.
+ * 64 KiB leaves ~4.6 KiB of headroom over that. Sereus used the same 64 KiB for the same payload.
  *
  * The invariant this constant carries, pinned by `test/rpc.codec-properties.spec.ts`: **the
  * largest legal emission of *any* profile — fixed fields, metadata allowance and hint budget
@@ -99,12 +100,12 @@ export const MAX_NEIGHBORS_BYTES = 64 * 1024;
  *  application metadata it will carry — not an acceptance limit; acceptance is
  *  {@link MAX_NEIGHBORS_BYTES}, one network-wide number. The invariant the emission budgets must
  *  keep is `largest emission of any profile <= MAX_NEIGHBORS_BYTES`: at the merge caps the Core
- *  fixed fields cost 3,371 bytes, so this allowance plus them lands at 11,575, and the hint budget
- *  ({@link MAX_SNAPSHOT_HINT_BYTES_CORE}) on top of that at 60,738 — under. Over-cap metadata is
+ *  fixed fields cost 3,447 bytes, so this allowance plus them lands at 11,651, and the hint budget
+ *  ({@link MAX_SNAPSHOT_HINT_BYTES_CORE}) on top of that at 60,814 — under. Over-cap metadata is
  *  omitted from the snapshot rather than truncated — see `FretService.snapshot`. */
 export const MAX_SNAPSHOT_METADATA_BYTES_CORE = 8 * 1024;
 /** Same, Edge profile: an emission budget, half of Core's because an edge node carries less.
- *  Its worst legal emission is 6,301 bytes of fixed fields plus {@link MAX_SNAPSHOT_HINT_BYTES_EDGE}
+ *  Its worst legal emission is 6,377 bytes of fixed fields plus {@link MAX_SNAPSHOT_HINT_BYTES_EDGE}
  *  of hints, also under {@link MAX_NEIGHBORS_BYTES} — which is the only bound any budget has to
  *  satisfy. Deliberately *not* sized against a per-profile acceptance cap; there is no such thing. */
 export const MAX_SNAPSHOT_METADATA_BYTES_EDGE = 4 * 1024;
@@ -116,15 +117,22 @@ export const MAX_SNAPSHOT_METADATA_BYTES_EDGE = 4 * 1024;
  * `SelfAddressRecord` omits its own record rather than emit one the receiver would drop.
  */
 export const MAX_ADDRESS_RECORD_CHARS = 2048;
+/**
+ * Longest snapshot digest a parser keeps (`NeighborSnapshotV1.digest`,
+ * `PingResponseV1.snapshot_digest`). Wider than the 22 characters `snapshotDigest`
+ * (`service/near-exchange.ts`) emits so a longer digest can be introduced later without a parser
+ * change; a receiver compares digests for equality only, so the width never matters to it.
+ */
+export const MAX_SNAPSHOT_DIGEST_CHARS = 64;
 /**
  * Emission budget for the whole `hints` array of a Core snapshot — the sum over hints of
  * `JSON.stringify(hint).length + 1` (the `+ 1` is the separating comma), which is what
  * `FretService.snapshot` counts. Profile-split like the metadata allowance, and for the same
  * reason: it is this node's own choice of how much it forwards, not a limit on what it accepts.
- * Worst case: 11,575 (fixed fields) + 49,152 + the field's own framing < {@link MAX_NEIGHBORS_BYTES}.
+ * Worst case: 11,651 (fixed fields) + 49,152 + the field's own framing < {@link MAX_NEIGHBORS_BYTES}.
  */
 export const MAX_SNAPSHOT_HINT_BYTES_CORE = 48 * 1024;
-/** Same, Edge profile: an edge node forwards less. 6,301 + 16,384 + framing is far under the cap. */
+/** Same, Edge profile: an edge node forwards less. 6,377 + 16,384 + framing is far under the cap. */
 export const MAX_SNAPSHOT_HINT_BYTES_EDGE = 16 * 1024;
 /**
  * Structural validity of an inbound `RouteAndMaybeAct` — everything downstream code touches
@@ -275,10 +283,25 @@ export function makeSnapshotParser(caps) {
             delete out.hints;
         else
             out.hints = hints;
+        // Advisory like the numerics: a usable digest lets the receiver skip its next fetch, an
+        // unusable one costs it nothing but that.
+        const digest = snapshotDigestOr(msg.digest, undefined);
+        if (digest === undefined)
+            delete out.digest;
+        else
+            out.digest = digest;
         // `sig` is deliberately unchecked: message signing is unimplemented, so nothing reads it.
         return out;
     };
 }
+/**
+ * The value when it is a snapshot digest a receiver can compare — a non-empty string of at most
+ * {@link MAX_SNAPSHOT_DIGEST_CHARS} characters — else `fallback`. Width-checked only: the receiver
+ * tests equality against a digest it cached from the same peer, so no encoding rule is enforced.
+ */
+function snapshotDigestOr(value, fallback) {
+    return typeof value === 'string' && value.length > 0 && value.length <= MAX_SNAPSHOT_DIGEST_CHARS ? value : fallback;
+}
 /**
  * The address hints, vetted per entry against the snapshot's named set — see
  * {@link makeSnapshotParser}. An entry survives when it is an object whose `id` is a named id not
@@ -416,6 +439,10 @@ export const parsePingResponse = (msg) => {
     const confidence = finiteNumberInRangeOr(msg.confidence, 0, 1, undefined);
     if (confidence !== undefined)
         out.confidence = confidence;
+    // Same drop-not-reject rule as the snapshot's `digest`, which this fingerprints.
+    const snapshotDigest = snapshotDigestOr(msg.snapshot_digest, undefined);
+    if (snapshotDigest !== undefined)
+        out.snapshot_digest = snapshotDigest;
     return out;
 };
 /**