Struct NegativeProbeCache 

pub struct NegativeProbeCache { /* private fields */ }

Bounded LRU cache of (NodeId, hash) pairs returned has_blob: false within the TTL window.

Implementations

impl NegativeProbeCache

pub fn new() -> Self

Build a cache with the ADR 001 § Probe cache defaults (1024 entries, 5- minute TTL).

pub fn with_capacity_and_ttl(cap: usize, ttl: Duration) -> Self

Build a cache with an explicit capacity and TTL.

Production code uses Self::new (the ADR 001 § Probe cache 1024-entry, 5-minute defaults); this constructor is the test / tuning seam. The TTL is anchored on std::time::Instant, so tokio::time pause / advance has no effect on it, and a short injected TTL is how a test exercises expiry without a multi-minute wall-clock wait. Two kinds of test want that:

• One whose subject is TTL SEMANTICS — that expiry sweeps on read, that a read-hit does not re-stamp the window, that a re-record does. This module’s own unit tests are those, and their wall-clock sleeps are the measurement, not overhead.
• One whose subject is the CACHE-WIDE TTL as a quantity. node_origin’s refusal suite is that case: it shrinks the cache TTL below node_origin::REFUSAL_SUPPRESSION_TTL to invert the production order, which is the only arrangement in which the two suppression arms have visibly different lifetimes.

A test that needs one ENTRY expired as a precondition — rather than as its subject — wants neither. Entries hold an absolute expiry, so Self::record_failure_with_ttl with Duration::ZERO stamps an already-elapsed expiry on a single key, Self::contains_active sweeps it on the next read, and the rest of the cache keeps production behaviour.

cap is clamped to ≥ 1.

pub fn contains_active(&self, node_id: &NodeId, hash: &Hash) -> bool

Filter 3 (ADR 022 § Lookup integrity): returns true iff (node_id, hash) is in the cache and its TTL hasn’t elapsed. A live hit bumps the entry to the front of the LRU ordering (index 0) without refreshing the entry’s expiry — TTL is anchored at insertion per ADR 001 § Probe cache, not at read. An expired entry is evicted before returning false.

pub fn record_failure(&self, node_id: NodeId, hash: Hash)

Insert / refresh (node_id, hash) with now + TTL expiry, moving the entry to the front of the LRU ordering. Evicts the least-recently-used entry on cap overflow. Producer-side hook for the outbound probe client; the lookup module never calls this directly.

Uses the cache-wide TTL, which suits an AUTHORITATIVE negative: a probe’s has_blob: false is the peer having just looked. For a weaker signal, pass its own TTL — see Self::record_failure_with_ttl.

pub fn record_failure_with_ttl( &self, node_id: NodeId, hash: Hash, ttl: Duration, )

Self::record_failure with an explicit TTL, for a negative that is weaker than a probe’s.

Entries store an absolute expiry, so mixing TTLs is free: a short-lived entry simply falls out sooner, and Self::contains_active cannot tell the two apart (nor does it need to). The caller owns the judgement of how much its evidence is worth — see node_origin::REFUSAL_SUPPRESSION_TTL, which is far shorter because a delivery refusal, unlike a probe answer, may not be about the peer at all.

pub fn len(&self) -> usize

Current entry count. Includes expired entries that haven’t been swept yet — call Self::contains_active first if a precise live count is needed.

pub fn is_empty(&self) -> bool

Whether the cache holds zero entries (including stale).

Trait Implementations

impl Debug for NegativeProbeCache

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NegativeProbeCache

fn default() -> Self

Returns the “default value” for a type.