Implement DNS Caching

[stephbu]

Goal: cache responses from upstream servers respecting TTL

[stephbu]

Analysis & Implementation Plan

Current State

• Infrastructure exists but is not integrated: IDnsCache interface and DnsCache class exist using Microsoft.Extensions.Caching.Memory.MemoryCache
• Not wired up: The cache is not registered in the DI container and DnsServer does not use it
• Basic tests only: Two simple tests exist in DnsCacheTests.cs for get/set operations

Scope Decisions (per owner input)

Question	Decision
Caching scope	Upstream (recursive) responses only — authoritative zone responses are not cached
Storage strategy	Parse and store individual resource records (not raw byte packets)
Negative caching	Deferred — basic positive-response caching first; RFC 2308 negative caching as follow-up
Configuration	Yes — max size limits, min/max TTL overrides, and statistics for metrics
TTL decrement	Yes — cached responses must reflect elapsed time in returned TTL values

---

Implementation Tasks

1. Enhance IDnsCache Interface

public interface IDnsCache
{
    // Existing
    byte[] Get(string key);
    void Set(string key, byte[] bytes, int ttlSeconds);
    
    // New - record-based API
    CachedResponse? TryGetResponse(string name, ResourceClass @class, ResourceType type);
    void CacheResponse(string name, ResourceClass @class, ResourceType type, IEnumerable<ResourceRecord> answers, uint ttlSeconds);
    
    // Statistics
    CacheStatistics GetStatistics();
    void Clear();
}

2. Create CachedResponse and CacheStatistics Models

• CachedResponse: holds answers, cached timestamp, original TTL
• CacheStatistics: hits, misses, evictions, current entry count, hit ratio

3. Enhance DnsCache Implementation

• Add configuration options via DnsCacheOptions:
  • MaxEntries (default: 10,000)
  • MinTtlSeconds (default: 60) — floor for very short TTLs
  • MaxTtlSeconds (default: 86400) — cap for excessively long TTLs
• Implement TTL decrement: effectiveTtl = originalTtl - (now - cachedAt)
• Track hit/miss statistics with thread-safe counters

4. Integrate Cache into DnsServer

• Inject IDnsCache via constructor
• Before upstream delegation: check cache for existing response
• On upstream response: parse and cache the answer records
• Cache key format: {name.ToLowerInvariant()}|{class}|{type}

5. Register in DI Container (Program.cs)

services.AddSingleton<IDnsCache, DnsCache>();
// or with options:
services.AddSingleton<IDnsCache>(sp => new DnsCache(new DnsCacheOptions { MaxEntries = 10000 }));

6. Expose Statistics via HTTP Endpoint

• Add /dump/cache or /metrics/cache endpoint returning JSON statistics

7. Expand Test Coverage

• Unit tests for TTL decrement logic
• Unit tests for min/max TTL clamping
• Unit tests for cache eviction when at capacity
• Integration tests verifying cached responses have decremented TTLs
• Statistics accuracy tests

---

Files to Modify/Create

File	Action
Dns/Contracts/IDnsCache.cs	Extend interface
Dns/DnsCache.cs	Implement new methods, add options, stats
Dns/Config/DnsCacheOptions.cs	Create — configuration model
Dns/CachedResponse.cs	Create — cached entry model
Dns/CacheStatistics.cs	Create — stats model
Dns/DnsServer.cs	Inject cache, add lookup/store logic
Dns/Program.cs	Register cache in DI
Dns/appsettings.json	Add cache configuration section
dnstest/DnsCacheTests.cs	Expand test coverage

---

Acceptance Criteria

• Upstream DNS responses are cached with TTL respected
• Cached responses return decremented TTLs based on cache age
• TTLs are clamped to configured min/max bounds
• Cache respects maximum entry limit with LRU-style eviction
• Cache statistics are exposed (hits, misses, hit ratio, entry count)
• HTTP endpoint exposes cache statistics
• Unit tests cover all new functionality
• Integration test confirms cache behavior end-to-end

Future Work (Out of Scope for This Issue)

• RFC 2308 negative caching (NXDOMAIN/NODATA)
• Cache persistence across restarts
• Cache warming from zone providers