Documentation
¶
Overview ¶
Package dns helps parse internationalized domain names (IDNA), canonicalize names and provides a strict and metrics-keeping logging DNS resolver.
Index ¶
- Variables
- func IsNotFound(err error) bool
- type Domain
- type IPDomain
- type MockResolver
- func (r MockResolver) LookupAddr(ctx context.Context, ip string) ([]string, adns.Result, error)
- func (r MockResolver) LookupCNAME(ctx context.Context, name string) (string, adns.Result, error)
- func (r MockResolver) LookupHost(ctx context.Context, host string) ([]string, adns.Result, error)
- func (r MockResolver) LookupIP(ctx context.Context, network, host string) ([]net.IP, adns.Result, error)
- func (r MockResolver) LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, adns.Result, error)
- func (r MockResolver) LookupMX(ctx context.Context, name string) ([]*net.MX, adns.Result, error)
- func (r MockResolver) LookupNS(ctx context.Context, name string) ([]*net.NS, adns.Result, error)
- func (r MockResolver) LookupPort(ctx context.Context, network, service string) (port int, err error)
- func (r MockResolver) LookupSRV(ctx context.Context, service, proto, name string) (string, []*net.SRV, adns.Result, error)
- func (r MockResolver) LookupTLSA(ctx context.Context, port int, protocol string, host string) ([]adns.TLSA, adns.Result, error)
- func (r MockResolver) LookupTXT(ctx context.Context, name string) ([]string, adns.Result, error)
- type Resolver
- type StrictResolver
- func (r StrictResolver) LookupAddr(ctx context.Context, addr string) (resp []string, result adns.Result, err error)
- func (r StrictResolver) LookupCNAME(ctx context.Context, host string) (resp string, result adns.Result, err error)
- func (r StrictResolver) LookupHost(ctx context.Context, host string) (resp []string, result adns.Result, err error)
- func (r StrictResolver) LookupIP(ctx context.Context, network, host string) (resp []net.IP, result adns.Result, err error)
- func (r StrictResolver) LookupIPAddr(ctx context.Context, host string) (resp []net.IPAddr, result adns.Result, err error)
- func (r StrictResolver) LookupMX(ctx context.Context, name string) (resp []*net.MX, result adns.Result, err error)
- func (r StrictResolver) LookupNS(ctx context.Context, name string) (resp []*net.NS, result adns.Result, err error)
- func (r StrictResolver) LookupPort(ctx context.Context, network, service string) (resp int, err error)
- func (r StrictResolver) LookupSRV(ctx context.Context, service, proto, name string) (resp0 string, resp1 []*net.SRV, result adns.Result, err error)
- func (r StrictResolver) LookupTLSA(ctx context.Context, port int, protocol, host string) (resp []adns.TLSA, result adns.Result, err error)
- func (r StrictResolver) LookupTXT(ctx context.Context, name string) (resp []string, result adns.Result, err error)
- func (r StrictResolver) WithPackage(name string) Resolver
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrRelativeDNSName = errors.New("dns: host to lookup must be absolute, ending with a dot")
var (
MetricLookup stub.HistogramVec = stub.HistogramVecIgnore{}
)
var Pedantic bool
Pedantic enables stricter parsing.
Functions ¶
func IsNotFound ¶
IsNotFound returns whether an error is an adns.DNSError with IsNotFound set. IsNotFound means the requested type does not exist for the given domain (a nodata or nxdomain response). It doesn't not necessarily mean no other types for that name exist.
A DNS server can respond to a lookup with an error "nxdomain" to indicate a name does not exist (at all), or with a success status with an empty list. The adns resolver (just like the Go resolver) returns an IsNotFound error for both cases, there is no need to explicitly check for zero entries.
Types ¶
type Domain ¶
type Domain struct { // A non-unicode domain, e.g. with A-labels (xn--...) or NR-LDH (non-reserved // letters/digits/hyphens) labels. Always in lower case. No trailing dot. ASCII string // Name as U-labels, in Unicode NFC. Empty if this is an ASCII-only domain. No // trailing dot. Unicode string }
Domain is a domain name, with one or more labels, with at least an ASCII representation, and for IDNA non-ASCII domains a unicode representation. The ASCII string must be used for DNS lookups. The strings do not have a trailing dot. When using with StrictResolver, add the trailing dot.
func ParseDomain ¶
ParseDomain parses a domain name that can consist of ASCII-only labels or U labels (unicode). Names are IDN-canonicalized and lower-cased. Characters in unicode can be replaced by equivalents. E.g. "Ⓡ" to "r". This means you should only compare parsed domain names, never unparsed strings directly.
Example ¶
package main import ( "fmt" "log" "github.com/mjl-/mox/dns" ) func main() { // ASCII-only domain. basic, err := dns.ParseDomain("example.com") if err != nil { log.Fatalf("parse domain: %v", err) } fmt.Printf("%s\n", basic) // IDNA domain xn--74h.example. smile, err := dns.ParseDomain("☺.example") if err != nil { log.Fatalf("parse domain: %v", err) } fmt.Printf("%s\n", smile) // ASCII only domain curl.se in surprisingly allowed spelling. surprising, err := dns.ParseDomain("ℂᵤⓇℒ。𝐒🄴") if err != nil { log.Fatalf("parse domain: %v", err) } fmt.Printf("%s\n", surprising) }
Output: example.com ☺.example/xn--74h.example curl.se
func ParseDomainLax ¶ added in v0.0.8
ParseDomainLax parses a domain like ParseDomain, but allows labels with underscores if the entire domain name is ASCII-only non-IDNA and Pedantic mode is not enabled. Used for interoperability, e.g. domains may specify MX targets with underscores.
func (Domain) ASCIIExtra ¶
ASCIIExtra returns the ASCII version of the domain name if smtputf8 is true and this is a unicode domain name. Otherwise it returns an empty string.
This function is used to add the punycode name in a comment to SMTP message headers, e.g. Received and Authentication-Results.
func (Domain) LogString ¶ added in v0.0.3
LogString returns a domain for logging. For IDNA names, the string is the slash-separated Unicode and ASCII name. For ASCII-only domain names, just the ASCII string is returned.
type IPDomain ¶
IPDomain is an ip address, a domain, or empty.
func (IPDomain) LogString ¶ added in v0.0.3
LogString returns a string with both ASCII-only and optional UTF-8 representation.
type MockResolver ¶
type MockResolver struct { PTR map[string][]string A map[string][]string AAAA map[string][]string TXT map[string][]string MX map[string][]*net.MX TLSA map[string][]adns.TLSA // Keys are e.g. _25._tcp.<host>. CNAME map[string]string Fail []string // Records of the form "type name", e.g. "cname localhost." that will return a servfail. AllAuthentic bool // Default value for authentic in responses. Overridden with Authentic and Inauthentic Authentic []string // Like Fail, but records that cause the response to be authentic. Inauthentic []string // Like Authentic, but making response inauthentic. }
MockResolver is a Resolver used for testing. Set DNS records in the fields, which map FQDNs (with trailing dot) to values.
func (MockResolver) LookupAddr ¶
func (MockResolver) LookupCNAME ¶
func (MockResolver) LookupHost ¶
func (MockResolver) LookupIPAddr ¶
func (MockResolver) LookupPort ¶
func (MockResolver) LookupTLSA ¶ added in v0.0.8
type Resolver ¶
type Resolver interface { LookupPort(ctx context.Context, network, service string) (port int, err error) LookupAddr(ctx context.Context, addr string) ([]string, adns.Result, error) // Always returns absolute names, with trailing dot. LookupCNAME(ctx context.Context, host string) (string, adns.Result, error) // NOTE: returns an error if no CNAME record is present. LookupHost(ctx context.Context, host string) ([]string, adns.Result, error) LookupIP(ctx context.Context, network, host string) ([]net.IP, adns.Result, error) LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, adns.Result, error) LookupMX(ctx context.Context, name string) ([]*net.MX, adns.Result, error) LookupNS(ctx context.Context, name string) ([]*net.NS, adns.Result, error) LookupSRV(ctx context.Context, service, proto, name string) (string, []*net.SRV, adns.Result, error) LookupTXT(ctx context.Context, name string) ([]string, adns.Result, error) LookupTLSA(ctx context.Context, port int, protocol, host string) ([]adns.TLSA, adns.Result, error) }
Resolver is the interface strict resolver implements.
func WithPackage ¶
WithPackage sets Pkg on resolver if it is a StrictResolve and does not have a package set yet.
type StrictResolver ¶
type StrictResolver struct { Pkg string // Name of subsystem that is making DNS requests, for metrics. Resolver *adns.Resolver // Where the actual lookups are done. If nil, adns.DefaultResolver is used for lookups. Log *slog.Logger }
StrictResolver is a net.Resolver that enforces that DNS names end with a dot, preventing "search"-relative lookups.
func (StrictResolver) LookupAddr ¶
func (StrictResolver) LookupCNAME ¶
func (r StrictResolver) LookupCNAME(ctx context.Context, host string) (resp string, result adns.Result, err error)
LookupCNAME looks up a CNAME. Unlike "net" LookupCNAME, it returns a "not found" error if there is no CNAME record.
func (StrictResolver) LookupHost ¶
func (StrictResolver) LookupIPAddr ¶
func (StrictResolver) LookupPort ¶
func (StrictResolver) LookupTLSA ¶ added in v0.0.8
func (StrictResolver) WithPackage ¶
func (r StrictResolver) WithPackage(name string) Resolver