resolver

package module
v0.9.2 Latest Latest
Warning

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

 Go to latest Published: Jan 24, 2024 License: MIT Imports: 19 Imported by: 6

README

Darvaza DNS Resolver

Go Reference Go Report Card Codebeat Score

Resolver

The Resolver interface reproduces the standard net.Resolver but allows us to make a custom implementation on top of any Lookuper.

We provide three mechanisms to create a Resolver:

  • SystemResolver()/SystemResolverWithDialer() as shortcuts for allocating a standard *net.Resolver{}.
  • NewResolver() returning a Resolver using the given Lookuper{}
  • and NewRootResolver() returning a Resolver using iterative lookup.

Lookuper

The Lookuper interface is centred on Resolver, making simple INET queries.

type Lookuper interface {
    Lookup(ctx context.Context, qName string, qType uint16) (*dns.Msg, error)
}

type LookuperFunc func(ctx context.Context, qName string, qType uint16) (*dns.Msg, error)

Additionally we can use any function implementing the same signature as LookuperFunc, which returns a type implementing Lookuper and Exchanger using the given function.

Exchanger

The Exchanger interface is an alternative to Lookuper but taking pre-assembled *dns.Msg{} queries.

type Exchanger interface {
    Exchange(ctx context.Context, msg *dns.Msg) (*dns.Msg, error)
}

type ExchangerFunc func(ctx context.Context, msg *dns.Msg) (*dns.Msg, error)

Additionally we can use any function implementing the same signature as ExchangerFunc, which returns a type implementing Lookuper and Exchanger using the given function.

client.Client

The client.Client interface represents ExchangeContext() of *dns.Client to perform a *dns.Msg{} against the specified server.

type Client interface {
    ExchangeContext(ctx context.Context, req *dns.Msg, server string) (*dns.Msg, time.Duration, error)
}

type ExchangeFunc func(ctx context.Context, req *dns.Msg, server string) (*dns.Msg, time.Duration, error)

type Unwrapper interface {
    Unwrap() *dns.Client
}

Additionally we can use any function implementing the same signature as client.ExchangeFunc, which returns a type implementing client.Client using the given functions.

Clients are advised to also implement Unwrapper to access the underlying *dns.Client{}.

Errors

We use the standard *net.DNSError{} for all our errors, but also provide errors.MsgAsError() and errors.ErrorAsMsg() to convert back and forth between the errors we emit and an equivalent *dns.Msg.

server.Handler

server.Handler implements a dns.Handler on top of a Lookuper or Exchanger.

Client Implementations

Default Standard Client

client.NewDefaultClient() can be used to get a plain UDP *dns.Client{} with an optional message size.

client.Auto

The client.Auto Client distinguishes requests by server protocol and retries truncated UDP requests as TCP. client.Auto uses udp://, tcp:// and tls:// server prefixes for protocol specific and uses UDP followed by a TCP retry if no prefix is specified.

client.NoAAAA

client.NoAAAA is a Client Middleware that removes all AAAA entries, to be used on systems were IPv6 isn't fully functional.

client.SingleFlight

client.SingleFlight is a Client Middleware that implements a barrier to catch identical queries, with a small caching period. Only the req.Id is ignored when comparing requests, and it operates per-server.

client.WorkerPool

client.WorkerPool is a Client Middleware that implements a barrier limiting the number of exchange calls that can happen in parallel. It's ideally use behind a SingleFlight Client.

reflect.Client

reflect.Client implements logging middleware if front of a client.Client.

Lookuper Implementations

RootLookuper

The RootLookuper implements an iterative Lookuper/Exchanger, supporting an optional custom client.Client.

SingleLookuper

SingleLookuper implements a forwarding Lookuper/Exchanger passing requests as-is to a client.Client.

MultiLookuper

MultiLookuper implements a parallel Lookuper/Exchanger that will pass the request to multiple Lookuper/Exchanger instances and return the first response.

SingleFlight

SingleFlight implements a Lookuper/Exchanger barrier to hold identical requests at the same time, before passing them over to another.

reflect.Lookuper

reflect.Lookuper implements logging middleware in front of a Lookuper or Exchanger.

Well-known recursive resolvers

For convenience we provide shortcuts to create forwarding Lookupers to well known recursive resolvers.

  • NewGoogleLookuper() using 8.8.8.8,
  • NewGoogleLookuper2() using 8.8.4.4,
  • NewCloudflareLookuper() using 1.1.1.1,
  • NewQuad9Lookuper() using 9.9.9.9,
  • and NewQuad9Lookuper6() using Quad9's 2620:fe::f3.

