doh

Documentation

Overview

Package doh is the library behind the doh command line: the HTTP client, request shaping, and the typed data models for DNS over HTTPS.

The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public API throws under load. DNS queries are made to Google's public DoH API (dns.google/resolve).

Index

• Constants
• type Client
  • func NewClient() *Client
  • func (c *Client) Get(ctx context.Context, url string) ([]byte, error)
  • func (c *Client) Resolve(ctx context.Context, domain, recordType string) ([]Record, error)
• type Config
  • func DefaultConfig() Config
• type Domain
  • func (Domain) Classify(input string) (uriType, id string, err error)
  • func (Domain) Info() kit.DomainInfo
  • func (Domain) Locate(uriType, id string) (string, error)
  • func (Domain) Register(app *kit.App)
• type Record

Constants

const BaseURL = "https://" + Host

BaseURL is the root every request is built from.

const DefaultUserAgent = "doh/dev (+https://github.com/tamnd/doh-cli)"

DefaultUserAgent identifies the client to dns.google.

const Host = "dns.google"

Host is the DNS-over-HTTPS resolver host.

Types

type Client

type Client struct {
	HTTP      *http.Client
	UserAgent string
	BaseURL   string
	// Rate is the minimum gap between requests. Zero means no pacing.
	Rate    time.Duration
	Retries int
	// contains filtered or unexported fields
}

Client talks to dns.google over HTTPS.

func NewClient

func NewClient() *Client

NewClient returns a Client with sensible defaults.

func (*Client) Get

func (c *Client) Get(ctx context.Context, url string) ([]byte, error)

Get fetches url and returns the response body. It paces and retries according to the client's settings. The caller owns nothing extra; the body is read fully and closed here.

func (*Client) Resolve

func (c *Client) Resolve(ctx context.Context, domain, recordType string) ([]Record, error)

Resolve queries dns.google for the given domain and record type (e.g. "A", "MX"). It returns all answer and authority records, or an error if the DNS status is non-zero.

type Config

type Config struct {
	BaseURL string
	Rate    time.Duration
	Retries int
	Timeout time.Duration
}

Config holds per-client tunables.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns sensible defaults for the DoH client.

type Domain

type Domain struct{}

Domain is the doh driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns any accepted input into the canonical (type, id).

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Record

type Record struct {
	Name string `json:"name"`
	Type string `json:"type"` // "A", "AAAA", "MX", "TXT", etc.
	TTL  int    `json:"ttl"`
	Data string `json:"data"`
}

Record is one DNS resource record returned by a resolve call.