resolvers

Documentation

Index

• func CloseResolvers(resolvers []Resolver) error
• type Answer
• type Authority
• type ClassicResolver
  • func (r *ClassicResolver) Address() string
  • func (r *ClassicResolver) Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)
• type ClassicResolverOpts
• type DNSCryptResolver
  • func (r *DNSCryptResolver) Address() string
  • func (r *DNSCryptResolver) Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)
• type DNSCryptResolverOpts
• type DOHResolver
  • func (r *DOHResolver) Address() string
  • func (r *DOHResolver) Close() error
  • func (r *DOHResolver) Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)
• type DOQResolver
  • func (r *DOQResolver) Address() string
  • func (r *DOQResolver) Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)
• type EdnsInfo
• type ExtendedError
• type LookupError
  • func (e *LookupError) Error() string
  • func (e *LookupError) Unwrap() error
• type Options
• type QueryFlags
• type QueryFunc
• type Question
• type Resolver
  • func LoadResolvers(opts Options) ([]Resolver, error)
  • func NewClassicResolver(server string, classicOpts ClassicResolverOpts, resolverOpts Options) (Resolver, error)
  • func NewDNSCryptResolver(server string, dnscryptOpts DNSCryptResolverOpts, resolverOpts Options) (Resolver, error)
  • func NewDOHResolver(server string, resolverOpts Options) (Resolver, error)
  • func NewDOQResolver(server string, resolverOpts Options) (Resolver, error)
• type Response
  • func ConcurrentLookup(ctx context.Context, questions []dns.Question, flags QueryFlags, ...) ([]Response, error)

Functions

func CloseResolvers

func CloseResolvers(resolvers []Resolver) error

CloseResolvers closes resolver-owned resources and joins any close errors. Resolvers without a Close method don't own persistent resources.

Types

type Answer

type Answer struct {
	Name       string `json:"name"`
	Type       string `json:"type"`
	Class      string `json:"class"`
	TTL        string `json:"ttl"`
	Address    string `json:"address"`
	Status     string `json:"status"`
	RTT        string `json:"rtt"`
	Nameserver string `json:"nameserver"`
}

type Authority

type Authority struct {
	Name       string `json:"name"`
	Type       string `json:"type"`
	Class      string `json:"class"`
	TTL        string `json:"ttl"`
	MName      string `json:"mname"`
	Status     string `json:"status"`
	RTT        string `json:"rtt"`
	Nameserver string `json:"nameserver"`
}

type ClassicResolver

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

ClassicResolver represents the config options for setting up a Resolver.

func (*ClassicResolver) Address

func (r *ClassicResolver) Address() string

Address implements the Resolver interface.

func (*ClassicResolver) Lookup

func (r *ClassicResolver) Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)

Lookup implements the Resolver interface

type ClassicResolverOpts

type ClassicResolverOpts struct {
	UseTLS bool
	UseTCP bool
}

ClassicResolverOpts holds options for setting up a Classic resolver.

type DNSCryptResolver

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

DNSCryptResolver represents the config options for setting up a Resolver.

func (*DNSCryptResolver) Address

func (r *DNSCryptResolver) Address() string

Address implements the Resolver interface.

func (*DNSCryptResolver) Lookup

func (r *DNSCryptResolver) Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)

Lookup implements the Resolver interface

type DNSCryptResolverOpts

type DNSCryptResolverOpts struct {
	UseTCP bool
}

DNSCryptResolverOpts holds options for setting up a DNSCrypt resolver.

type DOHResolver

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

DOHResolver represents the config options for setting up a DOH based resolver.

func (*DOHResolver) Address

func (r *DOHResolver) Address() string

Address implements the Resolver interface.

func (*DOHResolver) Close

func (r *DOHResolver) Close() error

Close releases connections and sockets owned by the HTTP transport.

func (*DOHResolver) Lookup

func (r *DOHResolver) Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)

Lookup implements the Resolver interface

type DOQResolver

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

DOQResolver represents the config options for setting up a DOQ based resolver.

func (*DOQResolver) Address

func (r *DOQResolver) Address() string

Address implements the Resolver interface.

func (*DOQResolver) Lookup

func (r *DOQResolver) Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)

Lookup implements the Resolver interface

type EdnsInfo

