mockdns

README

go-mockdns

Boilerplate for testing of code involving DNS lookups, including unholy hacks to redirect net.Lookup* calls.

Example

Trivial mock resolver, for cases where tested code supports custom resolvers:

r := mockdns.Resolver{
    Zones: map[string]mockdns.Zone{
        "example.org.": {
            A: []string{"1.2.3.4"},
        },
    },
}

addrs, err := r.LookupHost(context.Background(), "example.org")
fmt.Println(addrs, err)

// Output:
// [1.2.3.4] <nil>

Unholy hack for cases where it doesn't:

srv, _ := mockdns.NewServer(map[string]mockdns.Zone{
    "example.org.": {
        A: []string{"1.2.3.4"},
    },
}, false)
defer srv.Close()

srv.PatchNet(net.DefaultResolver)
defer mockdns.UnpatchNet(net.DefaultResolver)

addrs, err := net.LookupHost("example.org")
fmt.Println(addrs, err)

// Output:
// [1.2.3.4] <nil>

Note, if you need to replace net.Dial calls and tested code supports custom net.Dial, patch the resolver object inside it instead of net.DefaultResolver. If tested code supports Dialer-like objects - use Resolver itself, it implements Dial and DialContext methods.

Documentation

Index

• func UnpatchNet(r *net.Resolver)
• type Logger
• type Resolver
  • func (r *Resolver) Dial(network, addr string) (net.Conn, error)
  • func (r *Resolver) DialContext(ctx context.Context, network, addr string) (net.Conn, error)
  • func (r *Resolver) LookupAddr(ctx context.Context, addr string) (names []string, err error)
  • func (r *Resolver) LookupCNAME(ctx context.Context, host string) (cname string, err error)
  • func (r *Resolver) LookupHost(ctx context.Context, host string) (addrs []string, err error)
  • func (r *Resolver) LookupIP(ctx context.Context, network, host string) ([]net.IP, error)
  • func (r *Resolver) LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)
  • func (r *Resolver) LookupMX(ctx context.Context, name string) ([]*net.MX, error)
  • func (r *Resolver) LookupNS(ctx context.Context, name string) ([]*net.NS, error)
  • func (r *Resolver) LookupNetIP(ctx context.Context, network, host string) ([]netip.Addr, error)
  • func (r *Resolver) LookupPort(ctx context.Context, network, service string) (port int, err error)
  • func (r *Resolver) LookupSRV(ctx context.Context, service, proto, name string) (cname string, addrs []*net.SRV, err error)
  • func (r *Resolver) LookupTXT(ctx context.Context, name string) ([]string, error)
• type Server
  • func NewServer(zones map[string]Zone, authoritative bool) (*Server, error)
  • func NewServerWithLogger(zones map[string]Zone, l Logger, authoritative bool) (*Server, error)
  • func (s *Server) Close() error
  • func (s *Server) LocalAddr() net.Addr
  • func (s *Server) PatchNet(r *net.Resolver)
  • func (s *Server) Resolver() *Resolver
  • func (s *Server) ServeDNS(w dns.ResponseWriter, m *dns.Msg)
• type Zone

Examples

• Resolver
• Server.PatchNet

Functions

func UnpatchNet

func UnpatchNet(r *net.Resolver)

Types

type Logger

type Logger interface {
	Printf(f string, args ...interface{})
}

type Resolver

type Resolver struct {
	Zones map[string]Zone

	// Don't follow CNAME in Zones for Lookup*.
	SkipCNAME bool
}

Resolver is the struct that implements interface same as net.Resolver and so can be used as a drop-in replacement for it if tested code supports it.

Example

// Use for code that supports custom resolver implementations.
r := mockdns.Resolver{
	Zones: map[string]mockdns.Zone{
		"example.org.": {
			A: []string{"1.2.3.4"},
		},
	},
}

