cache

func (*Cache) Bytes ¶

func (c *Cache) Bytes() int64

Bytes returns the approximate memory the stored messages occupy.

Approximate is the operative word: the figure comes from this package's own estimate of each message rather than from the allocator, and it counts the stored messages, not the maps and nodes around them. It is the number Options.MaxBytes is compared against, which is what makes it the useful one to report.

It is not the resident cost, and the gap runs both ways with the shape of the traffic. Measured over two hundred thousand entries apiece: a one-A-record response is estimated at 254 bytes against about 380 of real heap once the node, the map slot and the message's own allocations are counted; an NXDOMAIN with an SOA, 303 against 380; a twenty-four record response, 2301 against 1356, the estimate now overshooting because its fixed per-record overhead outruns what a record really costs. Ordinary traffic is mostly the first case, so an operator reading this number as a memory figure should read it as about two thirds of one.

func (*Cache) Close ¶

func (c *Cache) Close() error

Close stops the sweeper, abandons any outstanding refresh, and returns once every goroutine the cache started has exited.

It is idempotent and safe to call concurrently: every caller waits for the same shutdown and none returns early. Returning before the goroutine had actually gone would make a leak test meaningless and would let a sweep run against a cache whose owner believes it is finished.

Close does not discard entries. A cache being replaced during a reload may still be read by whoever holds a reference to it; what Close ends is the background work, not the data. Use Cache.Flush for the data.

The error is always nil today. It is in the signature because Close is what callers defer, and widening a func() to a func() error afterwards would break every one of them.

func (*Cache) Flush ¶

func (c *Cache) Flush()

Flush drops every entry.

It is what an operator reaches for when the cache is known to be wrong — upstream data changed, a policy was edited, a test needs a clean slate — and it is deliberately blunt. Each shard is emptied under its own lock, so a Flush concurrent with traffic is not atomic across the cache: a lookup may still hit a shard the flush has not reached. Making it atomic would mean holding every lock at once, which is a stall on the query path in exchange for a guarantee nobody needs.

No event is published per entry. A flush is one deliberate act, and ten thousand eviction events describing it would drown every subscriber for information they already have.

func (*Cache) FlushSubtree ¶

func (c *Cache) FlushSubtree(n dnsmsg.Name) int

FlushSubtree drops the entry for n and every entry below it, and returns how many it dropped.

A subtree rather than a name, because that is the unit a change arrives in: a zone is re-signed, a delegation moves, a local override is added for a domain and everything under it must stop being answered from what the upstream said. The comparison is on canonical names, so case is irrelevant, and the root drops everything.

It walks every shard, so it is O(entries) and is not something to call per query. That is the honest cost of not maintaining a second index by name suffix, which would have to be updated under lock on every insertion in order to serve an operation that happens when configuration changes.

func (*Cache) Get ¶

func (c *Cache) Get(q dnsmsg.Question, dnssecOK bool) (*dnsmsg.Message, Result)

Get looks up the response to a question and returns a copy of it, or nil.

The returned message is always a fresh copy whose TTLs have been counted down by how long the entry has been held, per RFC 2181 section 8. The caller owns it completely and may set an ID, attach EDNS options or truncate it; the cache keeps its own.

dnssecOK is the DO bit of the query being answered and is part of the key: a response to a DO query carries signatures that a response without it does not, and serving one for the other is a validation failure rather than an inefficiency.

An entry found past its TTL is deleted here, under the lock that found it. That matters more than it looks: a name asked for exactly once would otherwise hold its slot until eviction pressure happened to reach it, which on a cache that is not full is never.

A non-nil message is not on its own permission to send one. Read Result.Status: StatusHit is an answer, while StatusStale is an answer of last resort that RFC 8767 section 5 allows only after an upstream attempt has failed. The cache cannot make that test — it has no upstream — so it returns the message and the label, and the caller that just tried the network decides. A hit on a name the cache holds an NXDOMAIN for is answered from that denial whatever type was asked, per RFC 2308 section 5, with the question section restated as the question that was asked.

func (*Cache) Len ¶

func (c *Cache) Len() int

Len returns how many entries the cache holds.

It is a single atomic load rather than a walk of the shards, so it is cheap enough to call per operation. It is also a point-in-time answer about a cache being written concurrently, which is the only kind of answer available without stopping the world.

func (*Cache) Put ¶

func (c *Cache) Put(m *dnsmsg.Message) bool

Put stores a response and reports whether it was stored.

It refuses everything Cacheable refuses, counting the Reason into Cache.Stats so that a cache which stores nothing can be diagnosed from outside. A refusal is not an error: "this response must not be cached" is a normal outcome of the protocol rather than a fault, and the caller already has the answer it needs.

