Shared packages

Active contributors: miekg, chrisohaver, johnbelamaric, yongtang, stp-ip

Purpose

Plugins and the server share a pool of utility packages under plugin/pkg/. They cover what every DNS server needs — caches, parsers, DNS helpers, logging, listeners, expression evaluation, transports — without forcing each plugin to copy them.

Directory layout

plugin/pkg/
├── cache/         # Generic sharded LRU/LFU cache
├── cidr/          # CIDR helpers
├── dnstest/       # Test helpers: Recorder, Multiplexer
├── dnsutil/       # MinimalTTL, Dedup, Join, ToRR, ParseHostPortOrFile, ...
├── doh/           # DoH request/response codecs (RFC 8484)
├── durations/     # Parse comma-separated time.Duration lists
├── edns/          # EDNS0 helpers: Size, Version, Code/option metadata
├── expression/    # CEL-like expression evaluator (used by view, rewrite)
├── fall/          # Fallthrough zone-list parsing
├── fuzz/          # Shared fuzz helpers
├── log/           # Plugin-aware logger with debug toggle
├── nonwriter/     # ResponseWriter that buffers
├── parse/         # Parsing helpers (Transport, HostPort, file paths)
├── proxy/         # Forwarder / connection cache used by forward and grpc
├── proxyproto/    # PROXY protocol UDP/TCP wrappers
├── rand/          # Seeded random helpers
├── rcode/         # ToString/FromString for rcodes
├── replacer/      # Variable substitution ({remote}, {>id}, ...) used by log
├── response/      # Reply classification (Type)
├── reuseport/     # SO_REUSEPORT listeners
├── singleflight/  # Generic single-flight for backend lookups
├── tls/           # TLS config builder
├── trace/         # Trace plugin interface
├── transport/     # Scheme strings and default ports
├── uniq/          # Deduper for sequences
├── up/            # Periodic uptime probes (used by forward health checks)
└── upstream/      # Upstream resolver interface for plugins like dnssec, file

What plugins use most

A few of these packages are pulled into nearly every plugin. The rest exist for specific use cases.

plugin/pkg/log

The standard logger. Plugins instantiate log := clog.NewWithPlugin("name") so output is prefixed with [INFO] plugin/name:. Levels are Info, Warning, Error, Debug (each with *f variants). Debug output requires the debug plugin, which calls log.D.Set() to flip the global toggle. The package also exposes log.Fatal and a no-op writer used during tests.

plugin/pkg/parse

Helpers for Caddyfile syntax and addresses:

• parse.Transport(s) strips and returns one of dns, tls, https, https3, quic, grpc. Used by dnsContext.InspectServerBlocks and by forward/grpc when parsing TO arguments.
• parse.HostPortOrFile(args ...) resolves command-line entries that may be either IP:port or paths to resolv.conf-format files.
• parse.Stanza and helpers for nested directive parsing.

plugin/pkg/dnsutil

DNS-message helpers used everywhere: MinimalTTL (compute the smallest TTL in a message), MaximumDefaultTTL, MinimalDefaultTTL, Dedup (drop duplicate RRs), Join (zip together answer/authority/additional sections), ParseHostPortOrFile, address parsing, and EDNS0 option lookup.

plugin/pkg/cache

A sharded cache used by plugin/cache, dnssec, forward, grpc, and others. Implementation: 256 shards, each with an LRU list and per-key TTLs. Generic on the value type since Go 1.18.

plugin/pkg/proxy

Connection cache and forwarding logic shared between plugin/forward and plugin/grpc. Defines Proxy, Connect, Healthcheck, options like ForceTCP, PreferUDP, HCRecursionDesired. Both plugins create proxies, hand them to the package's connection cache, and reuse sockets across queries.

plugin/pkg/up

Tiny periodic probe scheduler. up.New(interval, fn) runs fn every interval and exposes a Healthy() flag. Used by forward and health for upstream/downstream liveness.

plugin/pkg/replacer

Variable substitution against a request.Request. The log, errors, and metadata plugins use this to expand placeholders like {remote}, {>id}, {type}, {rcode}, {>do}, {port}, {name} etc. Custom placeholders can be registered. The same engine powers metadata's lazy values.

plugin/pkg/expression

