recursive

package module
v0.12.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 13, 2025 License: MIT Imports: 18 Imported by: 0

README

recursive

Recursive DNS resolver with QNAME minimization and optional cache.

Documentation

Index

Constants

View Source 
const DefaultMaxTTL = 3600 * 6 // six hours
View Source 
const DefaultMinTTL = 10 // ten seconds
View Source 
const DefaultNXTTL = 3600 // one hour
View Source 
const MaxQtype = 260

Variables

View Source 
var (
	// ErrInvalidCookie is returned if the DNS cookie from the server is invalid.
	ErrInvalidCookie = errors.New("invalid cookie")
	// ErrMaxDepth is returned when recursive resolving exceeds the allowed limit.
	ErrMaxDepth = fmt.Errorf("recursion depth exceeded %d", maxDepth)
	// ErrNoResponse is returned when no authoritative server could be successfully queried.
	// It is equivalent to SERVFAIL.
	ErrNoResponse = errors.New("no authoritative response")
	// ErrQuestionMismatch is returned when the DNS response is not for what was queried.
	ErrQuestionMismatch = errors.New("question mismatch")
	DefaultCache        = NewCache()
	DefaultTimeout      = time.Second * 5
)
View Source 
var Roots4 = []netip.Addr{
	netip.AddrFrom4([4]byte([]byte{0xaa, 0xf7, 0xaa, 0x2})),
	netip.AddrFrom4([4]byte([]byte{0xc0, 0x5, 0x5, 0xf1})),
	netip.AddrFrom4([4]byte([]byte{0xc0, 0x21, 0x4, 0xc})),
	netip.AddrFrom4([4]byte([]byte{0xc0, 0x24, 0x94, 0x11})),
	netip.AddrFrom4([4]byte([]byte{0xc0, 0x3a, 0x80, 0x1e})),
	netip.AddrFrom4([4]byte([]byte{0xc0, 0x70, 0x24, 0x4})),
	netip.AddrFrom4([4]byte([]byte{0xc0, 0xcb, 0xe6, 0xa})),
	netip.AddrFrom4([4]byte([]byte{0xc1, 0x0, 0xe, 0x81})),
	netip.AddrFrom4([4]byte([]byte{0xc6, 0x29, 0x0, 0x4})),
	netip.AddrFrom4([4]byte([]byte{0xc6, 0x61, 0xbe, 0x35})),
	netip.AddrFrom4([4]byte([]byte{0xc7, 0x7, 0x53, 0x2a})),
	netip.AddrFrom4([4]byte([]byte{0xc7, 0x7, 0x5b, 0xd})),
	netip.AddrFrom4([4]byte([]byte{0xca, 0xc, 0x1b, 0x21})),
}
View Source 
var Roots6 = []netip.Addr{
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x53})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x0, 0x0, 0x2, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xc})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x0, 0x0, 0x12, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xd, 0xd})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x0, 0x0, 0x2d, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xd})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x0, 0x0, 0x2f, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xf})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x0, 0x0, 0x9f, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x42})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x0, 0x0, 0xa8, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xe})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x3, 0xc, 0x27, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x2, 0x0, 0x30})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x5, 0x3, 0xba, 0x3e, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x2, 0x0, 0x30})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x7, 0xfd, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0x7, 0xfe, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x53})),
	netip.AddrFrom16([16]byte([]byte{0x20, 0x1, 0xd, 0xc3, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x35})),
	netip.AddrFrom16([16]byte([]byte{0x28, 0x1, 0x1, 0xb8, 0x0, 0x10, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xb})),
}

Functions

func AddrFromRR 

func AddrFromRR(rr dns.RR) netip.Addr

func DnsTypeToString 

func DnsTypeToString(qtype uint16) string

func MinTTL 

func MinTTL(msg *dns.Msg) int

MinTTL returns the lowest resource record TTL in the message, or -1 if there are no records.

Types

type Cache added in v0.1.2 

type Cache struct {
	MinTTL int // always cache responses for at least this long
	MaxTTL int // never cache responses for longer than this (excepting successful NS responses)
	NXTTL  int // cache NXDOMAIN responses for this long
	// contains filtered or unexported fields
}

func NewCache added in v0.1.2 

func NewCache() *Cache

func (*Cache) Clean added in v0.1.2 

func (cache *Cache) Clean()

func (*Cache) Clear added in v0.1.4 

func (cache *Cache) Clear()

func (*Cache) DnsGet added in v0.2.0 

func (cache *Cache) DnsGet(qname string, qtype uint16) (msg *dns.Msg)

func (*Cache) DnsResolve added in v0.2.0 

func (cache *Cache) DnsResolve(ctx context.Context, qname string, qtype uint16) (msg *dns.Msg, srv netip.Addr, err error)