Reflection

reflect.Lookuper and reflect.Client allow us to hook a dynamically enabled logging layer with an optional tracing ID, using the darvaza.org/slog.Logger interface.

See also

Documentation

Overview

Package resolver provides DNS lookup functions

Index

Constants

View Source 
const (
	// DefaultIteratorAttempts indicates how many times a request
	// will be tried by default.
	// Setting it to negative will make the iterator retry
	// unrestrictedly.
	// This can be changed using [IteratorLookuper.SetResilience]
	DefaultIteratorAttempts = 3

	// DefaultIteratorDeadline indicates how long are we willing
	// to wait at most for a request to be fulfilled.
	// Setting it to zero or negative will disable the feature.
	// This can be changed using [IteratorLookuper.SetResilience]
	DefaultIteratorDeadline = 1 * time.Second

	// DefaultIteratorInterval indicates how long to wait
	// before starting a new attempt.
	// Setting it to zero or negative will make the Iterator wait
	// for the previous attempt to finish before starting a new one.
	// This can be changed using [IteratorLookuper.SetResilience]
	DefaultIteratorInterval = 10 * time.Millisecond
)
View Source 
const (
	// DefaultNSCacheSize indicates the cache size if none
	// is specified.
	DefaultNSCacheSize = 1024
)
View Source 
const (
	// MinimumNSCacheTTL tells the minimum time, in seconds,
	// entries remain in the cache
	MinimumNSCacheTTL = 10
)

Variables

This section is empty.

Functions

func DefaultSingleFlightHasher added in v0.7.26 

func DefaultSingleFlightHasher(_ context.Context, req *dns.Msg) (string, error)

DefaultSingleFlightHasher returns the base64 encoded representation of the packed request, ignoring the ID.

func SystemResolver added in v0.0.3 

func SystemResolver(preferGo bool) *net.Resolver

SystemResolver returns a standard net.Resolver configured to preferGo or not

func SystemResolverWithDialer added in v0.0.3 

func SystemResolverWithDialer(preferGo bool, dialer DialerFunc) *net.Resolver

SystemResolverWithDialer returns a standard net.Resolver configured to preferGo or not and use the given Dialer instead of the default

Types

type DialerFunc added in v0.0.3 

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

A DialerFunc is a function that establishes TCP or UDP connection

type Exchanger added in v0.6.0 

type Exchanger interface {
	Exchange(ctx context.Context, q *dns.Msg) (*dns.Msg, error)
}

Exchanger performs a Lookup using a pre-assembled dns.Msg question.

type ExchangerFunc added in v0.6.2 

type ExchangerFunc func(context.Context, *dns.Msg) (*dns.Msg, error)

ExchangerFunc is a function that implements the Exchanger interface

func (ExchangerFunc) Exchange added in v0.6.2 

func (fn ExchangerFunc) Exchange(ctx context.Context, msg *dns.Msg) (*dns.Msg, error)

Exchange implements the Exchanger interface

func (ExchangerFunc) Lookup added in v0.6.2 

func (fn ExchangerFunc) Lookup(ctx context.Context, qName string, qType uint16) (*dns.Msg, error)

Lookup implements the Lookuper interface using an Exchanger function

type IteratorLookuper added in v0.8.0 

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

IteratorLookuper is a generic iterative lookuper, caching zones glue and NS information.

func NewIteratorLookuper added in v0.8.0 

func NewIteratorLookuper(name string, maxRR uint, c client.Client) *IteratorLookuper

NewIteratorLookuper creates a new IteratorLookuper. name and maxRR are used to assemble the NSCache.

func (*IteratorLookuper) AddFrom added in v0.8.0 

func (r *IteratorLookuper) AddFrom(ctx context.Context,
	qName string, ttl uint32, server ...string) error

AddFrom asks the specified server for the NS servers.

func (*IteratorLookuper) AddMap added in v0.8.0 

func (r *IteratorLookuper) AddMap(qName string, ttl uint32, servers map[string]string) error

AddMap loads NS servers from a map

func (*IteratorLookuper) AddMapPersistent added in v0.8.0 

func (r *IteratorLookuper) AddMapPersistent(qName string, ttl uint32,
	servers map[string]string) error

AddMapPersistent loads NS servers from a map but prevents it from being permanently evicted.

func (*IteratorLookuper) AddRootServers added in v0.8.0 

