Struct Deduplicator 

pub struct Deduplicator { /* private fields */ }

Deduplicates requests by key within a TTL window.

Guarantees

• Deterministic: same key always maps to the same result
• Thread-safe via Arc<Mutex<_>>
• Entries expire after ttl
• Optional max_entries cap bounds memory independently of TTL

Implementations

impl Deduplicator

pub fn new(ttl: Duration) -> Self

Create a new deduplicator with the given TTL.

pub fn with_max_entries(self, max: usize) -> Result<Self, AgentRuntimeError>

Set a hard cap on the number of cached (completed) entries.

When the cache is full the oldest entry (by insertion time) is evicted before the new entry is stored. This bounds memory growth for workloads where all request keys are unique and the TTL has not yet expired.

Returns

• Err(AgentRuntimeError::Orchestration) if max == 0

pub fn check_and_register( &self, key: &str, ) -> Result<DeduplicationResult, AgentRuntimeError>

Check whether key is new, cached, or in-flight.

Marks the key as in-flight if it is new.

pub fn check( &self, key: &str, ttl: Duration, ) -> Result<DeduplicationResult, AgentRuntimeError>

Check deduplication state for a key with a per-call TTL override.

Marks the key as in-flight if it is new. Ignores the stored TTL and uses ttl instead for expiry checks.

pub fn dedup_many( &self, requests: &[(&str, Duration)], ) -> Result<Vec<DeduplicationResult>, AgentRuntimeError>

Check deduplication state for multiple keys at once.

Returns results in the same order as requests. Each entry is (key, ttl) — same signature as check.

Acquires the internal mutex once for the entire batch, avoiding the per-key lock overhead of calling check in a loop.

pub fn complete( &self, key: &str, result: impl Into<String>, ) -> Result<(), AgentRuntimeError>

Complete a request: move from in-flight to cached with the given result.

If max_entries is configured and the cache is full, the oldest cached entry (by insertion time) is evicted before the new one is stored.

pub fn fail(&self, key: &str) -> Result<(), AgentRuntimeError>

Remove a key from in-flight tracking without caching a result.

Call this when an in-flight operation fails so that subsequent callers are not permanently blocked by a stuck InProgress entry for the full TTL.

pub fn in_flight_count(&self) -> Result<usize, AgentRuntimeError>

Return the number of keys currently in-flight (not yet completed or failed).

pub fn in_flight_keys(&self) -> Result<Vec<String>, AgentRuntimeError>

Return a snapshot of all keys currently in-flight.

pub fn cached_count(&self) -> Result<usize, AgentRuntimeError>

Return the number of keys currently in the completed result cache.

Note: expired entries are only removed lazily on the next check* call.

pub fn cached_keys(&self) -> Result<Vec<String>, AgentRuntimeError>

Return a snapshot of all keys that have cached results.

Expired entries are included (they are removed lazily). Use purge_expired first for a clean list of live keys.

pub fn ttl(&self) -> Duration

Return the configured time-to-live for cached results.

pub fn max_entries(&self) -> Option<usize>

Return the configured maximum number of cached entries, if any.

Returns None if no cap was set via with_max_entries.

pub fn is_idle(&self) -> Result<bool, AgentRuntimeError>

Return true if there are no in-flight requests.

pub fn total_count(&self) -> Result<usize, AgentRuntimeError>

Return the total number of items tracked by the deduplicator (in-flight + cached results, regardless of TTL expiry).

pub fn contains(&self, key: &str) -> Result<bool, AgentRuntimeError>

Return true if key is currently in-flight or has a cached result.

Unlike check_and_register this is a read-only inspection — it does not register the key or consume a deduplication slot.

pub fn get_result(&self, key: &str) -> Result<Option<String>, AgentRuntimeError>

Return the cached result for key if one exists and has not expired.

Returns None when the key is not in the cache (either not yet completed or already expired). Does not modify any state.

pub fn clear(&self) -> Result<(), AgentRuntimeError>

Remove all in-flight entries and cached results.

Useful for test teardown or hard resets.

pub fn purge_expired(&self) -> Result<usize, AgentRuntimeError>

Eagerly evict all cache entries whose TTL has elapsed.

Under normal operation expired entries are removed lazily on the next check* call. Call purge_expired for deterministic memory reclamation (e.g. before a cached_count snapshot or in a maintenance loop).

Returns the number of entries that were removed.

pub fn evict_oldest(&self) -> Result<bool, AgentRuntimeError>

Remove the oldest cached result entry (FIFO order).

Returns true if an entry was removed, false if the cache was empty.

Trait Implementations

impl Clone for Deduplicator

fn clone(&self) -> Deduplicator

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Deduplicator

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

Formats the value using the given formatter.