type EdnsInfo struct {
	Nameserver  string `json:"nameserver,omitempty"`
	NSID        string `json:"nsid,omitempty"`
	Cookie      string `json:"cookie,omitempty"`
	Subnet      string `json:"subnet,omitempty"`
	SubnetScope uint8  `json:"subnet_scope,omitempty"`
	// ExtendedErr is retained for JSON compatibility and contains the first
	// EDE option. ExtendedErrors is the authoritative ordered representation.
	ExtendedErr    string          `json:"extended_error,omitempty"`
	ExtendedErrors []ExtendedError `json:"extended_errors,omitempty"`
	UDPSize        uint16          `json:"udp_size,omitempty"`
	DNSSECOk       bool            `json:"dnssec_ok,omitempty"`
}

type ExtendedError

type ExtendedError struct {
	Code        uint16 `json:"code"`
	Description string `json:"description,omitempty"`
	ExtraText   string `json:"extra_text,omitempty"`
}

type LookupError

type LookupError struct {
	Nameserver string
	Err        error
}

LookupError tags a resolver failure with the nameserver that produced it so partial failures can be reported per-resolver instead of as an opaque top-level error.

func (*LookupError) Error

func (e *LookupError) Error() string

func (*LookupError) Unwrap

func (e *LookupError) Unwrap() error

type Options

type Options struct {
	Logger *slog.Logger

	Nameservers        []models.Nameserver
	UseIPv4            bool
	UseIPv6            bool
	UseHTTP3           bool
	SearchList         []string
	Ndots              int
	Timeout            time.Duration
	Strategy           string
	InsecureSkipVerify bool
	TLSHostname        string
}

Options represent a set of common options to configure a Resolver.

type QueryFlags

type QueryFlags struct {
	AA bool // Authoritative Answer
	AD bool // Authenticated Data
	CD bool // Checking Disabled
	RD bool // Recursion Desired
	Z  bool // Reserved for future use
	DO bool // DNSSEC OK

	// EDNS0 options
	NSID    bool   // Request Name Server Identifier
	Cookie  bool   // Request DNS Cookie
	Padding bool   // Request EDNS padding for privacy
	EDE     bool   // Enable EDNS to receive Extended DNS Errors
	ECS     string // EDNS Client Subnet (e.g., "192.0.2.0/24" or "2001:db8::/32")
	Bufsize uint16 // EDNS UDP buffer size (default: 1232 when EDNS enabled)
}

QueryFlags represents the various DNS query flags

type QueryFunc

type QueryFunc func(ctx context.Context, question dns.Question, flags QueryFlags) (Response, error)

QueryFunc represents the signature of a query function

type Question

type Question struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Class string `json:"class"`
}

type Resolver

type Resolver interface {
	// Address returns the nameserver identity used when reporting errors.
	Address() string
	Lookup(ctx context.Context, questions []dns.Question, flags QueryFlags) ([]Response, error)
}

Resolver implements the configuration for a DNS Client. Different types of providers can load a DNS Resolver satisfying this interface.

func LoadResolvers

func LoadResolvers(opts Options) ([]Resolver, error)

LoadResolvers loads differently configured resolvers based on a list of nameserver.

func NewClassicResolver

func NewClassicResolver(server string, classicOpts ClassicResolverOpts, resolverOpts Options) (Resolver, error)

NewClassicResolver accepts a list of nameservers and configures a DNS resolver.

func NewDNSCryptResolver

func NewDNSCryptResolver(server string, dnscryptOpts DNSCryptResolverOpts, resolverOpts Options) (Resolver, error)

NewDNSCryptResolver accepts a list of nameservers and configures a DNS resolver.

func NewDOHResolver

func NewDOHResolver(server string, resolverOpts Options) (Resolver, error)

NewDOHResolver accepts a nameserver address and configures a DOH based resolver.

func NewDOQResolver

func NewDOQResolver(server string, resolverOpts Options) (Resolver, error)

NewDOQResolver accepts a nameserver address and configures a DOQ based resolver.

type Response

type Response struct {
	Answers     []Answer    `json:"answers"`
	Authorities []Authority `json:"authorities"`
	Questions   []Question  `json:"questions"`
	Additional  []Answer    `json:"additional,omitempty"`
	Edns        *EdnsInfo   `json:"edns,omitempty"`
}

Response represents a custom output format for DNS queries. It wraps metadata about the DNS query and the DNS Answer as well.

func ConcurrentLookup

func ConcurrentLookup(ctx context.Context, questions []dns.Question, flags QueryFlags, queryFunc QueryFunc, logger *slog.Logger) ([]Response, error)

ConcurrentLookup performs concurrent DNS lookups across multiple questions against a single resolver. It always waits for all in-flight goroutines so completed work is never discarded when the context is cancelled or expires mid-flight; callers receive whatever responses finished plus a joined error describing any per-question failures.