func (r *IteratorLookuper) AddRootServers() error

AddRootServers loads the embedded table of root servers, and made persistent.

func (*IteratorLookuper) AddServer added in v0.8.0 

func (r *IteratorLookuper) AddServer(qName string, ttl uint32, servers ...string) error

AddServer loads NS servers from a list.

func (*IteratorLookuper) DisableAAAA added in v0.8.0 

func (r *IteratorLookuper) DisableAAAA()

DisableAAAA prevents the use of IPv6 entries on NS glue.

func (*IteratorLookuper) Exchange added in v0.8.0 

func (r *IteratorLookuper) Exchange(ctx context.Context, req *dns.Msg) (*dns.Msg, error)

Exchange queries any root server and validates the response

func (*IteratorLookuper) Lookup added in v0.8.0 

func (r *IteratorLookuper) Lookup(ctx context.Context,
	name string, qType uint16) (*dns.Msg, error)

Lookup performs an iterative lookup

func (*IteratorLookuper) ParseAddr added in v0.8.0 

func (r *IteratorLookuper) ParseAddr(server string) (netip.Addr, bool, error)

ParseAddr parses an address and returns if it's acceptable considering if AAAA is enabled or not.

func (*IteratorLookuper) ParseAddrs added in v0.8.0 

func (r *IteratorLookuper) ParseAddrs(servers []string) ([]netip.Addr, error)

ParseAddrs parses a list of addresses, and returns the acceptable ones and the first error.

func (*IteratorLookuper) SetLogger added in v0.8.0 

func (r *IteratorLookuper) SetLogger(log slog.Logger)

SetLogger sets NSCache's logger. slog.Debug is used to record when entries are added or removed.

func (*IteratorLookuper) SetPersistent added in v0.8.0 

func (r *IteratorLookuper) SetPersistent(qName string) error

SetPersistent flags a zone for being restored automatically if evicted.

func (*IteratorLookuper) SetResilience added in v0.9.0 

func (r *IteratorLookuper) SetResilience(attempts int, deadline, interval time.Duration)

SetResilience specifies retry parameters to use when doing an Exchange.

`attempts` indicates how many times a request will be tried, and setting it to negative will make the iterator retry unrestrictedly.

`deadline` indicates how long are we willing to wait at most for a request to be fulfilled. Setting it to zero or negative will disable the feature.

`interval` indicates how long to wait before starting a new attempt. Setting it to zero or negative will make the Iterator wait for the previous attempt to finish before starting a new one.

type LookupResolver added in v0.0.3 

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

LookupResolver uses a Lookuper to implement the Resolver inteface

func NewResolver added in v0.0.3 

func NewResolver(h Lookuper) *LookupResolver

NewResolver returns a Resolver using the provided Lookuper

func NewRootResolver added in v0.4.9 

func NewRootResolver(start string) (*LookupResolver, error)

NewRootResolver creates a LookupResolver using iterative lookup from a given root-server, or random if the argument is ""

func (LookupResolver) LookupAddr added in v0.0.3 

func (LookupResolver) LookupAddr(_ context.Context,
	name string,
) ([]string, error)

LookupAddr performs a reverse lookup for the given address, returning a list of names mapping to that address

func (LookupResolver) LookupCNAME added in v0.0.3 

func (r LookupResolver) LookupCNAME(ctx context.Context,
	host string) (string, error)

LookupCNAME returns the final canonical name after following zero or more CNAME records

func (LookupResolver) LookupHost added in v0.0.3 

func (LookupResolver) LookupHost(_ context.Context,
	name string,
) (addrs []string, err error)

LookupHost returns a slice of the host's addresses

func (LookupResolver) LookupIP added in v0.0.3 

func (r LookupResolver) LookupIP(ctx context.Context,
	network, host string) (s []net.IP, err error)

LookupIP returns the IP addresses of a host in the form of a slice of net.IP. The network must be one of "ip", "ip4" or "ip6".

func (LookupResolver) LookupIPAddr added in v0.0.3 

func (r LookupResolver) LookupIPAddr(ctx context.Context,
	host string) ([]net.IPAddr, error)

LookupIPAddr returns the IP addresses of a host in the form of a slice of net.IPAddr

func (LookupResolver) LookupMX added in v0.0.3 

func (r LookupResolver) LookupMX(ctx context.Context,
	name string) ([]*net.MX, error)

LookupMX returns the DNS MX records for the given domain name sorted by preference

func (LookupResolver) LookupNS added in v0.0.3 

