dnsr

README

dnsr

Iterative DNS resolver for Go.

The Resolve method on dnsr.Resolver queries DNS for given name and type (A, NS, CNAME, etc.). The resolver caches responses for queries, and liberally (aggressively?) returns DNS records for a given name, not waiting for slow or broken name servers.

This code leans heavily on Miek Gieben’s excellent DNS library, and is currently in production use at Domainr.

Install

go get github.com/domainr/dnsr

Usage

package main

import (
  "fmt"
  "github.com/domainr/dnsr"
)

func main() {
  r := dnsr.NewResolver(dnsr.WithCache(10000))
  for _, rr := range r.Resolve("google.com", "TXT") {
    fmt.Println(rr.String())
  }
}

Or construct with dnsr.NewResolver(dnsr.WithExpiry()) to expire cache entries based on TTL.

Documentation

Development

Run go generate in Go 1.4+ to refresh the root zone hint file. Pull requests welcome.

Copyright

© nb.io, LLC

Documentation

Index

• Constants
• Variables
• type ContextDialer
• type Option
  • func WithCache(cap int) Option
  • func WithDialer(d ContextDialer) Option
  • func WithExpiry() Option
  • func WithTCPRetry() Option
  • func WithTimeout(timeout time.Duration) Option
• type RR
  • func (rr *RR) String() string
• type RRs
• type Resolver
  • func New(cap int) *Resolver
  • func NewExpiring(cap int) *Resolver
  • func NewExpiringWithTimeout(cap int, timeout time.Duration) *Resolver
  • func NewResolver(options ...Option) *Resolver
  • func NewWithTimeout(cap int, timeout time.Duration) *Resolver
  • func (r *Resolver) Resolve(qname, qtype string) RRs
  • func (r *Resolver) ResolveContext(ctx context.Context, qname, qtype string) (RRs, error)
  • func (r *Resolver) ResolveCtx(ctx context.Context, qname, qtype string) (RRs, error)
  • func (r *Resolver) ResolveErr(qname, qtype string) (RRs, error)

Constants

const MinCacheCapacity = 1000

const NameCollision = "127.0.53.53"

ICANN specifies that DNS servers should return the special value 127.0.53.53 for A record queries of TLDs that have recently entered the root zone, that have a high likelyhood of colliding with private DNS names. The record returned is a notice to network administrators to adjust their DNS configuration. https://www.icann.org/resources/pages/name-collision-2013-12-06-en#127.0.53.53

Variables

var (
	Timeout             = 2000 * time.Millisecond
	TypicalResponseTime = 100 * time.Millisecond
	MaxRecursion        = 10
	MaxNameservers      = 2
	MaxIPs              = 2
)

DNS Resolution configuration.

var (
	NXDOMAIN = fmt.Errorf("NXDOMAIN")

	ErrMaxRecursion = fmt.Errorf("maximum recursion depth reached: %d", MaxRecursion)
	ErrMaxIPs       = fmt.Errorf("maximum name server IPs queried: %d", MaxIPs)
	ErrNoARecords   = fmt.Errorf("no A records found for name server")
	ErrNoResponse   = fmt.Errorf("no responses received")
	ErrTimeout      = fmt.Errorf("timeout expired") // TODO: Timeouter interface? e.g. func (e) Timeout() bool { return true }
)

Resolver errors.

var DebugLogger io.Writer

DebugLogger will receive writes of DNS resolution traces if not nil.

Types

type ContextDialer

type ContextDialer interface {
	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
}

A ContextDialer implements the DialContext method, e.g. net.Dialer.

type Option

type Option func(*Resolver)

Option specifies a configuration option for a Resolver.

func WithCache

func WithCache(cap int) Option

WithCache specifies a cache with capacity cap.

func WithDialer

func WithDialer(d ContextDialer) Option

WithDialer specifies a network dialer.

func WithExpiry

func WithExpiry() Option

WithExpiry specifies that the Resolver will delete stale cache entries.

func WithTCPRetry

func WithTCPRetry() Option

WithTCPRetry specifies that requests should be retried with TCP if responses are truncated. The retry must still complete within the timeout or context deadline.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout specifies the timeout for network operations. The default value is Timeout.

type RR

type RR struct {
	Name   string
	Type   string
	Value  string
	TTL    time.Duration
	Expiry time.Time
}

RR represents a DNS resource record.

func (*RR) String

func (rr *RR) String() string

String returns a string representation of an RR in zone-file format.

type RRs

type RRs []RR

RRs represents a slice of DNS resource records.

type Resolver

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

Resolver implements a primitive, non-recursive, caching DNS resolver.

func New

func New(cap int) *Resolver

New initializes a Resolver with the specified cache size. Deprecated: use NewResolver with Option(s) instead.

func NewExpiring

func NewExpiring(cap int) *Resolver

NewExpiring initializes an expiring Resolver with the specified cache size. Deprecated: use NewResolver with Option(s) instead.

func NewExpiringWithTimeout

func NewExpiringWithTimeout(cap int, timeout time.Duration) *Resolver

NewExpiringWithTimeout initializes an expiring Resolved with the specified cache size and timeout. Deprecated: use NewResolver with Option(s) instead.

func NewResolver

func NewResolver(options ...Option) *Resolver

NewResolver returns an initialized Resolver with options. By default, the returned Resolver will have cache capacity 0 and the default network timeout (Timeout).

func NewWithTimeout

func NewWithTimeout(cap int, timeout time.Duration) *Resolver

NewWithTimeout initializes a Resolver with the specified cache size and timeout. Deprecated: use NewResolver with Option(s) instead.

func (*Resolver) Resolve

func (r *Resolver) Resolve(qname, qtype string) RRs

Resolve calls ResolveErr to find DNS records of type qtype for the domain qname. For nonexistent domains (NXDOMAIN), it will return an empty, non-nil slice.

func (*Resolver) ResolveContext

func (r *Resolver) ResolveContext(ctx context.Context, qname, qtype string) (RRs, error)

ResolveContext finds DNS records of type qtype for the domain qname using the supplied context. Requests may time out earlier if timeout is shorter than a deadline set in ctx. For nonexistent domains, it will return an NXDOMAIN error. Specify an empty string in qtype to receive any DNS records found (currently A, AAAA, NS, CNAME, SOA, and TXT).

func (*Resolver) ResolveCtx

func (r *Resolver) ResolveCtx(ctx context.Context, qname, qtype string) (RRs, error)

ResolveCtx finds DNS records of type qtype for the domain qname using the supplied context. Requests may time out earlier if timeout is shorter than a deadline set in ctx. For nonexistent domains, it will return an NXDOMAIN error. Specify an empty string in qtype to receive any DNS records found (currently A, AAAA, NS, CNAME, SOA, and TXT). Deprecated: use ResolveContext.

func (*Resolver) ResolveErr

func (r *Resolver) ResolveErr(qname, qtype string) (RRs, error)

ResolveErr finds DNS records of type qtype for the domain qname. For nonexistent domains, it will return an NXDOMAIN error. Specify an empty string in qtype to receive any DNS records found (currently A, AAAA, NS, CNAME, SOA, and TXT).