dnscache

README

DNS Lookup Cache

The dnscache package provides a DNS cache layer to Go's net.Resolver.

Install

Install using the "go get" command:

go get -u github.com/rs/dnscache

Usage

Create a new instance and use it in place of net.Resolver. New names will be cached. Call the Refresh method at regular interval to update cached entries and cleanup unused ones.

resolver := &dnscache.Resolver{}

// First call will cache the result
addrs, err := resolver.LookupHost(context.Background(), "example.com")

// Subsequent calls will use the cached result
addrs, err = resolver.LookupHost(context.Background(), "example.com")

// Call to refresh will refresh names in cache. If you pass true, it will also
// remove cached names not looked up since the last call to Refresh. It is a good idea
// to call this method on a regular interval.
go func() {
    t := time.NewTicker(5 * time.Minute)
    defer t.Stop()
    for range t.C {
        resolver.Refresh(true)
    }
}()

If you are using an http.Transport, you can use this cache by specifying a DialContext function:

r := &dnscache.Resolver{}
t := &http.Transport{
    DialContext: func(ctx context.Context, network string, addr string) (conn net.Conn, err error) {
        host, port, err := net.SplitHostPort(addr)
        if err != nil {
            return nil, err
        }
        ips, err := r.LookupHost(ctx, host)
        if err != nil {
            return nil, err
        }
        for _, ip := range ips {
            var dialer net.Dialer
            conn, err = dialer.DialContext(ctx, network, net.JoinHostPort(ip, port))
            if err == nil {
                break
            }
        }
        return
    },
}

In addition to the Refresh method, you can RefreshWithOptions. This method adds an option to persist resource records on failed lookups

r := &Resolver{}
options := dnscache.ResolverRefreshOptions{}
options.ClearUnused = true
options.PersistOnFailure = false
resolver.RefreshWithOptions(options)

Documentation

Overview

Example

r := &Resolver{}
t := &http.Transport{
	DialContext: func(ctx context.Context, network string, addr string) (conn net.Conn, err error) {
		host, port, err := net.SplitHostPort(addr)
		if err != nil {
			return nil, err
		}
		ips, err := r.LookupHost(ctx, host)
		if err != nil {
			return nil, err
		}
		for _, ip := range ips {
			var dialer net.Dialer
			conn, err = dialer.DialContext(ctx, network, net.JoinHostPort(ip, port))
			if err == nil {
				break
			}
		}
		return
	},
}
c := &http.Client{Transport: t}
res, err := c.Get("http://httpbin.org/status/418")
if err == nil {
	fmt.Println(res.StatusCode)
}

Output:

418

Index

• type DNSResolver
  • func NewResolverOnlyV4() DNSResolver
  • func NewResolverOnlyV6() DNSResolver
• type Resolver
  • func (r *Resolver) LookupAddr(ctx context.Context, addr string) (names []string, err error)
  • func (r *Resolver) LookupHost(ctx context.Context, host string) (addrs []string, err error)
  • func (r *Resolver) Refresh(clearUnused bool)
  • func (r *Resolver) RefreshWithOptions(options ResolverRefreshOptions)
• type ResolverRefreshOptions

Examples

• Package

Types

type DNSResolver

type DNSResolver interface {
	LookupHost(ctx context.Context, host string) (addrs []string, err error)
	LookupAddr(ctx context.Context, addr string) (names []string, err error)
}

func NewResolverOnlyV4

func NewResolverOnlyV4() DNSResolver

Create a new resolver that only resolves to IPv4 Addresses when looking up Hosts. Example:

resolver := dnscache.Resolver{
  Resolver: NewResolverOnlyV4(),
}

func NewResolverOnlyV6

func NewResolverOnlyV6() DNSResolver

Create a new resolver that only resolves to IPv6 Addresses when looking up Hosts. Example:

resolver := dnscache.Resolver{
  Resolver: NewResolverOnlyV6(),
}

type Resolver

type Resolver struct {
	// Timeout defines the maximum allowed time allowed for a lookup.
	Timeout time.Duration

	// Resolver is used to perform actual DNS lookup. If nil,
	// net.DefaultResolver is used instead.
	Resolver DNSResolver

	// OnCacheMiss is executed if the host or address is not included in
	// the cache and the default lookup is executed.
	OnCacheMiss func()
	// contains filtered or unexported fields
}

func (*Resolver) LookupAddr

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

LookupAddr performs a reverse lookup for the given address, returning a list of names mapping to that address.

func (*Resolver) LookupHost

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

LookupHost looks up the given host using the local resolver. It returns a slice of that host's addresses.

func (*Resolver) Refresh

func (r *Resolver) Refresh(clearUnused bool)

func (*Resolver) RefreshWithOptions

func (r *Resolver) RefreshWithOptions(options ResolverRefreshOptions)

type ResolverRefreshOptions

type ResolverRefreshOptions struct {
	ClearUnused      bool
	PersistOnFailure bool
}