func (LookupResolver) LookupNS(_ context.Context,
	name string,
) ([]*net.NS, error)

LookupNS returns the DNS NS records for the given domain name

func (LookupResolver) LookupNetIP added in v0.0.3 

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

LookupNetIP looks up host using the assigned Lookuper. 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".

func (LookupResolver) LookupSRV added in v0.0.3 

func (r LookupResolver) LookupSRV(ctx context.Context,
	service, proto, name string) (string, []*net.SRV, error)

LookupSRV returns the DNS SRV for _service._proto.domain

func (LookupResolver) LookupTXT added in v0.0.3 

func (r LookupResolver) LookupTXT(ctx context.Context,
	name string) ([]string, error)

LookupTXT returns the DNS TXT records for the given domain name

type Lookuper added in v0.0.3 

type Lookuper interface {
	Lookup(ctx context.Context, qName string, qType uint16) (*dns.Msg, error)
}

Lookuper is the interface that wraps the basic iterative Lookup method.

type LookuperFunc added in v0.6.2 

type LookuperFunc func(context.Context, string, uint16) (*dns.Msg, error)

LookuperFunc is a function that implements the Lookuper interface

func (LookuperFunc) Exchange added in v0.6.2 

func (fn LookuperFunc) Exchange(ctx context.Context, msg *dns.Msg) (*dns.Msg, error)

Exchange implements the Exchanger interface using a Lookuper function

func (LookuperFunc) Lookup added in v0.6.2 

func (fn LookuperFunc) Lookup(ctx context.Context, qName string, qType uint16) (*dns.Msg, error)

Lookup implements the Lookuper interface

type MultiLookuper added in v0.2.0 

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

MultiLookuper queries multiple Lookupers in parallel and takes the first non-error answer

func NewMultiLookuper added in v0.2.0 

func NewMultiLookuper(lookupers ...Lookuper) *MultiLookuper

NewMultiLookuper creates a new Multilookuper using the given Lookupers

func NewMultiLookuperAddresses added in v0.2.0 

func NewMultiLookuperAddresses(servers ...string) (*MultiLookuper, error)

NewMultiLookuperAddresses creates a new Multilookuper composing SingleLookupers for each given address

func (MultiLookuper) Lookup added in v0.2.0 

func (r MultiLookuper) Lookup(ctx context.Context,
	qName string, qType uint16) (*dns.Msg, error)

Lookup queries all Lookupers in parallel and returns the quickest to answer

type NSCache added in v0.7.28 

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

NSCache is a non-recursive Exchanger that caches authoritative delegation information.

func NewNSCache added in v0.7.28 

func NewNSCache(name string, maxRR uint) *NSCache

NewNSCache creates a new NSCache.

func (*NSCache) Add added in v0.7.28 

func (nsc *NSCache) Add(zone *NSCacheZone) error

Add adds a preassembles NSCacheZone.

func (*NSCache) AddMap added in v0.7.28 

func (nsc *NSCache) AddMap(name string, ttl uint32, m map[string]string) error

AddMap adds data from a predefined map.

func (*NSCache) Evict added in v0.8.0 

func (nsc *NSCache) Evict(name string)

Evict removes a zone from the cache if present.

func (*NSCache) Exchange added in v0.7.28 

func (nsc *NSCache) Exchange(ctx context.Context, req *dns.Msg) (*dns.Msg, error)

Exchange attempts to get an authoritative response using the default client.Client.

func (*NSCache) ExchangeWithClient added in v0.7.28 

func (nsc *NSCache) ExchangeWithClient(ctx context.Context,
	req *dns.Msg, c client.Client) (*dns.Msg, error)

ExchangeWithClient attempts to get an authoritative response using the given client.Client.

func (*NSCache) Get added in v0.7.28 

func (nsc *NSCache) Get(qName string) (*NSCacheZone, time.Time, bool)

Get finds the exact NS match in the NSCache for a name.

func (*NSCache) Lookup added in v0.7.28 

func (nsc *NSCache) Lookup(qName string) (*NSCacheZone, bool)

Lookup finds the best NS match in the NSCache for a name.

func (*NSCache) SetLogger added in v0.7.28 

func (nsc *NSCache) SetLogger(log slog.Logger)

SetLogger attaches a logger to the Cache. slog.Debug level is used when adding or removing entries.

func (*NSCache) SetPersistence added in v0.7.28 

func (nsc *NSCache) SetPersistence(qName string, persistent bool) error

