dnscache

Documentation

Overview

Package dnscache implements github.com/Vonage/gosrvlib/pkg/sfcache to provide a simple, local, thread-safe, fixed-size, and single-flight cache for DNS lookup calls.

This package provides LookupHost() and DialContext() functions that can be used in place of the standard ones in the net package.

By caching previous values, dnscache improves DNS lookup performance by eliminating the need for repeated expensive requests.

This package provides a local in-memory cache with a configurable maximum number of entries. The fixed size helps with efficient memory management and prevents excessive memory usage. The cache is thread-safe, allowing concurrent access without the need for external synchronization. It efficiently handles concurrent requests by sharing results from the first lookup, ensuring only one request does the expensive call, and avoiding unnecessary network load or resource starvation. Duplicate calls for the same key will wait for the first call to complete and return the same value.

Each cache entry has a set time-to-live (TTL), so it will automatically expire. However, it is also possible to force the removal of a specific DNS entry or reset the entire cache.

This package is ideal for any Go application that relies heavily on DNS lookups.

Index

• type Cache
  • func New(resolver Resolver, size int, ttl time.Duration) *Cache
  • func (c *Cache) DialContext(ctx context.Context, network, address string) (net.Conn, error)
  • func (c *Cache) Len() int
  • func (c *Cache) LookupHost(ctx context.Context, host string) ([]string, error)
  • func (c *Cache) Remove(host string)
  • func (c *Cache) Reset()
• type Resolver

Types

type Cache

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

Cache represents the single-flight DNS cache.

func New

func New(resolver Resolver, size int, ttl time.Duration) *Cache

New creates a new single-flight DNS cache of the specified size and TTL. If the resolver parameter is nil, a default net.Resolver will be used. The size parameter determines the maximum number of DNS entries that can be cached (min = 1). If the size is less than or equal to zero, the cache will have a default size of 1. The ttl parameter specifies the time-to-live for each cached DNS entry.

func (*Cache) DialContext

func (c *Cache) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext dials the network and address specified by the parameters. It resolves the host from the address using the LookupHost method of the Resolver. It then attempts to establish a connection to each resolved IP address until a successful connection is made. If all connection attempts fail, it returns an error. The function returns the established net.Conn and any error encountered during the process. This function can replace the DialContext in http.Transport.

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of items in the cache.

func (*Cache) LookupHost

func (c *Cache) LookupHost(ctx context.Context, host string) ([]string, error)

LookupHost performs a DNS lookup for the given host. Duplicate lookup calls for the same host will wait for the first lookup to complete (single-flight). It also handles the case where the cache entry is removed or updated during the wait. The function returns the cached value if available; otherwise, it performs a new lookup. If the external lookup call is successful, it updates the cache with the newly obtained value.

func (*Cache) Remove

func (c *Cache) Remove(host string)

Remove removes the cache entry for the specified host.

func (*Cache) Reset

func (c *Cache) Reset()

Reset clears the whole cache.

type Resolver

type Resolver interface {
	LookupHost(ctx context.Context, host string) (addrs []string, err error)
}

Resolver is a net.Resolver interface for DNS lookups.