addrs, err := r.LookupHost(context.Background(), "example.org")
fmt.Println(addrs, err)

Output:

[1.2.3.4] <nil>

func (*Resolver) Dial

func (r *Resolver) Dial(network, addr string) (net.Conn, error)

Dial implements the function similar to net.Dial that uses Resolver zones to find the the IP address to use. It is very simple and does not fully replicate the net.Dial behavior. Notably it does not implement Fast Fallback and always prefers IPv6 over IPv4.

func (*Resolver) DialContext

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

func (*Resolver) LookupAddr

func (r *Resolver) LookupAddr(ctx context.Context, addr string) (names []string, err error)

func (*Resolver) LookupCNAME

func (r *Resolver) LookupCNAME(ctx context.Context, host string) (cname string, err error)

func (*Resolver) LookupHost

func (r *Resolver) LookupHost(ctx context.Context, host string) (addrs []string, err error)

func (*Resolver) LookupIP

func (r *Resolver) LookupIP(ctx context.Context, network, host string) ([]net.IP, error)

func (*Resolver) LookupIPAddr

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

func (*Resolver) LookupMX

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

func (*Resolver) LookupNS

func (r *Resolver) LookupNS(ctx context.Context, name string) ([]*net.NS, error)

func (*Resolver) LookupNetIP

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

func (*Resolver) LookupPort

func (r *Resolver) LookupPort(ctx context.Context, network, service string) (port int, err error)

func (*Resolver) LookupSRV

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

func (*Resolver) LookupTXT

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

type Server

type Server struct {
	Log           Logger
	Authoritative bool
	// contains filtered or unexported fields
}

Server is the wrapper that binds Resolver to the DNS server implementation from github.com/miekg/dns. This allows it to be used as a replacement resolver for testing code that doesn't support DNS callbacks. See PatchNet.

func NewServer

func NewServer(zones map[string]Zone, authoritative bool) (*Server, error)

func NewServerWithLogger

func NewServerWithLogger(zones map[string]Zone, l Logger, authoritative bool) (*Server, error)

func (*Server) Close

func (s *Server) Close() error

func (*Server) LocalAddr

func (s *Server) LocalAddr() net.Addr

LocalAddr returns the local endpoint used by the server. It will always be *net.UDPAddr, however it is also usable for TCP connections.

func (*Server) PatchNet

func (s *Server) PatchNet(r *net.Resolver)

PatchNet configures net.Resolver instance to use this Server object.

Use UnpatchNet to revert changes.

Example

// Use for code that directly calls net.Lookup*.
srv, _ := mockdns.NewServer(map[string]mockdns.Zone{
	"example.org.": {
		A: []string{"1.2.3.4"},
	},
}, false)
defer srv.Close()

srv.PatchNet(net.DefaultResolver)
// Important if net.DefaultResolver is modified.
defer mockdns.UnpatchNet(net.DefaultResolver)

addrs, err := net.LookupHost("example.org")
fmt.Println(addrs, err)

Output:

[1.2.3.4] <nil>

func (*Server) Resolver

func (s *Server) Resolver() *Resolver

Resolver returns the underlying Resolver object that can be used directly to access Zones content.

func (*Server) ServeDNS

func (s *Server) ServeDNS(w dns.ResponseWriter, m *dns.Msg)

ServeDNS implements miekg/dns.Handler. It responds with values from underlying Resolver object.

type Zone

type Zone struct {
	// Return the specified error on any lookup using this zone.
	// For Server, non-nil value results in SERVFAIL response.
	Err error

	// When used with Server, set the Authenticated Data (AD) flag
	// in the responses.
	AD bool

	A     []string
	AAAA  []string
	TXT   []string
	PTR   []string
	CNAME string
	MX    []net.MX
	NS    []net.NS
	SRV   []net.SRV

	// Misc includes other associated zone records, they can be returned only
	// when used with Server.
	Misc map[dns.Type][]dns.RR
}