SetPersistence flags a zone to be restore if evicted.

func (*NSCache) Suffixes added in v0.7.28 

func (*NSCache) Suffixes(qName string) []string

Suffixes returns the possible suffixes for a domain name.

type NSCacheZone added in v0.7.25 

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

NSCacheZone represents the NS data and glue for a domain name.

func NewNSCacheZone added in v0.7.25 

func NewNSCacheZone(name string) *NSCacheZone

NewNSCacheZone creates a blank NSCacheZone.

func NewNSCacheZoneFromDelegation added in v0.7.25 

func NewNSCacheZoneFromDelegation(resp *dns.Msg) (*NSCacheZone, error)

NewNSCacheZoneFromDelegation creates a new NSCacheZone using the delegation information on a response.

func NewNSCacheZoneFromMap added in v0.7.25 

func NewNSCacheZoneFromMap(name string, ttl uint32, m map[string]string) *NSCacheZone

NewNSCacheZoneFromMap creates a new NSCacheZone using a map for the NS server addresses.

func NewNSCacheZoneFromNS added in v0.8.0 

func NewNSCacheZoneFromNS(resp *dns.Msg) (*NSCacheZone, error)

NewNSCacheZoneFromNS creates a new NSCacheZone using the the response to a NS query.

func (*NSCacheZone) AddGlue added in v0.7.25 

func (zone *NSCacheZone) AddGlue(name string, addrs ...netip.Addr) bool

AddGlue adds an A/AAAA entry to the zone if the name is a registered NS. Returns true if it was added.

func (*NSCacheZone) AddGlueNS added in v0.7.25 

func (zone *NSCacheZone) AddGlueNS(name string, addrs ...netip.Addr) bool

AddGlueNS adds an A/AAAA entry to the zone and, if necessary, the name as NS. Returns true if it was added.

func (*NSCacheZone) AddGlueRR added in v0.7.25 

func (zone *NSCacheZone) AddGlueRR(rr dns.RR) bool

AddGlueRR adds an A/AAAA entry to the zone from a dns.RR record, if the name is a registered NS. Returns true

func (*NSCacheZone) AddNS added in v0.7.25 

func (zone *NSCacheZone) AddNS(name string) bool

AddNS adds the name of a NS to the zone, and returns true if it's new.

func (*NSCacheZone) Addrs added in v0.7.25 

func (zone *NSCacheZone) Addrs() []string

Addrs produces a sorted string array containing all the A/AAAA entries known for this zone.

func (*NSCacheZone) Exchange added in v0.9.0 

func (zone *NSCacheZone) Exchange(ctx context.Context, req *dns.Msg) (*dns.Msg, error)

Exchange performs a DNS request on a random NS server of the zone, retrying on errors if NSCacheZone.SetResilience has been used.

func (*NSCacheZone) ExchangeWithClient added in v0.9.0 

func (zone *NSCacheZone) ExchangeWithClient(ctx context.Context, req *dns.Msg,
	c client.Client) (*dns.Msg, error)

ExchangeWithClient performs a DNS request on a random NS server of the zone, using the given client.Client, and retrying on errors if NSCacheZone.SetResilience has been used.

func (*NSCacheZone) Expire added in v0.7.25 

func (zone *NSCacheZone) Expire() time.Time

Expire tells when this information is no long valid.

func (*NSCacheZone) ExportGlue added in v0.7.25 

func (zone *NSCacheZone) ExportGlue() []dns.RR

ExportGlue produces a dns.RR slice containing all the A/AAAA entries known for this zone.

func (*NSCacheZone) ExportNS added in v0.7.25 

func (zone *NSCacheZone) ExportNS() []dns.RR

ExportNS produces a dns.RR slice containing all the NS entries

func (*NSCacheZone) ForEachAddr added in v0.7.25 

func (zone *NSCacheZone) ForEachAddr(fn func(string) bool)

ForEachAddr calls a function for each address in random order. return true to terminate the loop.

func (*NSCacheZone) ForEachNS added in v0.7.25 

func (zone *NSCacheZone) ForEachNS(fn func(name string, addrs []netip.Addr))

ForEachNS calls the function for each registered NS, including any known glue addresses.

func (*NSCacheZone) HasGlue added in v0.8.0 

func (zone *NSCacheZone) HasGlue() bool

HasGlue tells if this zone has any glue address.

func (*NSCacheZone) Index added in v0.7.25 

func (zone *NSCacheZone) Index()

