Struct ArticleCache 

pub struct ArticleCache { /* private fields */ }

Article cache using LRU eviction with TTL

Uses Arc<str> (message ID content without brackets) as key for zero-allocation lookups. Arc<str> implements Borrow<str>, allowing cache.get(&str) without allocation.

Supports tier-aware TTL: entries from higher tier backends get longer TTLs. Formula: effective_ttl = base_ttl * (2 ^ tier)

Implementations

impl ArticleCache

pub fn new(max_capacity: u64, ttl: Duration) -> Self

Create a new article cache

Arguments

• max_capacity - Maximum cache size in bytes (uses weighted entries)
• ttl - Time-to-live for cached articles

pub async fn get(&self, message_id: &MessageId<'_>) -> Option<CachedArticle>

Get an article from the cache

Accepts any lifetime MessageId and uses the string content (without brackets) as key.

Zero-allocation: without_brackets() returns &str, which moka accepts directly for Arc<str> keys via the Borrow<str> trait. This avoids allocating a new Arc<str> for every cache lookup. See test_arc_str_borrow_lookup test for verification.

Tier-aware TTL: Even if moka hasn’t expired the entry yet, we check if the entry is expired based on tier-aware TTL. Higher tier entries get longer TTLs.

pub async fn upsert_ingest( &self, message_id: MessageId<'_>, buffer: impl Into<CacheIngestResponse>, backend: BackendId, tier: CacheTier, )

Upsert cache entry (insert or update) - ATOMIC OPERATION

Uses moka’s entry().and_upsert_with() for atomic get-modify-store. This eliminates the race condition of separate get() + insert() calls and provides key-level locking for concurrent operations.

If entry exists: updates the entry while preserving authoritative missing facts If entry doesn’t exist: inserts new entry

The tier is stored with the entry for tier-aware TTL calculation.

CRITICAL: Always re-insert to refresh TTL while preserving negative availability.

pub async fn record_backend_has_status( &self, message_id: MessageId<'_>, status_code: StatusCode, backend: BackendId, tier: CacheTier, )

Record successful backend availability without storing response payload bytes.

pub async fn record_backend_missing( &self, message_id: MessageId<'_>, backend_id: BackendId, )

Record that a backend returned 430 for this article - ATOMIC OPERATION

Uses moka’s entry().and_upsert_with() for atomic get-modify-store. This eliminates the race condition of separate get() + insert() calls and provides key-level locking for concurrent operations.

If the article is already cached, updates the availability bitset. If not cached, creates a typed missing cache entry. This prevents repeated queries to backends that don’t have the article.

Note: We don’t store the actual backend 430 response because:

1. We always send a standardized 430 to clients, never the backend’s response
2. The only info we need is the availability bitset (which backends returned 430)

pub fn stats(&self) -> CacheStats

Get cache statistics

pub const fn capacity(&self) -> u64

Get maximum cache capacity

pub fn entry_count(&self) -> u64

Get current number of cached entries (synchronous)

pub fn weighted_size(&self) -> u64

Get current weighted size in bytes (synchronous)

pub fn hit_rate(&self) -> f64

Get cache hit rate as percentage (0.0 to 100.0)

pub async fn sync(&self)

Run pending background tasks (for testing)

Moka performs maintenance tasks (eviction, expiration) asynchronously. This method ensures all pending tasks complete, useful for deterministic testing.

Trait Implementations

impl CacheStatsProvider for ArticleCache

fn display_stats(&self) -> CacheDisplayStats

Get statistics for TUI display

impl Clone for ArticleCache

fn clone(&self) -> ArticleCache

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ArticleCache

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

Formats the value using the given formatter.