resolver

package
v0.28.0 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrDNSNoData = errDNSNoData

ErrDNSNoData is returned when an authenticated DNS response contains no records of the requested type.

View Source 
var ErrDOHProtocolIncompatible = errors.New("DoH endpoint does not support DNS wire messages")

ErrDOHProtocolIncompatible indicates that a DoH endpoint clearly does not implement RFC 8484 wire messages. Only this error permits JSON fallback.

View Source 
var ErrHTTPSRecordsUnavailable = errors.New("HTTPS record discovery is unavailable")

ErrHTTPSRecordsUnavailable means that the selected resolver cannot query HTTPS records. Callers may use ordinary ALPN negotiation in this case.

Functions

func ECHPublicName added in v0.28.0 

func ECHPublicName(value []byte) (string, error)

ECHPublicName returns the public name from the first supported ECH config. The list is validated before the name is extracted, so callers never parse attacker-controlled offsets without the same framing checks used by TLS.

func EncodeQuery added in v0.28.0 

func EncodeQuery(name string, typ uint16) ([]byte, uint16, error)

EncodeQuery creates a recursive query with a cryptographically random ID and an EDNS(0) OPT record sized for the usual DNS UDP payload.

func EncodeQueryWithID added in v0.28.0 

func EncodeQueryWithID(id uint16, name string, typ uint16) ([]byte, uint16, error)

EncodeQueryWithID is deterministic for tests and for transports that need to correlate a caller-selected transaction ID.

func IsAuthenticatedDiscoveryFailure added in v0.28.0 

func IsAuthenticatedDiscoveryFailure(err error) bool

MayDowngrade reports whether ordinary ALPN negotiation is allowed after an HTTPS discovery failure. Authenticated NODATA and NXDOMAIN are normal DNS outcomes; authenticated transport, parsing, and server failures are not.

func MayDowngrade added in v0.28.0 

func MayDowngrade(err error) bool

func RCodeName added in v0.28.0 

func RCodeName(code uint16) string

RCodeName returns a stable name for ordinary and EDNS extended response codes. Unknown values are retained as a numeric name.

func RaceCandidates added in v0.28.0 

func RaceCandidates[T any](ctx context.Context, candidates []net.IPAddr, attempt func(context.Context, net.IPAddr) (T, error), closeResult func(T)) (T, error)

RaceCandidates starts address attempts with a bounded Happy Eyeballs delay. The caller controls the transport attempt and loser cleanup, so the same policy works for TCP, TLS, and QUIC. The candidate order is significant: callers should put their preferred address family first.

func RecordAddress added in v0.28.0 

func RecordAddress(record Record) net.IP

RecordAddress returns an address from an A or AAAA record.

func SupportedECHConfigList added in v0.28.0 

func SupportedECHConfigList(value []byte) ([]byte, error)

SupportedECHConfigList returns a TLS-ready ECHConfigList after strict validation and unsupported-version filtering.

func ValidateRData added in v0.28.0 

func ValidateRData(typ uint16, rdata []byte) error

ValidateRData applies the same strict per-type RDATA checks used by the message decoder to an independently obtained RDATA slice.

func ValidateSVCBRRSet added in v0.28.0 

func ValidateSVCBRRSet(records []Record) error

ValidateSVCBRRSet rejects an HTTPS/SVCB RRset atomically without exposing a partially validated result.

Types

type AddressLookup added in v0.28.0 

type AddressLookup func(context.Context, string) ([]net.IPAddr, error)

AddressLookup resolves the A and AAAA records for name.

type BootstrapFunc added in v0.28.0 

type BootstrapFunc func(context.Context, string) ([]net.IPAddr, error)

BootstrapFunc resolves a resolver endpoint hostname. It must use a resolver other than the endpoint being bootstrapped.

type Config 