Index processes the zone data and prepares it to be used.

func (*NSCacheZone) IsValid added in v0.7.25 

func (zone *NSCacheZone) IsValid() bool

IsValid tells if a zone can be stored.

func (*NSCacheZone) Len added in v0.7.25 

func (zone *NSCacheZone) Len() int

Len returns the number of dns.RR entries stored.

func (*NSCacheZone) Name added in v0.7.25 

func (zone *NSCacheZone) Name() string

Name returns the domain name associated to these servers.

func (*NSCacheZone) NeedsRefresh added in v0.7.25 

func (zone *NSCacheZone) NeedsRefresh() bool

NeedsRefresh tells when this information should be refreshed.

func (*NSCacheZone) OriginalTTL added in v0.7.25 

func (zone *NSCacheZone) OriginalTTL() uint32

OriginalTTL returns the number of seconds the data was set to live initially.

func (*NSCacheZone) RandomAddrs added in v0.7.25 

func (zone *NSCacheZone) RandomAddrs() []string

RandomAddrs produces a randomly shuffled strings array containing all the A/AAAA entries known for this zone

func (*NSCacheZone) ReplyNS added in v0.8.0 

func (zone *NSCacheZone) ReplyNS(req *dns.Msg) *dns.Msg

ReplyNS produces a response message equivalent to an NS request for the cache domain, including the known glue and current TTL.

func (*NSCacheZone) Server added in v0.7.25 

func (zone *NSCacheZone) Server() string

Server returns one address chosen randomly or and empty string if there is none.

func (*NSCacheZone) Servers added in v0.7.25 

func (zone *NSCacheZone) Servers() []string

Servers produces a string array containing all the NS entries known for this zone.

func (*NSCacheZone) SetGlue added in v0.7.25 

func (zone *NSCacheZone) SetGlue(name string, addrs []netip.Addr) bool

SetGlue set the A/AAAA entries for a NS of a zone if it's registered as such. Returns true if it was set.

func (*NSCacheZone) SetResilience added in v0.9.0 

func (zone *NSCacheZone) SetResilience(attempts int, deadline, interval time.Duration)

SetResilience specifies retry parameters to use when doing an Exchange.

func (*NSCacheZone) SetTTL added in v0.7.25 

func (zone *NSCacheZone) SetTTL(ttl, half uint32)

SetTTL sets the expiration and half-life times in seconds from Now.

func (*NSCacheZone) TTL added in v0.7.25 

func (zone *NSCacheZone) TTL() uint32

TTL returns the number of seconds the data has to live.

type Pool added in v0.8.3 

type Pool struct {

	// Attempts indicates how many times we will try. A negative
	// value indicates we will keep on trying
	Attempts int

	// Deadline is an optional maximum time exchanges can take.
	Deadline time.Duration

	// Interval indicates how long to wait until a new attempt is
	// started.
	Interval time.Duration
	// contains filtered or unexported fields
}

A Pool is a Exchanger with multiple possible servers behind and tries some at random up to a given limit of parallel requests.

func NewPoolExchanger added in v0.8.3 

func NewPoolExchanger(c client.Client, servers ...string) (*Pool, error)

NewPoolExchanger creates a new [PoolExchanger] middleware.

func (*Pool) Add added in v0.8.3 

func (p *Pool) Add(servers ...string) error

Add adds servers to the Pool.

func (*Pool) Exchange added in v0.8.3 

func (p *Pool) Exchange(ctx context.Context, req *dns.Msg) (*dns.Msg, error)

Exchange makes a DNS request to a random server in the Pool

func (*Pool) ExchangeWithClient added in v0.8.3 

func (p *Pool) ExchangeWithClient(ctx context.Context, req *dns.Msg, c client.Client) (*dns.Msg, error)

ExchangeWithClient makes a DNS request to a random server in the Pool using the given client.Client.

func (*Pool) ForEach added in v0.8.3 

func (p *Pool) ForEach(fn func(string) bool)

ForEach calls a function for each registered server in random order. Return true to terminate the loop.

func (*Pool) Len added in v0.8.3 

func (p *Pool) Len() int

Len indicates how many servers are registered in the Pool.

func (*Pool) Lookup added in v0.8.3 

func (p *Pool) Lookup(ctx context.Context, qName string, qType uint16) (*dns.Msg, error)

Lookup makes an INET DNS request to a random server in the Pool

func (*Pool) Remove added in v0.8.3 

func (p *Pool) Remove(servers ...string) error

