go-autodns

README

go-autodns

go-autodns is a Go client library for accessing the AutoDNS (InterNetX) JSON API, covering DNS zone and record operations. Runtime code depends on the Go standard library only.

The module also ships fakeautodns, an in-memory fake AutoDNS server for tests: this repo's own e2e tests and downstream consumers (such as a Terraform provider's acceptance tests) run against it without real credentials.

Which AutoDNS?

"AutoDNS" is a product of InterNetX GmbH, a German company. InterNetX builds the AutoDNS domain and DNS platform and exposes it programmatically through the Domain Robot JSON API (InterNetX uses the "DomainRobot" name for its APIs and SDKs). This library targets that JSON API, defaulting to the https://api.autodns.com/v1 endpoint, which you can override with a client option.

The same platform is also sold through resellers, who run their own branded portals on domains other than autodns.com (for example a login at portal.autodns.nl). Signing in through a reseller's portal still puts you on the InterNetX AutoDNS platform under that reseller's branding.

To use this library you need InterNetX AutoDNS JSON API credentials from your provider: a username, a password, and a context value (sent as the X-Domainrobot-Context header). These are separate from your web-portal login. The JSON API is served from api.autodns.com even when you reach it through a reseller-branded portal, so this library's default endpoint works for reseller accounts; override it only if your provider directs you to a different host.

Install

go get github.com/alserda-nl/go-autodns

Usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/alserda-nl/go-autodns/client"
	"github.com/alserda-nl/go-autodns/models"
)

func main() {
	apiClient, err := client.New("username", "password", "33004")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	// Fetch a zone with all its records.
	zone, err := apiClient.GetZone(ctx, "example.com", "a.ns14.net")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(zone.Origin, len(zone.ResourceRecords))

	// Atomically add and remove records. The AutoDNS API has no
	// per-record endpoints; _stream is the record mutation primitive.
	err = apiClient.StreamRecords(
		ctx,
		"example.com",
		"a.ns14.net",
		[]models.ResourceRecord{
			{
				Name:  "www",
				Type:  "A",
				Value: "192.0.2.10",
				TTL:   600,
			},
		},
		nil,
	)
	if err != nil {
		log.Fatal(err)
	}
}

Options

client.New(username, password, context,
	client.WithEndpoint("https://api.autodns.com/v1"), // default shown
	client.WithHTTPClient(customHTTPClient),           // custom TLS/timeouts
	client.WithMaxRetries(3),                          // default shown
	client.WithRetryWait(200*time.Millisecond),        // default shown
)

The client retries 429 and 500/502/503/504 responses with exponential backoff (doubling from the retry wait, capped at 5s, plus or minus 20% jitter). A Retry-After header on any retried response overrides the backoff for that attempt, in either form the HTTP spec allows: an integer number of seconds or an HTTP date. Sleeps abort when the request context is canceled.

Errors

Construction and lookup misses use sentinels, matched with errors.Is:

• client.ErrInvalidConfig - New called with an empty username, password, or context.
• client.ErrZoneNotFound - the API reported the requested zone does not exist.

API-level failures use typed pointer errors, matched with errors.As:

• *client.APIError - the response envelope reported status.type == "ERROR".
• *client.HTTPError - a non-2xx response without a parseable envelope.
• *client.ParseError - a 2xx response whose body could not be decoded.

zone, err := apiClient.GetZone(ctx, "example.com", "a.ns14.net")
if errors.Is(err, client.ErrZoneNotFound) {
	// zone does not exist
}
var apiErr *client.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.Code, apiErr.Text, apiErr.HTTPStatus)
}

Testing against the fake

func TestSomething(t *testing.T) {
	fake := fakeautodns.New(t)
	fake.SeedZone(models.Zone{Origin: "example.com", VirtualNameServer: "a.ns.example.net"})

	apiClient, err := client.New(
		fakeautodns.Username, fakeautodns.Password, fakeautodns.Context,
		client.WithEndpoint(fake.URL))
	// ...
}

fakeautodns supports SeedZone, Zone (inspect state), Reset, and FailNext(status, times) for retry scenarios. It verifies credentials the way the real API does and answers with real envelope shapes.

Development

make help              # list targets
make lint              # golangci-lint
make lint-fix          # golangci-lint with auto-fix
make test              # every non-tagged test (unit + e2e), race detector on
make unit-test         # unit tests only (client, models, fakeautodns)
make e2e-test          # e2e suite only (tests/ against fakeautodns)
make integration-test  # real-API tests, local only; needs AUTODNS_USERNAME, AUTODNS_PASSWORD, AUTODNS_CONTEXT

CI runs lint, unit, and e2e as three parallel jobs. The real-API integration tests never run in CI. Nothing here uses docker: fakeautodns is an in-process httptest server.

Integration tests are additionally gated on AUTODNS_TEST_ZONE_ORIGIN and AUTODNS_TEST_VNS for the zone lifecycle test, so a throwaway zone is named explicitly.

Scope

Zone and record operations for now. Domain registration is the most likely next addition; certificate and contact endpoints of the AutoDNS API follow when a concrete use case exists.

Versioning

Releases follow semantic versioning. Tags and GitHub releases are created automatically from conventional commit messages when changes land on main. Until v1.0.0, minor releases may include breaking changes; the CHANGELOG records them.

Contributing

Issues and pull requests are welcome. Run make lint and make test before submitting; commit messages follow Conventional Commits, which drive the release automation.

License

MIT