type Config struct {
	Endpoint *Endpoint
	Server   *url.URL

	// SystemLookupIPAddr replaces the platform resolver in deterministic tests.
	// Production callers leave it nil so net.Resolver remains authoritative for
	// ordinary system A/AAAA lookups.
	SystemLookupIPAddr func(context.Context, string) ([]net.IPAddr, error)

	// The stream hooks are used by DNS-over-TCP and DNS-over-TLS. They keep
	// resolver endpoint bootstrap and dialing injectable without coupling this
	// package to the application client.
	DialContext DialContextFunc
	Bootstrap   BootstrapFunc
	// RoundTripper is used only by DoH. It lets the application inject its
	// resolver-aware HTTP transport without duplicating DoH logic.
	RoundTripper http.RoundTripper
	// Proxy is applied to DoH endpoint requests. The endpoint bootstrap still
	// uses the platform resolver because resolving a custom resolver through
	// itself would recurse.
	Proxy func(*http.Request) (*url.URL, error)
	// SystemPolicy supplies OS resolver-file policy for HTTPS/SVCB discovery
	// when no custom endpoint is configured. A nil value uses the platform
	// resolv.conf path lazily.
	SystemPolicy *SystemResolverPolicy
	TLSConfig    *tls.Config
	CACerts      []*x509.Certificate
	ClientCert   *tls.Certificate
	Insecure     bool
	TLSMin       uint16
	TLSMax       uint16
}

Config controls hostname resolution. Endpoint is the validated resolver configuration used by production callers. Server is retained for callers that construct resolver test fixtures directly.

type DNSRecord 

type DNSRecord struct {
	IP         net.IP
	TTL        int
	TTLPresent bool
}

DNSRecord is a resolved DNS answer with optional TTL metadata.

func LookupDOHType 

func LookupDOHType(ctx context.Context, serverURL *url.URL, host, dnsType string, answerType int) ([]DNSRecord, error)

LookupDOHType resolves one DNS record family through a DNS-over-HTTPS endpoint. RFC 8484 wire format is authoritative; JSON is retained only for endpoints that clearly do not implement the wire protocol.

type DOHClient added in v0.28.0 

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

DOHClient keeps one HTTP client, and therefore its connection pool, for a related set of DNS queries. It is safe for concurrent Lookup calls.

func NewDOHClient added in v0.28.0 

func NewDOHClient(cfg DOHConfig) (*DOHClient, error)

NewDOHClient creates an operation-scoped DoH client. It does not follow redirects: a redirect changes the resolver endpoint protocol and must not silently turn a failed wire request into an unrelated request.

func (*DOHClient) Close added in v0.28.0 

func (c *DOHClient) Close() error

Close releases idle connections from the transport owned by the DoH client. A transport supplied by the caller remains the caller's responsibility. Close is safe to call more than once.

func (*DOHClient) LookupInspectionType added in v0.28.0 

func (c *DOHClient) LookupInspectionType(ctx context.Context, host, dnsType string, answerType int) ([]DOHRecord, error)

LookupInspectionType performs the same wire-first query as LookupType but retains all validated record types for DNS inspection.

func (*DOHClient) LookupType added in v0.28.0 

func (c *DOHClient) LookupType(ctx context.Context, host, dnsType string, answerType int) ([]DNSRecord, error)

LookupType performs a wire-first query and permits JSON fallback only after the wire endpoint has made a clear protocol incompatibility response.

type DOHConfig added in v0.28.0 

type DOHConfig struct {
	Endpoint     *Endpoint
	ServerURL    *url.URL
	RoundTripper http.RoundTripper
	// RoundTripperOwned transfers responsibility for closing RoundTripper to
	// the returned client. Callers that inject a shared transport must leave
	// this false.
	RoundTripperOwned bool
	Proxy             func(*http.Request) (*url.URL, error)
	DialContext       DialContextFunc
	Bootstrap         BootstrapFunc
	TLSConfig         *tls.Config
	CACerts           []*x509.Certificate
	ClientCert        *tls.Certificate
	Insecure          bool
	TLSMin            uint16
	TLSMax            uint16
	Timeout           time.Duration
}

DOHConfig controls one DNS-over-HTTPS client. RoundTripper and DialContext are intentionally injectable: the application can provide its proxy and resolver-aware dial policy without duplicating DoH parsing and validation.