Remove removes servers from the Pool.

func (*Pool) Server added in v0.8.3 

func (p *Pool) Server() string

Server returns on registered server chosen at random. They can repeat.

func (*Pool) Servers added in v0.8.3 

func (p *Pool) Servers() []string

Servers returns the list of registered servers in random order.

type Resolver added in v0.0.3 

type Resolver interface {
	// LookupIPAddr looks up host using the assigned Lookuper.
	// It returns a slice of that host's IPv4 and IPv6 addresses.
	LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)

	// LookupIP looks up host for the given network using assigned Lookuper
	// It returns a slice of that host's IP addresses of the type specified
	// by network. network must be one of "ip", "ip4" or "ip6".
	LookupIP(ctx context.Context, network, host string) ([]net.IP, error)

	// LookupNetIP looks up host using the assigned Lookuper. 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)

	// LookupAddr performs a reverse lookup for the given address, returning a list
	// of names mapping to that address.
	//
	// The returned names are validated to be properly formatted presentation-format
	// domain names. If the response contains invalid names, those records are
	// filtered out and an error will be returned alongside the remaining results,
	// if any.
	LookupAddr(ctx context.Context, addr string) ([]string, error)

	// LookupCNAME returns the canonical name for the given host. Callers that do not
	// care about the canonical name can call LookupHost or LookupIP directly; both
	// take care of resolving the canonical name as part of the lookup.
	// A canonical name is the final name after following zero or more CNAME records.
	// LookupCNAME does not return an error if host does not contain DNS "CNAME"
	// records, as long as host resolves to address records.
	// The returned canonical name is validated to be a properly formatted
	// presentation-format domain name.
	LookupCNAME(ctx context.Context, host string) (string, error)

	// LookupHost looks up the given host using the assigned Lookuper. It returns a
	// slice of that host's addresses.
	LookupHost(ctx context.Context, host string) (addrs []string, err error)

	// LookupMX returns the DNS MX records for the given domain name sorted by
	// preference.
	// The returned mail server names are validated to be properly formatted
	// presentation-format domain names. If the response contains invalid names,
	// those records are filtered out and an error will be returned alongside
	// the remaining results, if any.
	LookupMX(ctx context.Context, name string) ([]*net.MX, error)

	// LookupNS returns the DNS NS records for the given domain name.
	// The returned name server names are validated to be properly formatted
	// presentation-format domain names. If the response contains invalid names,
	// those records are filtered out and an error will be returned alongside
	// the remaining results, if any.
	LookupNS(ctx context.Context, name string) ([]*net.NS, error)

	// LookupSRV tries to resolve an SRV query of the given service, protocol,
	// and domain name. The proto is "tcp" or "udp". The returned records are
	// sorted by priority and randomized by weight within a priority.
	//
	// LookupSRV constructs the DNS name to look up following RFC 2782. That is,
	// it looks up _service._proto.name. To accommodate services publishing SRV
	// records under non-standard names, if both service and proto are empty
	// strings, LookupSRV looks up name directly.
	//
	// The returned service names are validated to be properly formatted
	// presentation-format domain names. If the response contains invalid names,
	// those records are filtered out and an error will be returned alongside
	// the remaining results, if any.
	LookupSRV(ctx context.Context, service, proto, name string) (cname string,
		addrs []*net.SRV, err error)

	// LookupTXT returns the DNS TXT records for the given domain name.
	LookupTXT(ctx context.Context, name string) ([]string, error)
}

A Resolver implements the interface of net.Resolver

type RootLookuper added in v0.1.0 

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

RootLookuper does iterative lookup using the root servers.

func NewRootLookuper added in v0.1.1 

func NewRootLookuper(start string) (*RootLookuper, error)

NewRootLookuper creates a RootLookuper using the indicated root, or random if the argument is ""

func NewRootLookuperWithClient added in v0.7.3 

func NewRootLookuperWithClient(start string, c client.Client) (*RootLookuper, error)

NewRootLookuperWithClient creates a RootLookuper using the indicated root, or random if the argument is "", and uses the given client.Client to connect.

func (RootLookuper) DisableAAAA added in v0.8.0 

func (r RootLookuper) DisableAAAA()

DisableAAAA prevents the use of IPv6 entries on NS glue.

func (RootLookuper) Exchange added in v0.3.0 

func (r RootLookuper) Exchange(ctx context.Context, m *dns.Msg) (*dns.Msg, error)

Exchange queries any root server and validates the response

