client

Documentation

Overview

Package client implements a Go client for the AutoDNS (InterNetX) JSON API, covering DNS zone and record operations.

Index

• Variables
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func New(username, password, context string, opts ...Option) (*Client, error)
  • func (c *Client) CreateZone(ctx context.Context, zone *models.Zone) (*models.Zone, error)
  • func (c *Client) DeleteZone(ctx context.Context, origin, virtualNameServer string) error
  • func (c *Client) GetZone(ctx context.Context, origin, virtualNameServer string) (*models.Zone, error)
  • func (c *Client) ResolveVirtualNameServer(ctx context.Context, origin string) (string, error)
  • func (c *Client) SearchZones(ctx context.Context, filters []models.Filter) ([]models.Zone, error)
  • func (c *Client) UpdateRecords(ctx context.Context, origin, virtualNameServer string, ...) error
  • func (c *Client) UpdateZone(ctx context.Context, zone *models.Zone) (*models.Zone, error)
• type HTTPError
  • func (e *HTTPError) Error() string
• type Option
  • func WithEndpoint(url string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithMaxRetries(maxRetries int) Option
  • func WithRetryWait(wait time.Duration) Option
• type ParseError
  • func (e *ParseError) Error() string
  • func (e *ParseError) Unwrap() error

Variables

var (
	// ErrInvalidConfig is returned by New when username, password, or
	// context is empty.
	ErrInvalidConfig = errors.New("autodns: invalid client configuration")

	// ErrZoneNotFound is returned by zone operations when the API
	// reports that the requested zone does not exist.
	ErrZoneNotFound = errors.New("autodns: zone not found")

	// ErrAmbiguousZone is returned by ResolveVirtualNameServer when more than
	// one zone shares the given origin, so the origin alone does not identify
	// a single zone. Callers that can accept a virtual name server from their
	// own configuration should ask for one instead of resolving.
	ErrAmbiguousZone = errors.New("zone origin is ambiguous")
)

Sentinel errors, matched with errors.Is.

Types

type APIError

type APIError struct {
	// Status is the envelope's status.type, always "ERROR" here.
	Status string
	// Code is the AutoDNS result code, e.g. "EF02020".
	Code string
	// Text is the AutoDNS result message.
	Text string
	// HTTPStatus is the HTTP status code the envelope arrived with.
	HTTPStatus int
}

APIError is returned when the AutoDNS response envelope reports status.type "ERROR", regardless of the HTTP status code. Match it with errors.As.

func (*APIError) Error

func (e *APIError) Error() string

Error implements the error interface.

type Client

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

Client is the AutoDNS API client. Its *http.Client carries the retry and auth round trippers, so endpoint methods deal only with request shapes and response envelopes.

func New

func New(username, password, context string, opts ...Option) (*Client, error)

New constructs a Client for the AutoDNS API. username and password feed HTTP Basic Auth; context is sent as the X-Domainrobot-Context header (e.g. "33004"). It returns ErrInvalidConfig when any of the three is empty.

func (*Client) CreateZone

func (c *Client) CreateZone(ctx context.Context, zone *models.Zone) (*models.Zone, error)

CreateZone creates the given zone and returns the API's view of it.

func (*Client) DeleteZone

func (c *Client) DeleteZone(ctx context.Context, origin, virtualNameServer string) error

DeleteZone removes the zone. It returns an error matching ErrZoneNotFound when the zone does not exist.

func (*Client) GetZone

func (c *Client) GetZone(ctx context.Context, origin, virtualNameServer string) (*models.Zone, error)

GetZone fetches one zone, records included. It returns an error matching ErrZoneNotFound when the API reports the zone does not exist.

func (*Client) ResolveVirtualNameServer

func (c *Client) ResolveVirtualNameServer(ctx context.Context, origin string) (string, error)

ResolveVirtualNameServer returns the virtualNameServer of the zone with the given origin, found via zone search. It returns an error matching ErrZoneNotFound when no zone with that origin exists, and an error matching ErrAmbiguousZone, naming the candidate virtual name servers, when more than one zone matches: zone identity is origin+virtualNameServer, so more than one zone sharing an origin is genuinely ambiguous, not a pick-first guess.

Search results are filtered to an exact origin match before the count checks, which makes resolution independent of how the server interprets the name search: whether it matches loosely (e.g. returning subdomains of origin) or only exactly, only exact-origin results ever reach the count checks.

func (*Client) SearchZones

func (c *Client) SearchZones(ctx context.Context, filters []models.Filter) ([]models.Zone, error)

SearchZones returns the zones matching all given filters. An empty or nil filter list returns every zone visible to the account.

func (*Client) UpdateRecords

func (c *Client) UpdateRecords(ctx context.Context, origin, virtualNameServer string, adds, rems []models.ResourceRecord) error

UpdateRecords atomically applies record additions and removals to one zone via PATCH /zone/{origin}/{virtualNameServer}. AutoDNS has no per-record endpoints; this is the vns-targeted incremental route, letting callers address one of several zones sharing an origin by passing the specific virtualNameServer. It returns an error matching ErrZoneNotFound when the zone does not exist.

func (*Client) UpdateZone

func (c *Client) UpdateZone(ctx context.Context, zone *models.Zone) (*models.Zone, error)

UpdateZone replaces the zone's settings and records with the given value and returns the API's view of the result. It returns an error matching ErrZoneNotFound when the zone does not exist.

type HTTPError

type HTTPError struct {
	// Status is the HTTP status code.
	Status int
	// Body is the raw response body, kept for diagnostics.
	Body []byte
}

HTTPError is returned for a non-2xx response whose body is not a parseable AutoDNS envelope. Match it with errors.As.

func (*HTTPError) Error

func (e *HTTPError) Error() string

Error implements the error interface.

type Option

type Option func(*config)

Option configures a Client at construction time.

func WithEndpoint

func WithEndpoint(url string) Option

WithEndpoint overrides the API base URL (default https://api.autodns.com/v1). Point it at a fakeautodns server in tests. A trailing slash is trimmed.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient supplies the base *http.Client whose transport the auth and retry round trippers wrap. Use it for custom TLS or timeout settings. The supplied client is copied, not mutated.

func WithMaxRetries

func WithMaxRetries(maxRetries int) Option

WithMaxRetries sets how many extra attempts a retryable response gets (default 3). Zero disables retries.

func WithRetryWait

func WithRetryWait(wait time.Duration) Option

WithRetryWait sets the initial retry backoff (default 200ms); each retry doubles it, capped at 5s.

type ParseError

type ParseError struct {
	// Endpoint is the request path that produced the undecodable body.
	Endpoint string
	// Err is the underlying decode error.
	Err error
}

ParseError is returned when a 2xx response body cannot be decoded. Surfacing this loudly is intentional: it flags a mismatch between this client's models and the live API. Match it with errors.As.

func (*ParseError) Error

func (e *ParseError) Error() string

Error implements the error interface.

func (*ParseError) Unwrap

func (e *ParseError) Unwrap() error

Unwrap exposes the underlying decode error to errors.Is and errors.As.