type DOHRecord added in v0.28.0 

type DOHRecord struct {
	Record     Record
	Data       string
	TTLPresent bool
}

DOHRecord retains the validated DNS record and the original JSON data when the endpoint uses the compatibility JSON representation. Data is empty for wire responses; callers should use Record in that case.

type DialContextFunc added in v0.28.0 

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

DialContextFunc opens a connection. It is injectable so encrypted DNS can share the application's dial policy without making resolver depend on the client package.

type DiscoveryError added in v0.28.0 

type DiscoveryError struct {
	Kind DiscoveryFailureKind
	Err  error
}

DiscoveryError keeps downgrade policy separate from error text. The wrapped error remains available to callers with errors.Is/errors.As.

func (*DiscoveryError) Error added in v0.28.0 

func (e *DiscoveryError) Error() string

func (*DiscoveryError) Unwrap added in v0.28.0 

func (e *DiscoveryError) Unwrap() error

type DiscoveryFailureKind added in v0.28.0 

type DiscoveryFailureKind uint8

DiscoveryFailureKind describes whether HTTPS discovery may safely be skipped. Authenticated protocol failures must not be silently downgraded. 

const (
	DiscoveryFailureUnknown DiscoveryFailureKind = iota
	DiscoveryFailureNODATA
	DiscoveryFailureNXDOMAIN
	DiscoveryFailureUnauthenticated
	DiscoveryFailureAuthenticated
)

func DiscoveryFailure added in v0.28.0 

func DiscoveryFailure(err error) DiscoveryFailureKind

DiscoveryFailure reports the policy classification of err.

type DoQClient added in v0.28.0 

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

DoQClient sends DNS queries over one operation-scoped QUIC connection. Each query uses a separate bidirectional stream, as required by RFC 9250.

func NewDoQClient added in v0.28.0 

func NewDoQClient(ctx context.Context, cfg DoQConfig) (*DoQClient, error)

NewDoQClient establishes a verified DNS-over-QUIC connection. Resolver endpoint hostnames are bootstrapped with cfg.Bootstrap, or with the system resolver when no hook is supplied. The bootstrap hook must not recursively use this DoQ endpoint.

func (*DoQClient) Close added in v0.28.0 

func (c *DoQClient) Close() error

Close terminates the operation-scoped QUIC connection and its UDP socket.

func (*DoQClient) Query added in v0.28.0 

func (c *DoQClient) Query(ctx context.Context, name string, typ uint16) (*Message, error)

Query sends one DNS query on its own bidirectional QUIC stream and validates the response against the transaction ID and question.

func (*DoQClient) QueryMany added in v0.28.0 

func (c *DoQClient) QueryMany(ctx context.Context, queries []Question) ([]*Message, error)

QueryMany pipelines concurrent queries over one DoQ connection and returns responses in input order.

type DoQConfig added in v0.28.0 

type DoQConfig = StreamConfig

DoQConfig is an alias for the transport-neutral stream configuration. The same endpoint bootstrap and TLS policy is used by DoT and DoQ.

type ECHConfigListInfo added in v0.28.0 

type ECHConfigListInfo struct {
	Raw                []byte
	Supported          []byte
	ConfigurationCount int
	UnsupportedCount   int
}

ECHConfigListInfo describes the framed ECH configurations advertised in an HTTPS/SVCB record. Configurations with an unknown version are preserved for diagnostics but are not usable by the current Go TLS client.

func ValidateECHConfigList added in v0.28.0 

func ValidateECHConfigList(value []byte) (ECHConfigListInfo, error)

ValidateECHConfigList validates the complete ECHConfigList framing and returns a copy of the list containing only configurations understood by the current client. A malformed known configuration invalidates the whole list; an unknown-version configuration is skipped only when another usable configuration remains.

type Endpoint 

type Endpoint struct {
	Transport      Transport
	ConnectHost    string
	Port           uint16
	Path           string
	RawPath        string
	RawQuery       string
	TLSServerName  string
	BootstrapAddrs []net.IP
	VerifyTLS      bool
	Security       Security
	Display        string
}

