resolver

README

Resolver

A 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.
• Fluent and expressive API (allowing sophisticated resolution strategies).
• Parallel query support.
• Custom dialer support.

TODOs

• Support for /etc/resolvers/ see: Go #12524, might make sense to shell out to scutil --dns.
• DNS over HTTPS support.
• DNSSEC support?
• Multicast DNS support, RFC 6762?
• Non recursive DNS server support?

Documentation

Index

• Variables
• func DNS(conf DNSResolverConfig) *dnsResolver
• func DNS64(resolver Resolver, conf *DNS64ResolverConfig) *dns64Resolver
• func Parallel(resolvers ...Resolver) *parallelResolver
• func Relative(resolver Resolver, conf *RelativeResolverConfig) *relativeResolver
• func Retry(resolver Resolver, conf *RetryResolverConfig) *retryResolver
• func RoundRobin(resolvers ...Resolver) *roundRobinResolver
• func Sequential(resolvers ...Resolver) *sequentialResolver
• type DNS64ResolverConfig
• type DNSResolverConfig
• type DNSTransport
• type DialContextFunc
• type HostsResolver
  • func Hosts(conf *HostsResolverConfig) (*HostsResolver, error)
  • func (r *HostsResolver) AddHost(host string, addrs ...netip.Addr)
  • func (r *HostsResolver) LookupNetIP(ctx context.Context, network, host string) ([]netip.Addr, error)
  • func (r *HostsResolver) RemoveHost(host string)
• type HostsResolverConfig
• type RelativeResolverConfig
• type Resolver
  • func Literal() 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 DNS

func DNS(conf DNSResolverConfig) *dnsResolver

DNS creates a new DNS resolver.

func DNS64

func DNS64(resolver Resolver, conf *DNS64ResolverConfig) *dns64Resolver

DNS64 returns a resolver that synthesizes IPv6 addresses from IPv4 addresses using DNS64 (RFC 6147).

func Parallel

func Parallel(resolvers ...Resolver) *parallelResolver

Parallel returns a resolver that tries each resolver in parallel until one succeeds.

func Relative

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

Relative returns a resolver that resolves relative hostnames.

func Retry

func Retry(resolver Resolver, conf *RetryResolverConfig) *retryResolver

Retry returns a resolver that retries a resolver a number of times.

func RoundRobin

func RoundRobin(resolvers ...Resolver) *roundRobinResolver

RoundRobin returns a Resolver that load balances between multiple resolvers using a round-robin strategy.

func Sequential

func Sequential(resolvers ...Resolver) *sequentialResolver

Sequential returns a resolver that tries each resolver in order until one succeeds.

Types

type DNS64ResolverConfig

type DNS64ResolverConfig struct {
	// Prefix is the IPv6 prefix to use.
	// If not set, the well-known prefix "64:ff9b::/96" is used.
	Prefix *netip.Prefix
	// DialContext is used to establish a connection to a DNS server.
	DialContext DialContextFunc
}

DNS64ResolverConfig is the configuration for a DNS64 resolver.

type DNSResolverConfig

type DNSResolverConfig struct {
	// Server is the DNS server to query.
	Server netip.AddrPort
	// Transport is the optional transport protocol used for DNS resolution.
	// By default, plain DNS over UDP is used.
	Transport *DNSTransport
	// 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 DialContextFunc
	// TLSConfig is the configuration for the TLS client used for DNS over TLS.
	TLSConfig *tls.Config
	// SingleRequest is used to query A and AAAA records sequentially.
	// This is mostly useful for avoiding conntrack race issues with DNS over UDP.
	// If you feel the need to enable this, you should probably just use
	// DNS over TCP instead.
	SingleRequest *bool
}

DNSResolverConfig is the configuration for a DNS resolver.

type DNSTransport

type DNSTransport string

DNSTransport is the transport protocol used for DNS resolution.

const (
	// DNSTransportUDP is DNS over UDP as defined in RFC 1035.
	DNSTransportUDP DNSTransport = "udp"
	// DNSTransportTCP is DNS over TCP as defined in RFC 1035.
	DNSTransportTCP DNSTransport = "tcp"
	// DNSTransportTLS is DNS over TLS as defined in RFC 7858.
	DNSTransportTLS DNSTransport = "tcp-tls"
)

type DialContextFunc

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

DialContextFunc is a network dialer that can be used to dial a network.

type HostsResolver

type HostsResolver struct {
	// contains filtered or unexported fields
}

func Hosts

func Hosts(conf *HostsResolverConfig) (*HostsResolver, error)

func (*HostsResolver) AddHost

func (r *HostsResolver) AddHost(host string, addrs ...netip.Addr)

AddHost adds an ephemeral host to the resolver with the given addresses.

func (*HostsResolver) LookupNetIP

func (r *HostsResolver) LookupNetIP(ctx context.Context, network, host string) ([]netip.Addr, error)

func (*HostsResolver) RemoveHost

func (r *HostsResolver) RemoveHost(host string)

RemoveHost removes an ephemeral host from the resolver.

type HostsResolverConfig

type HostsResolverConfig struct {
	// HostsFileReader is an optional reader that will be used as the source of the hosts file.
	// If not provided, the OS's default hosts file will be used.
	HostsFileReader io.Reader
	// DialContext is an optional dialer used for ordering the returned addresses.
	DialContext DialContextFunc
	// NoHostsFile disables the use of the hosts file.
	// This is useful when operating with only ephemeral hosts.
	NoHostsFile *bool
}

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 {
	// 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, this interface is also implemented by net.Resolver from the Go standard library.

func Literal

func Literal() Resolver

Literal returns a resolver that resolves IP literals.

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 indefinitely.
	Attempts *int
}

RetryResolverConfig is the configuration for a retry resolver.

type SystemResolverConfig

type SystemResolverConfig struct {
	// HostsFilePath is the optional path to the hosts file.
	// By default, the system's hosts file is used.
	HostsFilePath string
	// DialContext is used to establish a connection to a DNS server.
	DialContext DialContextFunc
}

SystemResolverConfig is the configuration for a system resolver.