The message is copied before it is stored, unconditionally. This is the single most likely correctness bug in this package, which is why the copy is not an optimisation anybody may skip: the caller keeps its own message and is entitled to reuse it — dnsmsg.Message.Reset and a pooled message are the recommended way to serve ten thousand queries a second — so an entry holding the caller's message would have its records rewritten, or zeroed, by whatever the caller did next, and the corruption would surface as a wrong answer to a different question minutes later.

func (*Cache) PutFor ¶

func (c *Cache) PutFor(q dnsmsg.Question, dnssecOK bool, m *dnsmsg.Message) bool

PutFor stores a response to the question the caller says it asked, and reports whether it was stored.

This is the insert path a resolver wants. The key is built entirely from q and dnssecOK — the question that went out and the DO bit that went with it — and the response supplies content and nothing else. A response whose own question section disagrees is refused with ReasonQuestionMismatch rather than filed under whichever key it names, because an answer to one question stored as the answer to another is what cache poisoning looks like from in here. Only the caller knows what was asked, so only the caller can close that door.

The message is copied before it is stored, unconditionally. This is the single most likely correctness bug in this package, which is why the copy is not an optimisation anybody may skip: the caller keeps its own message and is entitled to reuse it — dnsmsg.Message.Reset and a pooled message are the recommended way to serve ten thousand queries a second — so an entry holding the caller's message would have its records rewritten, or zeroed, by whatever the caller did next, and the corruption would surface as a wrong answer to a different question minutes later.

func (*Cache) Reclaimed ¶

func (c *Cache) Reclaimed() uint64

Reclaimed reports how many entries the sweeper has removed over the life of the cache.

It is the cheap answer to "is the sweeper doing anything", which is otherwise visible only through a metrics recorder that a deployment may not have configured. It is not part of Stats because it describes the maintenance goroutine rather than the cache's response to traffic, and folding the two together would make the hit rate depend on how often somebody swept.

func (*Cache) Remove ¶

func (c *Cache) Remove(k Key) bool

Remove deletes the entry for k and reports whether there was one.

It is the precise instrument that Cache.Flush is not: a name whose records have just changed can be dropped without discarding everything else the cache has learned.

It removes whatever k would have been answered from, which for a name the cache holds an NXDOMAIN for is that denial — filed under the name rather than under any one type, and so not otherwise reachable through this call. A name that has just started to exist is exactly the case Remove is reached for.

func (*Cache) SetRefresher ¶

func (c *Cache) SetRefresher(fn func(context.Context, Key))

SetRefresher registers a callback invoked when a hit lands on an entry whose remaining lifetime has fallen below Options.PrefetchThreshold, so that a popular record can be renewed before anybody misses on it.

The cache does not resolve, does not know what a resolver is, and will not learn: it reports that a key is worth refreshing, and the callback decides what that means. Milestone 6 wires this to the resolver, which re-queries the key and calls Cache.Put with what comes back.

The contract a refresher may rely on:

• fn is never called on the lookup path. It runs on its own goroutine, so a refresher that takes two seconds adds nothing to the hit that triggered it.
• fn is never called twice concurrently for one key, however many goroutines hit that key while the first call is outstanding.
• At most [maxOutstandingRefreshes] calls are outstanding at once. Past that, refreshes are declined rather than queued: a refresh that has waited in a queue is worth less than the entry it was for, and an unbounded queue of them is only a slower way to run out of memory.
• fn is handed a context that Cache.Close cancels.

Passing nil disables prefetching, which is also the default. With no refresher registered the whole path is one atomic load per hit, which is what makes it free for the deployments that do not want it. Registering one on a closed cache does nothing.

func (*Cache) StartSweeper ¶

func (c *Cache) StartSweeper(ctx context.Context, interval time.Duration) error

StartSweeper runs a sweep every interval until ctx is done or Cache.Close is called.

Expiring entries as they are looked up is not sufficient, which is the whole reason this exists. An entry is only examined when its own name is queried, so a name asked for once and never again holds its slot until eviction pressure happens to reach it — and on a cache that is not full, that is never. A cache fed by a port scan, a spam run or any other stream of one-shot names therefore fills with entries that are already dead, and then evicts live ones to make room for them. The sweeper is what makes "expired" and "gone" the same thing.

It is one Start with a matching Cache.Close rather than a Start/Stop pair. A cache owns exactly one goroutine and owns it for its whole life, so a separate Stop would only ever be called where Close already is; and a Stop that could be followed by another Start would need the full restartable lifecycle — stopped, running, closed — for a component nobody has a reason to revive. One Close, deferred next to construction, is the shape a caller gets right.

The interval is measured on the cache's clock.Clock, so a test drives the sweep with a clock.Fake instead of waiting. The ticker is registered before this returns, so a test may advance the clock immediately without racing the goroutine into existence.

StartSweeper returns ErrSweepInterval for a non-positive interval, ErrSweeperRunning if a sweeper is already running, and ErrClosed if the cache has been closed.

package main