Endpoint is the transport-neutral configuration for a DNS resolver.

ConnectHost is kept separate from TLSServerName because a future dialer may connect to an explicit bootstrap address while still verifying the resolver hostname. BootstrapAddrs contains addresses that are safe to use without a recursive lookup through this endpoint.

func ParseEndpoint added in v0.28.0 

func ParseEndpoint(value string) (*Endpoint, error)

ParseEndpoint parses a resolver endpoint. It accepts bare UDP endpoints and the explicit UDP, TCP, DoT, DoQ, and DoH forms described by the CLI contract. DoH must use HTTPS; test transports can use ParseEndpointURL with an explicit opt-in when they need a local plaintext HTTP server.

func ParseEndpointURL added in v0.28.0 

func ParseEndpointURL(value string, allowInsecureHTTPS bool) (*Endpoint, error)

ParseEndpointURL parses a URL supplied by an internal test transport. The allowInsecureHTTPS flag permits http:// for local DoH fixtures only. Normal CLI and config parsing must use ParseEndpoint.

func (*Endpoint) Address added in v0.28.0 

func (e *Endpoint) Address() string

Address returns the endpoint's network address.

func (*Endpoint) String added in v0.28.0 

func (e *Endpoint) String() string

String returns a canonical, secret-free display form.

func (*Endpoint) URL added in v0.28.0 

func (e *Endpoint) URL() *url.URL

URL returns a compatibility URL for code that has not yet migrated to the transport-neutral fields. New network code should use the endpoint fields.

type HTTPSDiscovery added in v0.28.0 

type HTTPSDiscovery struct {
	Origin            Name
	EffectiveTarget   Name
	Candidates        []ServiceCandidate
	FallbackAddresses []net.IPAddr
	FallbackPort      uint16
	TTL               uint32
	TTLPresent        bool
	Authenticated     bool
	Security          Security
}

HTTPSDiscovery is the result of following AliasMode and selecting usable ServiceMode records. EffectiveTarget is the final target used for service discovery, even when no usable ServiceMode record exists.

func ResolveHTTPS added in v0.28.0 

func ResolveHTTPS(ctx context.Context, host string, records HTTPSRecordLookup, addresses AddressLookup, options ServiceDiscoveryOptions) (HTTPSDiscovery, error)

ResolveHTTPS follows AliasMode chains and turns ServiceMode records into address candidates. It is independent of a particular DNS transport so all resolver implementations can share the same policy and tests can use a deterministic lookup fixture.

type HTTPSRecordLookup added in v0.28.0 

type HTTPSRecordLookup func(context.Context, string) ([]Record, error)

HTTPSRecordLookup returns the validated HTTPS records for name. The lookup must authorize owners and validate the complete RRset before returning. 

type Header struct {
	ID                 uint16
	Response           bool
	Opcode             uint8
	Authoritative      bool
	Truncated          bool
	RecursionDesired   bool
	RecursionAvailable bool
	RCode              uint16
}

Header contains the fields that are relevant to query correlation and response authorization. RCode includes the EDNS extended RCODE when an OPT record is present.

type Message added in v0.28.0 

type Message struct {
	Header      Header
	Questions   []Question
	Answers     []Record
	Authorities []Record
	Additionals []Record
}

Message is a decoded DNS message. Unknown record types remain opaque in Record.RData, but their owner, class, TTL, and bounds are still validated.

func DecodeMessage added in v0.28.0 

func DecodeMessage(packet []byte) (*Message, error)

DecodeMessage strictly decodes one DNS message.

func DecodeResponse added in v0.28.0 

func DecodeResponse(packet []byte, id uint16, question Question) (*Message, error)

DecodeResponse decodes and validates a response for one query.

func LookupDOHWireMessage added in v0.28.0 

func LookupDOHWireMessage(ctx context.Context, serverURL *url.URL, host string, answerType int) (*Message, error)

LookupDOHWireMessage performs one strict RFC 8484 query. It is used by DNS inspection so wire and address-resolution paths share validation.

func LookupDoQMessage added in v0.28.0 

