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 github.com/chillum/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() {
    clearUnused := true
    t := time.NewTicker(5 * time.Minute)
    defer t.Stop()
    for range t.C {
        resolver.Refresh(clearUnused)
    }
}()

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

r := &dnscache.Resolver{}
t := &http.Transport{DialContext: r.Dial}

Please note that for now the Dial function is rather minimalistic and there are some restrictions. Consult godoc for limitations. If you need extra functionality, but don't want to modify the library, you can specify it inline like:

r := &dnscache.Resolver{}
t := &http.Transport{
    DialContext: func(ctx context.Context, network string, addr string) (conn net.Conn, err error) {
        separator := strings.LastIndex(addr, ":")
        ips, err := r.LookupHost(ctx, addr[:separator])
        if err != nil {
            return nil, err
        }
        for _, ip := range ips {
            conn, err = net.Dial(network, ip+addr[separator:])
            if err == nil {
                break
            }
        }
        return
    },
}

Documentation

Index

• type Resolver
  • func (r *Resolver) Dial(ctx context.Context, network string, addr string) (conn net.Conn, err error)
  • 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)

Types

type Resolver

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

	// Resolver is the net.Resolver used to perform actual DNS lookup. If nil,
	// net.DefaultResolver is used instead.
	Resolver *net.Resolver
	// contains filtered or unexported fields
}

Resolver adds a DNS cache layer to Go's net.Resolver.

func (*Resolver) Dial

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

Dial is a function to use in DialContext for http.Transport. It looks up the host via Resolver and passes it to net.Dial.

Be warned that this is a simplistic implementation and misses a lot of features like dual stack support, correct handling of context tracing, randomization of adds etc. This implementation will also choke on "unix", "unixgram" and "unixpacket" network.

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)

Refresh refreshes cached entries which has been used at least once since the last Refresh. If clearUnused is true, entries which hasn't be used since the last Refresh are removed from the cache.