DNS interceptor cache revalidation on request errors

[SuperOleg39]

Hello!

For example, we have a dynamic network environment (Kubernetes), where IP addresses change frequently.

When DNS caching is used and a cached IP address becomes outdated, requests will fail.

Is there a way to clear the DNS cache for these requests after an error occurs? Or is this handled automatically internally?

[mcollina]

Cache entries are cleared up according to their expiration date.

Can you build a little lab to reproduce the problem?

[SuperOleg39]

Okay, I will try!

For now, I found a similar case for nginx + k8s environment - kubernetes/ingress-nginx#9652

Yes, there is a lot of information how to set a short TTL (like 5-10s) for nginx DNS resolver, and the same logic can be applied for undici and node.js.

But the problem is, that still a lot of requests can be sent on this short window, when DNS cache is already stale and not updated yet.

It often leads to 5xx spikes. Also, very short TTL's doesn't sound effective on terms of caches hit rates and DNS servers pressure.

[SuperOleg39]

Before undici we used cacheable-lookup and manually delete DNS cache on requests errors - https://github.com/tramvaijs/tramvai/blob/main/packages%2Fmodules%2Fdns-cache%2Fsrc%2Fserver.ts#L162-L170

Didn't like that it can clear cache when upstream is just broken/unresponsive by some other reason.

But maybe at undici DNS interceptor level we can do something better/smarter and working out of the box?

[pacocartones]

I built the lab @mcollina asked for, simulating the Kubernetes case: a service whose IP changes while a cached record is still valid.

Environment: Node v24.14.1, undici 8.10.0, interceptors.dns({ maxTTL: 60000, lookup: fakeLookup, affinity: 4, dualStack: false }). The fake lookup always answers with the service's current IP; a local HTTP server first listens on 127.0.0.1, then "reschedules" to 127.0.0.2 (same port).

Result — the failure is real, and the cache is not revalidated on connection errors:

=== default storage, no eviction ===
1) first request (cold cache): OK 200 "hello from 127.0.0.1"
   lookups so far: 1
2) after "pod reschedule" (cached IP dead, DNS fresh):
   attempt 1: FAIL ECONNREFUSED
   attempt 2: FAIL ECONNREFUSED
   attempt 3: FAIL ECONNREFUSED
   total lookups: 1        <- no re-lookup happens

So, to answer the question directly: no, this is not handled automatically (as of 8.10.0). Reading lib/interceptor/dns.js:

• Cached records live until their per-record TTL (max(record.ttl, ...), capped by maxTTL, default 10 s). Expiry is only checked lazily inside pick().
• onResponseError handles ECONNREFUSED/ETIMEDOUT by retrying once against the other IP family (dual-stack fallback). With a single-family (IPv4-only) setup there is no other family to try, so the error propagates and the stale record stays cached until TTL.
• Only ENOTFOUND triggers deleteRecords() — i.e. the cache is invalidated when the hostname stops resolving, not when a cached IP stops answering.

A workaround that works today — the interceptor accepts a custom storage object ({ get, set, full, delete }). If you keep a reference to it, your retry wrapper can evict the entry on connection errors:

const records = new Map()
const storage = {
  get: (k) => records.get(k) ?? null,
  set: (k, v) => records.set(k, v),
  delete: (k) => records.delete(k),
  full: () => false
}
const dispatcher = new Agent().compose(
  interceptors.dns({ maxTTL: 60_000, storage })
)
// on ECONNREFUSED/ETIMEDOUT: storage.delete(host); then retry

Verified with the same lab — eviction + retry recovers immediately instead of waiting out the TTL:

=== custom storage + delete on error ===
1) first request (cold cache): OK 200 "hello from 127.0.0.1"
2) after "pod reschedule":
   attempt 1: FAIL ECONNREFUSED -> storage.delete(host); retry: OK 200 "hello from 127.0.0.2"
   attempt 2: OK 200 "hello from 127.0.0.2"
   total lookups: 2        <- fresh lookup happened

Two additional mitigations for dynamic environments: keep maxTTL low (it caps whatever TTL your lookup reports), and note that pick() already rotates through multiple cached IPs round-robin, so if your DNS returns both the old and new IP during a rollout you'd only see intermittent failures.

If there's interest, "evict the specific cached IP on ECONNREFUSED/ETIMEDOUT to that IP" (rather than only trying the other family) would make this automatic — happy to explore a PR if the maintainers think it belongs in the interceptor.