func LookupDoQMessage(ctx context.Context, cfg DoQConfig, name string, typ uint16) (*Message, error)

LookupDoQMessage performs one operation-scoped DNS-over-QUIC query.

func LookupQUICMessage added in v0.28.0 

func LookupQUICMessage(ctx context.Context, cfg QUICConfig, name string, typ uint16) (*Message, error)

LookupQUICMessage is a descriptive alias for LookupDoQMessage.

func LookupStreamMessage added in v0.28.0 

func LookupStreamMessage(ctx context.Context, cfg StreamConfig, name string, typ uint16) (*Message, error)

LookupStreamMessage opens an operation-scoped stream, sends one query, and closes the stream after the response. Use NewStreamClient when related queries should be pipelined on one connection.

func LookupUDPMessage added in v0.28.0 

func LookupUDPMessage(ctx context.Context, serverAddr, host string, typ uint16) (*Message, bool, error)

LookupUDPMessage performs one UDP DNS transaction and, when the matching response is truncated, retries the same query over TCP. The boolean reports whether TCP fallback was used so diagnostic callers can explain the result.

func (*Message) ValidateResponse added in v0.28.0 

func (m *Message) ValidateResponse(id uint16, question Question) error

ValidateResponse checks the transaction, response flags, and exact question.

type Name added in v0.28.0 

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

Name is a DNS name in canonical wire-label form. Labels are opaque octets; comparison folds ASCII letters only, as required by DNS name comparison.

func ParseDNSName added in v0.28.0 

func ParseDNSName(value string) (Name, error)

ParseDNSName is an explicit alias for callers that prefer the protocol name.

func ParseName added in v0.28.0 

func ParseName(value string) (Name, error)

ParseName parses a presentation-format DNS name. A trailing dot is optional. Backslash escapes may quote one octet or use the RFC 4343 three-digit form.

func (Name) Equal added in v0.28.0 

func (n Name) Equal(other Name) bool

Equal compares names using DNS ASCII case-insensitive semantics.

func (Name) String added in v0.28.0 

func (n Name) String() string

String returns an escaped presentation name that round-trips to the same wire labels. The root name is ".".

func (Name) Wire added in v0.28.0 

func (n Name) Wire() ([]byte, error)

Wire returns the uncompressed wire representation of the name.

type QUICConfig added in v0.28.0 

type QUICConfig = StreamConfig

QUICConfig is retained as a descriptive alias for callers that select the transport by protocol name.

type QUICDialFunc added in v0.28.0 

type QUICDialFunc func(context.Context, net.PacketConn, *net.UDPAddr, *tls.Config, *quic.Config) (*quic.Conn, error)

QUICDialFunc is the injectable QUIC connection operation used by DoQ. The packet connection is owned by the caller and must remain open until the returned connection is closed.

type Question added in v0.28.0 

type Question struct {
	Name  Name
	Type  uint16
	Class uint16
}

Question identifies the question to which a response belongs.

type Record added in v0.28.0 

type Record struct {
	Owner      Name
	Type       uint16
	Class      uint16
	TTL        uint32
	TTLPresent bool
	RData      []byte
	Target     *Name
	Target2    *Name
	Preference uint16
	Priority   uint16
	Weight     uint16
	Port       uint16
	SOAValues  [5]uint32
	TXT        [][]byte
	Params     []SVCParam
}

Record is a bounded DNS resource record. RData is always a copy limited to the record's declared length. Target is populated for records whose RDATA contains a DNS name.

func AuthorizeAddressAnswers added in v0.28.0 

func AuthorizeAddressAnswers(m *Message, question Question) ([]Record, error)

AuthorizeAddressAnswers filters AuthorizeAnswers to records that can supply an address or service candidate.

func AuthorizeAnswers added in v0.28.0 

func AuthorizeAnswers(m *Message, question Question) ([]Record, error)

AuthorizeAnswers returns answer records whose owners are the queried name or a bounded, validated CNAME successor. Unrelated answer and glue records are excluded. A reachable CNAME owner cannot also contain other answer data, and all CNAME records for one owner must agree on one target.

