Struct EngineCache 

pub struct EngineCache { /* private fields */ }

Thread-safe cache of discovered SNMPv3 engine state.

Before sending authenticated SNMPv3 messages, a client must discover the target engine’s ID, boot counter, and time (RFC 3414 Section 4). This cache stores those results so that subsequent requests, or other clients sharing the same cache via Arc, skip the discovery round trip.

Entry lifetime

Each entry tracks a synced_at timestamp that is reset on every successful time update (update_time). Entries whose synced_at exceeds the configured TTL (default 5 minutes) are treated as expired: get returns None and the stale entry is removed, causing the next request to re-run discovery.

This TTL-based expiry handles device replacement (a new device with a different engine ID appearing at the same IP address). Without it, the client would hold a stale engine ID indefinitely and every request would fail with usmStatsUnknownEngineIDs. Automatic re-discovery on that Report PDU was considered but rejected because Report PDUs are unauthenticated, making it possible for a spoofed report to force re-discovery toward a rogue engine. The TTL approach avoids this: only entries that have not been refreshed by a successful authenticated exchange are expired.

Actively polled targets refresh their entry on every response, so the TTL has no effect during normal operation.

Capacity

The cache is unbounded by default. Each entry is roughly 100-150 bytes, so even 100k targets uses only ~10-15 MB. For deployments that scan very large address ranges, with_max_capacity sets a hard limit with oldest-entry eviction.

Example

use std::sync::Arc;

let cache = Arc::new(EngineCache::new());

let client1 = Client::builder("192.168.1.1:161")
    .username("admin")
    .auth(AuthProtocol::Sha1, "authpass")
    .engine_cache(cache.clone())
    .connect()
    .await?;

let client2 = Client::builder("192.168.1.2:161")
    .username("admin")
    .auth(AuthProtocol::Sha1, "authpass")
    .engine_cache(cache.clone())
    .connect()
    .await?;

Implementations

impl EngineCache

pub fn new() -> Self

Create a new empty engine cache with default settings.

pub fn with_max_capacity(self, max_capacity: usize) -> Self

Set a maximum capacity. When full, the oldest entry is evicted on insert.

pub fn with_ttl(self, ttl: Duration) -> Self

Set the TTL for cache entries. Entries not refreshed within this duration are removed on lookup, triggering re-discovery.

pub fn get(&self, target: &SocketAddr) -> Option<EngineState>

Get cached engine state for a target.

Returns None if the entry does not exist or has expired. Expired entries are removed from the cache.

pub fn insert(&self, target: SocketAddr, state: EngineState)

Store engine state for a target.

If a max capacity is set and the cache is full, the entry with the oldest synced_at time is evicted.

pub fn update_time( &self, target: &SocketAddr, response_boots: u32, response_time: u32, ) -> bool

Update time for an existing entry.

Returns true if the entry was updated, false if not found or not updated.

pub fn remove(&self, target: &SocketAddr) -> Option<EngineState>

Remove cached state for a target.

pub fn clear(&self)

Clear all cached state.

pub fn len(&self) -> usize

Get the number of cached engines (including expired entries).

pub fn is_empty(&self) -> bool

Check if the cache is empty.

Trait Implementations

impl Debug for EngineCache

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

Formats the value using the given formatter.

impl Default for EngineCache

fn default() -> Self

Returns the “default value” for a type.