Struct FilterManager 

pub struct FilterManager { /* private fields */ }

Cuckoo filter manager for L3 existence checks.

The filter tracks which keys exist in L3 (SQL). On cache miss:

• If filter says “definitely not” AND trusted → return 404 immediately
• If filter says “maybe” → check L3
• If untrusted → always check L3 (degraded mode)

The filter must be warmed from L3 on startup and verified via merkle root comparison before being marked trusted.

Persistence

The filter supports export/import for fast startup:

• On shutdown: export() → save bytes to SQLite
• On startup: load bytes → import() → mark_trusted() → ready instantly

Implementations

impl FilterManager

pub fn new(node_id: impl Into<String>, initial_capacity: usize) -> Self

Create a new filter manager (starts untrusted).

Arguments

• node_id - Unique identifier for deterministic seeding (e.g., hostname)
• initial_capacity - Expected number of items (filter will grow if exceeded)

pub fn trust_state(&self) -> FilterTrust

Get current trust state.

pub fn is_trusted(&self) -> bool

Check if filter is trusted (convenience method).

pub fn mark_trusted(&self)

Mark filter as trusted (after warmup + verification).

pub fn mark_untrusted(&self)

Mark filter as untrusted (e.g., after detecting inconsistency).

pub fn might_exist(&self, key: &str) -> Option<bool>

Check if a key might exist in L3.

Returns:

• Some(true) → key might exist, check L3
• Some(false) → key definitely doesn’t exist (trusted mode only)
• None → filter is untrusted, must check L3

pub fn should_check_l3(&self, key: &str) -> bool

Check if we should query L3 for this key.

pub fn insert(&self, key: &str)

Insert a key into the filter (call when item is persisted to L3).

pub fn remove(&self, key: &str) -> bool

Remove a key from the filter (call when item is deleted from L3).

pub fn bulk_insert(&self, keys: &[String])

Bulk insert keys during warmup.

More efficient than individual inserts for large batches.

pub fn export(&self) -> Option<Vec<u8>>

Export filter state to bytes for persistence.

Save these bytes to SQLite on shutdown for fast startup.

pub fn import(&self, data: &[u8]) -> Result<(), String>

Import filter state from bytes.

Load bytes from SQLite on startup, then call mark_trusted().

pub fn len(&self) -> usize

Get current entry count.

pub fn is_empty(&self) -> bool

Check if filter is empty.

pub fn stats(&self) -> (usize, usize, FilterTrust)

Get filter stats: (entry_count, capacity, trust_state).

pub fn memory_usage_bytes(&self) -> usize

Estimate memory usage in bytes.

pub fn node_id(&self) -> &str

Get the node ID used for deterministic seeding.

pub fn seed(&self) -> u64

Get the deterministic seed.