func QuerySystemHTTPS added in v0.28.0 

func QuerySystemHTTPS(ctx context.Context, policy SystemResolverPolicy, host string, typ uint16) ([]Record, error)

QuerySystemHTTPS queries the configured system resolver policy. It is kept separate from Resolver so callers can use it for automatic HTTP/3/ECH discovery without changing ordinary platform A/AAAA resolution.

type ResolvedEndpoint added in v0.28.0 

type ResolvedEndpoint struct {
	Host  string
	Port  string
	Addrs []net.IPAddr
}

ResolvedEndpoint contains a parsed host:port address and its resolved IP addresses.

type Resolver 

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

Resolver resolves names and dials addresses using the configured DNS backend.

func New 

func New(cfg Config) *Resolver

New returns a resolver for the provided config. Endpoint validation normally happens while CLI/config values are parsed. Server supports existing internal test fixtures and is converted once here for compatibility.

func (*Resolver) CacheIdentity added in v0.28.0 

func (r *Resolver) CacheIdentity() string

CacheIdentity is a canonical, secret-free identity for persistent caches. Provenance is intended for display and deliberately omits fields such as a DoH query. Cache identity includes every resolver endpoint field that can change the answer source or its verification policy.

func (*Resolver) Close added in v0.28.0 

func (r *Resolver) Close() error

Close releases resources owned by the resolver. It is safe to call more than once; externally supplied DoH transports remain the caller's responsibility.

func (*Resolver) DialContext 

func (r *Resolver) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext resolves address and dials each returned IP until one succeeds. DialContext resolves address and races its candidates with the shared Happy Eyeballs policy. The first address retains the resolver's preferred family; later candidates are interleaved by ResolveAddress.

func (*Resolver) DiscoverHTTPS added in v0.28.0 

func (r *Resolver) DiscoverHTTPS(ctx context.Context, host string, defaultPort uint16, randomInt func(int) int) (HTTPSDiscovery, error)

DiscoverHTTPS follows the configured resolver's HTTPS AliasMode and returns effective service/address candidates for the supplied origin.

func (*Resolver) DiscoverSVCB added in v0.28.0 

func (r *Resolver) DiscoverSVCB(ctx context.Context, host string, defaultPort uint16, randomInt func(int) int) (HTTPSDiscovery, error)

DiscoverSVCB follows SVCB AliasMode with the same candidate and downgrade policy as HTTPS discovery.

func (*Resolver) DiscoverService added in v0.28.0 

func (r *Resolver) DiscoverService(ctx context.Context, host string, typ uint16, defaultPort uint16, randomInt func(int) int) (HTTPSDiscovery, error)

DiscoverService follows the selected HTTPS/SVCB record type through the configured resolver. The returned OriginName values remain the original authority even when a service target is different.

func (*Resolver) LookupHTTPSRecords added in v0.28.0 

func (r *Resolver) LookupHTTPSRecords(ctx context.Context, host string) ([]Record, error)

LookupHTTPSRecords queries and authorizes one HTTPS RRset through the configured resolver. It is also useful to H3/ECH callers that need raw records without invoking the full candidate builder.

func (*Resolver) LookupIPAddr 

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

LookupIPAddr resolves host to IP addresses using the configured backend.

func (*Resolver) LookupSVCBRecords added in v0.28.0 

func (r *Resolver) LookupSVCBRecords(ctx context.Context, host string) ([]Record, error)

LookupSVCBRecords is the equivalent raw-record operation for SVCB queries.

func (*Resolver) NetResolver 

func (r *Resolver) NetResolver() *net.Resolver

NetResolver returns a net.Resolver for system or UDP DNS resolution. DoH, DoT, and DoQ resolution cannot be represented as a net.Resolver.

func (*Resolver) Provenance added in v0.28.0 

func (r *Resolver) Provenance() string

Provenance identifies the resolver policy that supplied addresses. It is intentionally display-oriented and contains no credentials.

func (*Resolver) ResolveAddress 

func (r *Resolver) ResolveAddress(ctx context.Context, network, address string) (ResolvedEndpoint, error)

