dnsworker

Documentation

Overview

Package dnsworker implements a simple limiting DNS client-request execution pool. Mobydig uses DnsPool with a pool of “DNS workers” for A/AAAA lookups. Please note that the A/AAAA queries for a single fqdn are not concurrent.

Usage

dnsclnt := dns.Client{}
workers := dnsworker.New(
    context.Background(),
    4,                    // number of parallel DNS connections and thus workers
    dnsclnt,              // DNS client
    "127.0.0.1:53",        // address of server/resolver
)
workers.ResolveName(
    "foobar.example.org",
    func(addrs []string, error){
        // do something with addrs, unless there's an error reported
    })
workers.Submit(func(conn *dns.Conn){
    // do something with the DNS connection
})

Acknowledgements

Under its hood, DnsPool leverages gammazero/workerpool as the limiting goroutine pool.

Index

• type DnsPool
  • func New(ctx context.Context, size int, dnsclnt *dns.Client, addr string, ...) (*DnsPool, error)
  • func (p *DnsPool) ResolveName(ctx context.Context, name string, fn func([]string, error))
  • func (p *DnsPool) StopWait()
  • func (p *DnsPool) Submit(task func(conn *dns.Conn))
• type DnsPoolOption
  • func InNetworkNamespace(netnsref string) DnsPoolOption

Types

type DnsPool

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

DnsPool is a (size-limited) pool of DNS client connections talking with the same DNS resolver address.

func New

func New(ctx context.Context, size int, dnsclnt *dns.Client, addr string, options ...DnsPoolOption) (*DnsPool, error)

New returns a pool of the specified size of DNS client connections, with each connection using the specified context and talking to the same DNS resolver address.

DNS tasks are submitted using DnsPool.Submit in form of task functions receiving a concrete dns.Conn.

The passed context is used for creating (dialing) the DNS client connections only. It is not directly passed to the submitted DNS tasks, so task submitters are themselves responsible for capturing the necessary context in their task function closure.

To operate a DnsPool in a network namespace different to that of the OS-level thread of the caller specify the InNetworkNamespace option and pass it a filesystem path that must reference a network namespace (such as "/proc/666/ns/net").

func (*DnsPool) ResolveName

func (p *DnsPool) ResolveName(ctx context.Context, name string, fn func([]string, error))

ResolveName is a convenience method for submitting A/AAAA queries and gathering the results. The results (resolved IP addresses in textual format) or an error if resolution failed is passed to the specified callback function fn.

fn is called only once after completing both A and AAAA queries, so fn always gets to see all IP addresses from all IP families to see (if any).

Please note that when the passed context is cancelled this will cancel all in-flight as well as scheduled name resolution jobs.

func (*DnsPool) StopWait

func (p *DnsPool) StopWait()

StopWait waits for all enqueued address lookup or generic DNS request tasks to finish, and then shuts down the pool.

func (*DnsPool) Submit

func (p *DnsPool) Submit(task func(conn *dns.Conn))

Submit a task to the DNS client connection pool, where it gets enqueued to be executed on an available DNS client connection.

type DnsPoolOption

type DnsPoolOption func(*DnsPool)

DnsPoolOption can be passed to New when creating new DnsPool objects.

func InNetworkNamespace

func InNetworkNamespace(netnsref string) DnsPoolOption

InNetworkNamespace optionally runs a DnsPool inside the network namespace referenced by the specified filesystem path.