dnscache

Documentation

Overview

Package dnscache contains a minimal DNS cache that makes a bunch of assumptions that are only valid for us. Not recommended for general use.

Index

• Variables
• func SetDebugLoggingEnabled(v bool)
• type DialContextFunc
  • func Dialer(fwd DialContextFunc, dnsCache *Resolver) DialContextFunc
  • func TLSDialer(fwd DialContextFunc, dnsCache *Resolver, tlsConfigBase *tls.Config) DialContextFunc
• type MessageCache
  • func (c *MessageCache) AddCacheEntry(qPacket, res []byte) error
  • func (c *MessageCache) Flush()
  • func (c *MessageCache) ReplyFromCache(w io.Writer, dnsQueryMessage []byte) error
  • func (c *MessageCache) SetMaxCacheSize(n int)
• type Resolver
  • func Get() *Resolver
  • func (r *Resolver) LookupIP(ctx context.Context, host string) (ip, v6 netip.Addr, allIPs []netip.Addr, err error)

Variables

var ErrCacheMiss = errors.New("cache miss")

ErrCacheMiss is a sentinel error returned by MessageCache.ReplyFromCache when the request can not be satisfied from cache.

Functions

func SetDebugLoggingEnabled

func SetDebugLoggingEnabled(v bool)

SetDebugLoggingEnabled controls whether debug logging is enabled for this package.

These logs are also printed when the TS_DEBUG_DNS_CACHE envknob is set, but we allow configuring this manually as well so that it can be changed at runtime.

Types

type DialContextFunc

type DialContextFunc func(ctx context.Context, network, address string) (net.Conn, error)

func Dialer

func Dialer(fwd DialContextFunc, dnsCache *Resolver) DialContextFunc

Dialer returns a wrapped DialContext func that uses the provided dnsCache.

func TLSDialer

func TLSDialer(fwd DialContextFunc, dnsCache *Resolver, tlsConfigBase *tls.Config) DialContextFunc

TLSDialer is like Dialer but returns a func suitable for using with net/http.Transport.DialTLSContext. It returns a *tls.Conn type on success. On TLS cert validation failure, it can invoke a backup DNS resolution strategy.

type MessageCache

type MessageCache struct {
	// Clock is a clock, for testing.
	// If nil, time.Now is used.
	Clock func() time.Time
	// contains filtered or unexported fields
}

MessageCache is a cache that works at the DNS message layer, with its cache keyed on a DNS wire-level question, and capable of replying to DNS messages.

Its zero value is ready for use with a default cache size. Use SetMaxCacheSize to specify the cache size.

It's safe for concurrent use.

func (*MessageCache) AddCacheEntry

func (c *MessageCache) AddCacheEntry(qPacket, res []byte) error

AddCacheEntry adds a cache entry to the cache. It returns an error if the entry could not be cached.

func (*MessageCache) Flush

func (c *MessageCache) Flush()

Flush clears the cache.

func (*MessageCache) ReplyFromCache

func (c *MessageCache) ReplyFromCache(w io.Writer, dnsQueryMessage []byte) error

ReplyFromCache writes a DNS reply to w for the provided DNS query message, which must begin with the two ID bytes of a DNS message.

If there's a cache miss, the message is invalid or unexpected, ErrCacheMiss is returned. On cache hit, either nil or an error from a w.Write call is returned.

func (*MessageCache) SetMaxCacheSize

func (c *MessageCache) SetMaxCacheSize(n int)

SetMaxCacheSize sets the maximum number of DNS cache entries that can be stored.

type Resolver

type Resolver struct {
	// Forward is the resolver to use to populate the cache.
	// If nil, net.DefaultResolver is used.
	Forward *net.Resolver

	// LookupIPFallback optionally provides a backup DNS mechanism
	// to use if Forward returns an error or no results.
	LookupIPFallback func(ctx context.Context, host string) ([]netip.Addr, error)

	// TTL is how long to keep entries cached
	//
	// If zero, a default (currently 10 minutes) is used.
	TTL time.Duration

	// UseLastGood controls whether a cached entry older than TTL is used
	// if a refresh fails.
	UseLastGood bool

	// SingleHostStaticResult, if non-nil, is the static result of IPs that is returned
	// by Resolver.LookupIP for any hostname. When non-nil, SingleHost must also be
	// set with the expected name.
	SingleHostStaticResult []netip.Addr

	// SingleHost is the hostname that SingleHostStaticResult is for.
	// It is required when SingleHostStaticResult is present.
	SingleHost string

	// Logf optionally provides a log function to use for debug logs. If
	// not present, log.Printf will be used. The prefix "dnscache: " will
	// be added to all log messages printed with this logger.
	Logf logger.Logf
	// contains filtered or unexported fields
}

Resolver is a minimal DNS caching resolver.

The TTL is always fixed for now. It's not intended for general use. Cache entries are never cleaned up so it's intended that this is only used with a fixed set of hostnames.

func Get

func Get() *Resolver

Get returns a caching Resolver singleton.

func (*Resolver) LookupIP

func (r *Resolver) LookupIP(ctx context.Context, host string) (ip, v6 netip.Addr, allIPs []netip.Addr, err error)

LookupIP returns the host's primary IP address (either IPv4 or IPv6, but preferring IPv4) and optionally its IPv6 address, if there is both IPv4 and IPv6.

If err is nil, ip will be non-nil. The v6 address may be nil even with a nil error.