ResolveAddress resolves the host portion of network address.

func (*Resolver) SetOwnedRoundTripper added in v0.28.0 

func (r *Resolver) SetOwnedRoundTripper(transport http.RoundTripper) error

SetOwnedRoundTripper replaces the operation-scoped DoH transport and makes the resolver responsible for closing it. It is intended for a transport created specifically for this resolver; shared caller transports should use SetRoundTripper instead.

func (*Resolver) SetRoundTripper added in v0.28.0 

func (r *Resolver) SetRoundTripper(transport http.RoundTripper) error

SetRoundTripper replaces the operation-scoped DoH transport after the application has assembled its proxy and resolver-aware dial policy. This avoids a package cycle while keeping DoH on the same proxy layer as normal requests.

type SVCBRecord added in v0.28.0 

type SVCBRecord struct {
	Owner                Name
	TTL                  uint32
	TTLPresent           bool
	Priority             uint16
	Target               Name
	Params               []SVCParam
	Mandatory            []uint16
	UnsupportedMandatory []uint16
	ALPN                 [][]byte
	NoDefaultALPN        bool
	Port                 uint16
	HasPort              bool
	IPv4Hints            []net.IP
	IPv6Hints            []net.IP
	ECH                  []byte
}

SVCBRecord is the validated service-binding form of an HTTPS or SVCB record. Params retains unknown optional parameters so callers can preserve them without guessing their meaning.

func ParseSVCBRData added in v0.28.0 

func ParseSVCBRData(raw []byte) (SVCBRecord, error)

ParseSVCBRData strictly parses one uncompressed SVCB/HTTPS RDATA value. It returns no partially parsed record on error.

func ParseSVCBRRSet added in v0.28.0 

func ParseSVCBRRSet(records []Record) ([]SVCBRecord, error)

ParseSVCBRRSet validates every record in an HTTPS or SVCB RRset before returning any of them. A single malformed record rejects the whole set.

func SortSVCBRecords added in v0.28.0 

func SortSVCBRecords(records []SVCBRecord, randomInt func(int) int) []SVCBRecord

SortSVCBRecords returns service records in priority order. Records with the same priority are shuffled with randomInt, which makes production selection unbiased while allowing deterministic tests. If randomInt is nil, crypto/rand supplies the shuffle values.

func (SVCBRecord) AdvertisesALPN added in v0.28.0 

func (r SVCBRecord) AdvertisesALPN(protocol string) bool

AdvertisesALPN reports whether the record contains the exact protocol ID.

func (SVCBRecord) IsAliasMode added in v0.28.0 

func (r SVCBRecord) IsAliasMode() bool

func (SVCBRecord) IsUsable added in v0.28.0 

func (r SVCBRecord) IsUsable() bool

IsUsable reports whether all mandatory parameters are understood by this implementation. An unknown optional parameter does not make a record unusable.

type SVCParam added in v0.28.0 

type SVCParam struct {
	Key   uint16
	Value []byte
}

SVCParam retains an SVCB/HTTPS parameter without interpreting unknown keys.

type Security added in v0.28.0 

type Security string

Security describes the transport's protection against network observers and endpoint impersonation. Resolver authentication is separate from the authentication of DNS answers. 

const (
	SecurityPlaintext         Security = "plaintext/unauthenticated"
	SecurityVerifiedEncrypted Security = "certificate-verified encrypted"
	SecurityUnverifiedEncrypt Security = "encrypted but verification disabled"
)

type ServiceCandidate added in v0.28.0 

type ServiceCandidate struct {
	OriginName    Name
	TargetName    Name
	Priority      uint16
	Port          uint16
	ALPN          [][]byte
	NoDefaultALPN bool
	ECH           []byte
	Hints         []net.IPAddr
	Addresses     []net.IPAddr
	TTL           uint32
	TTLPresent    bool
}

ServiceCandidate is an effective HTTPS/SVCB service candidate. OriginName is the name used for HTTP authority and TLS SNI. TargetName is the name whose service is used for dialing and address resolution.