func (RootLookuper) Lookup added in v0.1.0 

func (r RootLookuper) Lookup(ctx context.Context, qName string, qType uint16) (*dns.Msg, error)

Lookup performs an iterative lookup

type SingleFlight added in v0.7.26 

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

SingleFlight is an Exchanger/Lookuper that holds/caches identical queries before passing them over to another Exchanger.

func NewSingleFlight added in v0.7.26 

func NewSingleFlight(next Exchanger, exp time.Duration,
	hasher SingleFlightHasher) (*SingleFlight, error)

NewSingleFlight creates a Exchanger wrapper holding/caching identical requests for up to the given time, using the given function to produce the keys or base64 packed if no hasher is provided. use negative exp to indicate immediate as zero will be replaced with the default of 1s.

func (*SingleFlight) Exchange added in v0.7.26 

func (sf *SingleFlight) Exchange(ctx context.Context, req *dns.Msg) (*dns.Msg, error)

Exchange implements the Exchanger interface holding/caching identical queries.

func (*SingleFlight) Lookup added in v0.7.26 

func (sf *SingleFlight) Lookup(ctx context.Context, qName string, qType uint16) (*dns.Msg, error)

Lookup implements the Lookuper interface holding/caching identical queries.

type SingleFlightHasher added in v0.7.26 

type SingleFlightHasher func(context.Context, *dns.Msg) (string, error)

SingleFlightHasher is a function that generates the caching key for a request.

type SingleLookuper added in v0.2.0 

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

SingleLookuper asks a single server for a direct answer to the query preventing repetition

func NewCloudflareLookuper added in v0.2.0 

func NewCloudflareLookuper() *SingleLookuper

NewCloudflareLookuper creates a Lookuper asking 1.1.1.1 (Cloudflare)

func NewGoogleLookuper added in v0.2.0 

func NewGoogleLookuper() *SingleLookuper

NewGoogleLookuper creates a Lookuper asking 8.8.8.8 (Google)

func NewGoogleLookuper2 added in v0.2.0 

func NewGoogleLookuper2() *SingleLookuper

NewGoogleLookuper2 creates a Lookuper asking 8.8.4.4 (Google)

func NewQuad9Lookuper added in v0.2.0 

func NewQuad9Lookuper() *SingleLookuper

NewQuad9Lookuper creates a Lookuper asking 9.9.9.9 (Quad9.net)

func NewQuad9Lookuper6 added in v0.2.0 

func NewQuad9Lookuper6() *SingleLookuper

NewQuad9Lookuper6 creates a Lookuper asking Quad9.net using IPv6

func NewSingleLookuper added in v0.2.0 

func NewSingleLookuper(server string, recursive bool) (*SingleLookuper, error)

NewSingleLookuper creates a Lookuper that asks one particular server

func NewSingleLookuperWithClient added in v0.7.3 

func NewSingleLookuperWithClient(server string, recursive bool,
	c client.Client) (*SingleLookuper, error)

NewSingleLookuperWithClient creates a lookuper that asks one particular server using the provided DNS client

func (SingleLookuper) Exchange added in v0.2.0 

func (r SingleLookuper) Exchange(ctx context.Context,
	msg *dns.Msg) (*dns.Msg, error)

Exchange exchanges a message with a designed server

func (SingleLookuper) Lookup added in v0.2.0 

func (r SingleLookuper) Lookup(ctx context.Context,
	qName string, qType uint16) (*dns.Msg, error)

Lookup asks the designed remote to make a DNS Lookup

type ZeroLookuper added in v0.0.3 

type ZeroLookuper struct{}

A ZeroLookuper is a Lookuper that never finds anything

func (ZeroLookuper) Lookup added in v0.0.3 

func (ZeroLookuper) Lookup(_ context.Context, qName string, _ uint16) (*dns.Msg, error)

Lookup implements Lookuper but always fails

Source Files

View all Source files

Directories

Path Synopsis
pkg
client
Package client implements DNS client wrappers
 Package client implements DNS client wrappers
errors
Package errors aids error handling for [dns.Msg] and darvaza.org/resolver related functions
 Package errors aids error handling for [dns.Msg] and darvaza.org/resolver related functions
exdns
Package exdns contains helpers to work with [dns.Msg]
 Package exdns contains helpers to work with [dns.Msg]
reflect
Package reflect provides a logging layer for exchangers and client
 Package reflect provides a logging layer for exchangers and client
server
Package server aids writing DNS servers
 Package server aids writing DNS servers

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.