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
• 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 net.IP, allIPs []net.IPAddr, err error)

Variables

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

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

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) ([]netaddr.IP, 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
	// 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 net.IP, allIPs []net.IPAddr, 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.