pub struct DnsCache { /* private fields */ }Expand description
A DNS resolution cache with TTL support and negative caching.
This cache stores resolved DNS entries and avoids repeated lookups for the same hostname within the TTL window. It also implements negative caching for failed lookups to prevent retry storms.
§Thread Safety
For use in async contexts, wrap with tokio::sync::Mutex.
Instances should be created during engine initialization and passed
down via dependency injection rather than using global singletons.
Implementations§
Source§impl DnsCache
impl DnsCache
Sourcepub fn new() -> Self
pub fn new() -> Self
Create a new DNS cache with default settings.
Default values:
- TTL: 300 seconds (5 minutes)
- Negative TTL: 60 seconds (1 minute)
- IPv4 preference: enabled
Sourcepub fn with_ttl(default_ttl_secs: u64, negative_ttl_secs: u64) -> Self
pub fn with_ttl(default_ttl_secs: u64, negative_ttl_secs: u64) -> Self
Create a new DNS cache with custom TTL values.
§Arguments
default_ttl_secs- Time-to-live for successful resolutions (in seconds)negative_ttl_secs- Time-to-live for failed lookups (in seconds)
Sourcepub fn with_resolver(self, resolver: TokioAsyncResolver) -> Self
pub fn with_resolver(self, resolver: TokioAsyncResolver) -> Self
Inject a custom hickory resolver (useful for testing with a configured/mock resolver).
This replaces the default resolver built during construction. The TTL settings and IPv4 preference are preserved.
Sourcepub async fn resolve(
&mut self,
hostname: &str,
port: u16,
) -> Result<Vec<SocketAddr>, String>
pub async fn resolve( &mut self, hostname: &str, port: u16, ) -> Result<Vec<SocketAddr>, String>
Resolve a hostname to socket addresses, using cache if valid.
Resolution strategy:
- Check positive cache — return immediately if entry exists and is not expired
- Check negative cache — return error if lookup recently failed
- Try the fully-async hickory resolver (no blocking getaddrinfo); on success the
record TTL is capped at
default_ttland the result is cached - If hickory is unavailable or errors, fall back to
tokio::net::lookup_host(blocking getaddrinfo on a tokio thread pool) so behavior stays robust - On success: sort addresses by IPv4 preference, cache result, return
- On failure: record in negative cache, return error
§Arguments
hostname- The hostname to resolve (e.g., “example.com”)port- The port number to include in resolved addresses
§Returns
A vector of resolved SocketAddr on success, or an error string on failure.
Sourcepub async fn force_refresh(
&mut self,
hostname: &str,
port: u16,
) -> Result<Vec<SocketAddr>, String>
pub async fn force_refresh( &mut self, hostname: &str, port: u16, ) -> Result<Vec<SocketAddr>, String>
Force refresh a specific hostname, bypassing any cached entry.
This removes any existing cache entry for the hostname and performs a fresh DNS resolution. Useful when you know the DNS records may have changed.
§Arguments
hostname- The hostname to re-resolveport- The port number for resolved addresses
Sourcepub fn purge_expired(&mut self) -> usize
pub fn purge_expired(&mut self) -> usize
Remove expired entries from the cache.
Call this periodically (e.g., every few minutes) to reclaim memory from stale entries. Also cleans up expired negative cache entries.
§Returns
The number of entries that were removed.
Sourcepub fn set_ipv4_preference(&mut self, prefer_ipv4: bool)
pub fn set_ipv4_preference(&mut self, prefer_ipv4: bool)
Set whether IPv4 addresses should be preferred over IPv6.
When enabled, resolved addresses are sorted with IPv4 addresses first. This matches the behavior of C++ aria2 which prefers IPv4 by default.
Sourcepub fn default_ttl(&self) -> Duration
pub fn default_ttl(&self) -> Duration
Get the default TTL setting.
Sourcepub fn negative_ttl(&self) -> Duration
pub fn negative_ttl(&self) -> Duration
Get the negative TTL setting.
Sourcepub fn record_failure(&mut self, hostname: &str)
pub fn record_failure(&mut self, hostname: &str)
Manually record a failed lookup in the negative cache.
This is useful for testing negative cache behavior without depending on network DNS resolution.
Sourcepub fn resolve_no_network(
&mut self,
hostname: &str,
port: u16,
) -> Result<Vec<SocketAddr>, String>
pub fn resolve_no_network( &mut self, hostname: &str, port: u16, ) -> Result<Vec<SocketAddr>, String>
Check cache only (no network resolution).
Returns cached addresses if available, or an error if the entry is in the negative cache or not cached at all. This is useful for testing cache behavior without network dependencies.