type ServiceDiscoveryOptions added in v0.28.0 

type ServiceDiscoveryOptions struct {
	DefaultPort   uint16
	MaxAliasDepth int
	RandomInt     func(int) int
	AddressLookup AddressLookup
	// Authenticated marks errors returned by a certificate-verified DNS
	// transport. It controls downgrade policy for parsing and address errors.
	Authenticated bool
}

ServiceDiscoveryOptions controls the resolver-independent discovery engine. DefaultPort is used when a service record does not advertise port 443.

type StreamClient added in v0.28.0 

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

StreamClient pipelines DNS queries over one stream and correlates responses by transaction ID. Query may be called concurrently.

func NewStreamClient added in v0.28.0 

func NewStreamClient(ctx context.Context, cfg StreamConfig) (*StreamClient, error)

NewStreamClient opens a pipelined TCP or TLS DNS connection. The endpoint must use tcp://, tls://, or dot://. Endpoint hostnames are bootstrapped via cfg.Bootstrap or the platform resolver, never through the endpoint itself.

func (*StreamClient) Close added in v0.28.0 

func (c *StreamClient) Close() error

Close stops the reader and fails all pending queries. It is safe to call more than once.

func (*StreamClient) Query added in v0.28.0 

func (c *StreamClient) Query(ctx context.Context, name string, typ uint16) (*Message, error)

Query sends one query and waits for its correlated response. Multiple Query calls may share the connection and responses may arrive in any order.

func (*StreamClient) QueryMany added in v0.28.0 

func (c *StreamClient) QueryMany(ctx context.Context, queries []Question) ([]*Message, error)

QueryMany pipelines all queries on one connection and returns responses in input order. It is useful to inspection and related A/AAAA discovery.

type StreamConfig added in v0.28.0 

type StreamConfig struct {
	Endpoint    *Endpoint
	DialContext DialContextFunc
	Bootstrap   BootstrapFunc
	TLSConfig   *tls.Config
	CACerts     []*x509.Certificate
	ClientCert  *tls.Certificate
	Insecure    bool
	TLSMin      uint16
	TLSMax      uint16

	// QUICDial optionally replaces the default quic-go dial operation. It is
	// useful for deterministic tests and for callers that provide a shared
	// packet-dial policy. It is ignored by TCP and TLS transports.
	QUICDial QUICDialFunc
}

StreamConfig controls one bounded DNS-over-TCP or DNS-over-TLS connection. The connection is intentionally operation-scoped. It is not a global pool.

type SystemResolverPolicy added in v0.28.0 

type SystemResolverPolicy struct {
	Nameservers []string
	Attempts    int
	Timeout     time.Duration
	Rotate      bool

	// UseSystemdResolved prefers resolvectl on Linux. Tests can disable it or
	// provide a resolv.conf path without depending on the host's resolver.
	UseSystemdResolved bool
	ResolvConfPath     string
}

SystemResolverPolicy describes the portable subset of resolv.conf policy that can be applied to raw HTTPS/SVCB queries. A/AAAA queries still use the platform resolver API, which preserves NSS and OS-specific routing.

func LoadSystemResolverPolicy added in v0.28.0 

func LoadSystemResolverPolicy(path string) (SystemResolverPolicy, error)

LoadSystemResolverPolicy reads a resolver configuration file using the supported system policy subset. It does not fail because one nameserver line is malformed; callers receive an error only when the file itself is unavailable.

func ParseResolvConf added in v0.28.0 

func ParseResolvConf(data string) SystemResolverPolicy

ParseResolvConf parses nameservers and the supported resolver options from a resolv.conf-like document. Invalid nameserver entries are skipped so one malformed line does not discard usable resolver policy.

type Transport added in v0.28.0 

type Transport string

Transport identifies the protocol used to send DNS queries to an endpoint. 

const (
	TransportUDP   Transport = "udp"
	TransportTCP   Transport = "tcp"
	TransportTLS   Transport = "tls"
	TransportQUIC  Transport = "quic"
	TransportHTTPS Transport = "https"
)

Source Files

View all Source files

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.