import (
	"context"
	"fmt"
	"log"
	"net/netip"
	"runtime"
	"time"

	"github.com/daboss2003/dns/cache"
	"github.com/daboss2003/dns/clock"
	"github.com/daboss2003/dns/dnsmsg"
)

// exampleEpoch is the instant the examples start from. A recognisable, non-zero
// wall time keeps the expected output readable and avoids the year-1 underflow
// [clock.NewFake] warns about.
var exampleEpoch = time.Date(2024, time.March, 1, 12, 0, 0, 0, time.UTC)

// exampleQuestion is the question every example asks.
var exampleQuestion = dnsmsg.Question{
	Name:  dnsmsg.MustParseName("example.com."),
	Type:  dnsmsg.TypeA,
	Class: dnsmsg.ClassINET,
}

// exampleAnswer builds the response an upstream would have returned: one A
// record with the given TTL.
func exampleAnswer(ttl uint32) *dnsmsg.Message {
	return &dnsmsg.Message{
		Header:    dnsmsg.Header{Response: true, RecursionAvailable: true},
		Questions: []dnsmsg.Question{exampleQuestion},
		Answers: []dnsmsg.RR{{
			Name:  exampleQuestion.Name,
			Type:  dnsmsg.TypeA,
			Class: dnsmsg.ClassINET,
			TTL:   ttl,
			Data:  &dnsmsg.A{Addr: netip.MustParseAddr("192.0.2.1")},
		}},
	}
}

func main() {
	clk := clock.NewFake(exampleEpoch)
	c, err := cache.New(cache.Options{Clock: clk})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()

	c.Put(exampleAnswer(60))
	fmt.Println("stored:", c.Len())

	if err := c.StartSweeper(context.Background(), time.Minute); err != nil {
		log.Fatal(err)
	}

	// Two minutes later the entry has expired, and the sweeper's tick removes it
	// although nobody ever asked for it again. The sweep happens on its own
	// goroutine, so this yields until it has run rather than assuming it has;
	// nothing sleeps, and nothing depends on real time passing.
	clk.Advance(2 * time.Minute)
	for c.Reclaimed() == 0 {
		runtime.Gosched()
	}
	fmt.Println("after the sweep:", c.Len())

}

Output:
stored: 1
after the sweep: 0

func (*Cache) Stats ¶

func (c *Cache) Stats() Stats

Stats returns a snapshot of the counters.

They are read shard by shard, so the snapshot is not a single instant on a cache under load and the totals may be a few operations out of date relative to one another. Taking every lock at once to fix that would put an administrative call on the critical path of every query, which is a poor trade for a number that ends up on a dashboard.

func (*Cache) Sweep ¶

func (c *Cache) Sweep() int

Sweep removes every entry whose lifetime has run out and returns how many it reclaimed.

It is what the background sweeper calls on each tick, and is exported so that a caller who would rather drive maintenance from its own scheduler — or a test that needs the sweep to have finished before it asserts — can do so without starting a goroutine.

Sweep takes one shard lock at a time and never holds two. A cache of a million entries is therefore swept as a sequence of short pauses on individual shards rather than one long pause across all of them, so a lookup for an unrelated name waits for at most one shard and usually for nothing at all. Each shard's share of the work is bounded in turn; see [maxScanPerShard].

func (Key) Question ¶

func (k Key) Question() dnsmsg.Question

Question returns the key as a question, which is how every event and log line in the engine describes a name: the key's DNSSEC OK bit has nowhere to go in a dnsmsg.Question, and a subscriber reading one wants the form the client asked in.

The key of a cached name error carries [denialType], which is not a question anybody asked and which a dnsmsg.Question has no way to say otherwise. A subscriber seeing it is looking at the eviction of a denial that covered every type at that name; Key.String spells that out, and is the better thing to log.

func (Key) String ¶

func (k Key) String() string

String renders the key in the dig-like "name class type" order, with a +do suffix when the DNSSEC OK bit is set. It exists for log lines and cache dumps.

A key filed under [denialType] prints its type as "DENIAL" rather than as the private-use number, because an operator reading a cache dump is owed the reason the entry is there and "TYPE65280" is not it.

func (Options) Validate ¶

func (o Options) Validate() error

Validate reports every problem in o at once, joined with errors.Join.

Every problem, not the first: an operator who fixes a configuration one error per restart spends an afternoon on what should have been a single edit, and a cache misconfigured in three ways is no rarer than one misconfigured in one.

New calls Validate, so a caller who does not validate separately is not skipping it.

func (Stats) HitRate ¶

func (s Stats) HitRate() float64

HitRate reports the fraction of lookups answered from cache, between 0 and 1, and 0 for a cache nobody has asked anything.

A stale answer counts as a hit: the client got an answer without waiting for an upstream, which is what the ratio measures. Stats.StaleHits is there for anyone who needs to separate the degraded case out again.

func (Status) String ¶

func (s Status) String() string

String returns the lower-case mnemonic for the status, or a "Status(n)" form for a value outside the defined set.