resolver

README

Resolver

A minimal pure Go DNS resolver implementation, designed to be a drop in replacement for net.Resolver.

Features

• Pure Go implementation.
• DNS over UDP, TCP, and TLS.
• Chainable query options.
• Custom dialer support.

TODOs

• Implement more of the net.Resolver interface.
• Parallel queries.
• Non recursive DNS server support.

Documentation

Index

• Variables
• func Chain(resolvers ...Resolver) *chainResolver
• func DNS(conf *DNSResolverConfig) *dnsResolver
• func File(hostsfileReader io.Reader, conf *FileResolverConfig) (*fileResolver, error)
• func Relative(inner Resolver, conf *RelativeResolverConfig) *relativeResolver
• func RoundRobin(resolvers ...Resolver) *roundRobinResolver
• type DNSResolverConfig
• type FileResolverConfig
• type Protocol
• type RelativeResolverConfig
• type Resolver
  • func IP() Resolver
  • func Retry(inner Resolver, conf *RetryResolverConfig) Resolver
  • func System(conf *SystemResolverConfig) (Resolver, error)
• type RetryResolverConfig
• type SystemResolverConfig

Variables

var (
	ErrNoSuchHost          = errors.New("no such host")
	ErrServerMisbehaving   = errors.New("server misbehaving")
	ErrUnsupportedNetwork  = errors.New("unsupported network")
	ErrUnsupportedProtocol = errors.New("unsupported protocol")
)

Functions

func Chain

func Chain(resolvers ...Resolver) *chainResolver

Chain returns a Resolver that chains the given resolvers. It tries each resolver in order until one of them returns a non-nil result.

func DNS

func DNS(conf *DNSResolverConfig) *dnsResolver

DNS returns a new DNS resolver.

func File

func File(hostsfileReader io.Reader, conf *FileResolverConfig) (*fileResolver, error)

File creates a new hosts file resolver from the given reader.

func Relative

func Relative(inner Resolver, conf *RelativeResolverConfig) *relativeResolver

Relative creates a new relative name resolver.

func RoundRobin

func RoundRobin(resolvers ...Resolver) *roundRobinResolver

RoundRobin returns a Resolver that load balances between multiple resolvers by chaining them in a random order.

Types

type DNSResolverConfig

type DNSResolverConfig struct {
	// Protocol is the protocol used for DNS resolution.
	Protocol Protocol
	// Server is the DNS server to query.
	Server netip.AddrPort
	// Timeout is the maximum duration to wait for a query to complete.
	Timeout *time.Duration
	// DialContext is used to establish a connection to a DNS server.
	DialContext func(ctx context.Context, network, address string) (net.Conn, error)
	// TLSClientConfig is the configuration for the TLS client used for DNS over TLS.
	TLSClientConfig *tls.Config
}

DNSResolverConfig is the configuration for a DNS resolver.

type FileResolverConfig

type FileResolverConfig struct {
	// DialContext is an optional function for creating network connections.
	// It is used for ordering the returned addresses.
	DialContext func(ctx context.Context, network, address string) (net.Conn, error)
}

FileResolverConfig is the configuration for a hosts file resolver.

type Protocol

type Protocol string

Protocol is the protocol used for DNS resolution.

const (
	// ProtocolUDP is the DNS over UDP as defined in RFC 1035.
	ProtocolUDP Protocol = "udp"
	// ProtocolTCP is the DNS over TCP as defined in RFC 1035.
	ProtocolTCP Protocol = "tcp"
	// ProtocolTLS is the DNS over TLS as defined in RFC 7858.
	ProtocolTLS Protocol = "tls"
)

type RelativeResolverConfig

type RelativeResolverConfig struct {
	// Search is a list of rooted suffixes to append to the relative name.
	Search []string
	// NDots is the number of dots in a name to trigger an absolute lookup.
	NDots int
}

RelativeResolverConfig is the configuration for a relative domain resolver.

type Resolver

type Resolver interface {
	// LookupHost looks up the given host using the resolver. It returns a slice
	// of that host's addresses.
	LookupHost(ctx context.Context, host string) (addrs []string, err error)
	// LookupNetIP looks up host using the resolver. It returns a slice of that
	// host's IP addresses of the type specified by network. The network must be
	// one of "ip", "ip4" or "ip6".
	LookupNetIP(ctx context.Context, network, host string) ([]netip.Addr, error)
}

Resolver looks up names and numbers.

func IP

func IP() Resolver

IP returns a resolver that looks up IP address strings.

func Retry

func Retry(inner Resolver, conf *RetryResolverConfig) Resolver

Retry creates a new resolver that retries the inner resolver a configurable number of times (for temporary errors).

func System

func System(conf *SystemResolverConfig) (Resolver, error)

System returns a Resolver that uses the system's default DNS configuration.

type RetryResolverConfig

type RetryResolverConfig struct {
	// Attempts is the number of attempts to make before giving up.
	// Setting this to 0 will cause the resolver to retry forever.
	Attempts int
}

RetryResolverConfig is the configuration for a retry resolver.

type SystemResolverConfig

type SystemResolverConfig struct {
	// Timeout is the maximum duration to wait for a query to complete
	// (including retries).
	Timeout *time.Duration
	// DialContext is used to establish a connection to a DNS server.
	DialContext func(ctx context.Context, network, address string) (net.Conn, error)
	// TLSClientConfig is the configuration for the TLS client used for DNS over TLS.
	TLSClientConfig *tls.Config
}

SystemResolverConfig is the configuration for a system resolver.