func (*Cache) DnsSet added in v0.2.0 

func (cache *Cache) DnsSet(msg *dns.Msg)

func (*Cache) Entries added in v0.2.0 

func (cache *Cache) Entries() (n int)

Entries returns the number of entries in the cache.

func (*Cache) HitRatio added in v0.1.2 

func (cache *Cache) HitRatio() float64

HitRatio returns the hit ratio as a percentage.

type Cacher added in v0.1.4 

type Cacher interface {
	// DnsSet may make a copy of msg and set it's dns.Msg.Zero to true and return it later with DnsGet.
	DnsSet(msg *dns.Msg)

	// DnsGet returns the cached dns.Msg for the given qname and qtype, or nil.
	// Do not modify the returned msg. Make a copy of it if needed.
	//
	// dns.Msg.Zero must be set to true to indicate response is served from cache.
	DnsGet(qname string, qtype uint16) *dns.Msg
}

type CachingResolver added in v0.2.0 

type CachingResolver interface {
	Resolver
	Cacher
}

type Recursive added in v0.1.6 

type Recursive struct {
	proxy.ContextDialer               // (read-only) ContextDialer passed to NewWithOptions
	Cacher                            // (read-only) Cacher passed to NewWithOptions
	*net.Resolver                     // (read-only) net.Resolver using our ContextDialer
	Timeout             time.Duration // (read-only) dialing timeout, zero to disable

	DefaultLogWriter io.Writer // if not nil, write debug logs here unless overridden
	// contains filtered or unexported fields
}

func New 

func New(dialer proxy.ContextDialer) *Recursive

New returns a new Recursive resolver using the given ContextDialer and has DefaultCache as it's cache.

It calls OrderRoots before returning.

func NewWithOptions 

func NewWithOptions(dialer proxy.ContextDialer, cache Cacher, roots4, roots6 []netip.Addr, rateLimiter <-chan struct{}) *Recursive

NewWithOptions returns a new Recursive resolver using the given ContextDialer and using the given Cacher as it's default cache. It does not call OrderRoots.

Passing nil for dialer will use a net.Dialer. Passing nil for cache means it won't use any cache by default. Passing nil for the roots will use the default set of roots. Passing nil for the rateLimiter means no rate limiting

func (*Recursive) DnsResolve added in v0.2.0 

func (r *Recursive) DnsResolve(ctx context.Context, qname string, qtype uint16) (msg *dns.Msg, srv netip.Addr, err error)

DnsResolve performs a recursive DNS resolution for the provided name and record type.

func (*Recursive) GetRoots added in v0.9.1 

func (r *Recursive) GetRoots() (root4, root6 []netip.Addr)

Roots returns the current set of root servers in use.

func (*Recursive) LookupHost added in v0.9.0 

func (rc *Recursive) LookupHost(ctx context.Context, host string) (addrs []string, err error)

func (*Recursive) LookupIP added in v0.9.0 

func (rc *Recursive) LookupIP(ctx context.Context, network, host string) (ips []net.IP, err error)

func (*Recursive) LookupIPAddr added in v0.9.0 

func (rc *Recursive) LookupIPAddr(ctx context.Context, host string) (addrs []net.IPAddr, err error)

func (*Recursive) LookupNS added in v0.9.0 

func (rc *Recursive) LookupNS(ctx context.Context, name string) (nslist []*net.NS, err error)

func (*Recursive) LookupNetIP added in v0.9.0 

func (rc *Recursive) LookupNetIP(ctx context.Context, network, host string) (addrs []netip.Addr, err error)

func (*Recursive) OrderRoots added in v0.2.0 

func (r *Recursive) OrderRoots(ctx context.Context)

OrderRoots sorts the root server list by their current latency and removes those that don't respond.

If ctx does not have a deadline, DefaultTimeout will be used.

func (*Recursive) ResetCookies added in v0.5.0 

func (r *Recursive) ResetCookies()

ResetCookies generates a new DNS client cookie and clears the known DNS server cookies.

func (*Recursive) ResolveWithOptions added in v0.1.6 

func (r *Recursive) ResolveWithOptions(ctx context.Context, cache Cacher, logw io.Writer, qname string, qtype uint16) (msg *dns.Msg, srv netip.Addr, err error)

ResolveWithOptions performs a recursive DNS resolution for the provided name and record type.

If cache is nil, no cache is used. If logw is non-nil (or DefaultLogWriter is set), write a log of events.

type Resolver 

type Resolver interface {
	DnsResolve(ctx context.Context, qname string, qtype uint16) (msg *dns.Msg, srv netip.Addr, err error)
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
cli command
genhints command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.