A CEL-like expression evaluator used by the view plugin (filter expressions on incoming requests) and by rewrite for conditional rules. Built on github.com/expr-lang/expr.

plugin/pkg/reuseport

Wraps net.Listen and net.ListenPacket with SO_REUSEPORT (Linux) so a graceful reload can hand sockets between processes and the multisocket plugin can spin up multiple listeners on the same port.

plugin/pkg/transport

Constants only: scheme strings (DNS, TLS, HTTPS, etc.) and default ports.

plugin/pkg/response

response.Typify(msg, now) and response.Type — the reply classification used by cache and dnssec to decide what to cache or sign.

plugin/pkg/dnstest

Test infrastructure: dnstest.NewRecorder to capture replies, dnstest.Multiplexer to run mock servers, dnstest.Server for in-memory DNS exchanges. Used in *_test.go across the tree.

plugin/pkg/upstream

The Upstream interface is what plugins like dnssec, file, template, and auto use to resolve names that aren't in their own zone (e.g. CNAME targets). Default implementation forwards back through the plugin chain.

plugin/pkg/proxyproto

UDP and TCP PROXY protocol v1/v2 listener wrappers. The TCP wrapper is pires/go-proxyproto.Listener; the UDP wrapper (cproxyproto.PacketConn) is custom and includes Cloudflare Spectrum session tracking.

plugin/pkg/doh

Encodes/decodes DoH requests (RequestToMsgWire, ResponseToMsg) and the Path constant /dns-query. core/dnsserver/server_https.go consumes these.

Smaller helpers

Package	Notes
plugin/pkg/cidr	CIDR-to-reverse-zone expansion (Class, Reverse)
plugin/pkg/durations	Parses lists like "5s,10s" into []time.Duration
plugin/pkg/edns	EDNS0 option lookups, version checks, code metadata
plugin/pkg/fall	Parses fallthrough [zones...] and matches names against the list
plugin/pkg/nonwriter	A ResponseWriter whose WriteMsg only stores the message
plugin/pkg/rand	Seeded random helpers used by forward policies
plugin/pkg/rcode	ToString/FromString for DNS rcodes (used by metrics)
plugin/pkg/tls	Build a *tls.Config from cert/key/CA arguments
plugin/pkg/trace	Interface implemented by the trace plugin
plugin/pkg/uniq	Deduplicate strings while preserving order
plugin/pkg/singleflight	Generic single-flight for backend lookups
plugin/pkg/fuzz	Helpers shared by */fuzz.go harnesses

Key abstractions

Symbol	File	Description
clog.NewWithPlugin	plugin/pkg/log/log.go	Plugin-aware logger
cache.New[T]	plugin/pkg/cache/cache.go	Sharded cache constructor
parse.Transport	plugin/pkg/parse/parse.go	Strip and identify transport scheme
dnsutil.MinimalTTL	plugin/pkg/dnsutil/ttl.go	Lowest TTL in a message
proxy.Proxy.Connect	plugin/pkg/proxy/proxy.go	Connect (and reuse) a connection to an upstream
up.New	plugin/pkg/up/up.go	Periodic probe scheduler
replacer.New	plugin/pkg/replacer/replacer.go	Variable substitution against a request
expression.Eval	plugin/pkg/expression/expression.go	CEL-like expression evaluator
reuseport.Listen	plugin/pkg/reuseport/reuseport.go	SO_REUSEPORT wrappers
response.Typify	plugin/pkg/response/typify.go	Classify a reply

Integration points

• Server: uses parse, transport, reuseport, proxyproto, doh, dnsutil, response, edns.
• Plugins: practically every plugin imports plugin/pkg/log. Forward/grpc/cache/dnssec lean on pkg/cache, pkg/proxy, pkg/up, pkg/upstream. view and rewrite use pkg/expression.
• Tests: pkg/dnstest, pkg/nonwriter, pkg/fuzz.

Entry points for modification

• Anything reusable across two or more plugins → put it in plugin/pkg/<name>/ rather than duplicating.
• Test helpers → plugin/pkg/dnstest/.
• Listener/socket-level changes → plugin/pkg/reuseport, plugin/pkg/proxyproto.
• New shared parser → plugin/pkg/parse.