sdk

Documentation

Overview

Package sdk is a thin HTTP client for the AutoDNS (Domainrobot) JSON API.

It is the transport used by the libdns/autodns provider, exported so callers who need direct access to AutoDNS — for example to read or write zone fields that libdns does not model (Main.Address, WWWInclude, SOA, nameServerGroup) — can use it on its own.

Authentication

Requests use HTTP Basic auth (Username, Password) and carry the AutoDNS account context in the X-Domainrobot-Context header. When Context is empty the SDK falls back to a default value; set it explicitly if your account uses a non-default context.

Usage

s := &sdk.SDK{
    Username: os.Getenv("AUTODNS_USERNAME"),
    Password: os.Getenv("AUTODNS_PASSWORD"),
}

zone, err := s.CheckZone(ctx, "example.org")
if err != nil {
    return err
}

resp, err := s.GetZone(ctx, zone.Origin, zone.Nameserver, "example.org")
if err != nil {
    return err
}
// mutate resp.Data[0] ...
if err := s.UpdateZone(ctx, zone.Origin, zone.Nameserver, resp.Data[0]); err != nil {
    return err
}

Errors

Errors returned by the AutoDNS API surface as *AutoDNSError. Use errors.As to inspect the underlying message list:

var apiErr *sdk.AutoDNSError
if errors.As(err, &apiErr) {
    for _, m := range apiErr.Messages() {
        // m.Text, m.Code, m.Objects
    }
}

Index

• type AutoDNSError
  • func NewError(messages []*AutoDNSMessage) *AutoDNSError
  • func (m *AutoDNSError) Error() string
  • func (m *AutoDNSError) Messages() []*AutoDNSMessage
• type AutoDNSMessage
• type AutoDNSObject
• type AutoDNSResponse
• type AutoDNSUser
• type ResponseStatus
• type ResponseZone
• type SDK
  • func (s *SDK) CheckZone(ctx context.Context, zone string) (*ZoneItem, error)
  • func (s *SDK) GetZone(ctx context.Context, origin, nameserver, zone string) (*ResponseZone, error)
  • func (s *SDK) PatchZone(ctx context.Context, origin, nameserver string, patch ZonePatch) (*ResponseZone, error)
  • func (s *SDK) UpdateZone(ctx context.Context, origin, nameserver string, zone ZoneItem) error
• type ZoneItem
  • func (m *ZoneItem) MarshalJSON() ([]byte, error)
  • func (m *ZoneItem) UnmarshalJSON(data []byte) error
• type ZoneItemMain
• type ZoneNameserver
• type ZonePatch
• type ZoneRecord
• type ZoneSOA

Types

type AutoDNSError

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

AutoDNSError is the typed error returned by the SDK when the API reports a failure (Status.Type == "ERROR"). Use errors.As to detect it and Messages to inspect the per-message details.

func NewError

func NewError(messages []*AutoDNSMessage) *AutoDNSError

func (*AutoDNSError) Error

func (m *AutoDNSError) Error() string

func (*AutoDNSError) Messages

func (m *AutoDNSError) Messages() []*AutoDNSMessage

type AutoDNSMessage

type AutoDNSMessage struct {
	Text    string          `json:"text"`
	Objects []AutoDNSObject `json:"objects"`
	Code    string          `json:"code"`
	Status  string          `json:"status"`
}

AutoDNSMessage is a single status or error message returned by the API. A response may carry multiple messages; Code and Text describe what happened and Objects lists the entities the message refers to.

type AutoDNSObject

type AutoDNSObject struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

AutoDNSObject is a generic reference to an entity in the AutoDNS API (a zone, domain, contact, etc.). It appears as the top-level `object` field on a response and inside AutoDNSMessage to identify what an error or status message refers to.

type AutoDNSResponse

type AutoDNSResponse struct {
	STID string `json:"stid"`

	Status ResponseStatus `json:"status"`

	Object *AutoDNSObject `json:"object,omitempty"`

	// potential error messages
	Messages []*AutoDNSMessage `json:"messages,omitempty"`
}

AutoDNSResponse is the envelope returned by every AutoDNS endpoint. Status.Type is "SUCCESS" on success and "ERROR" on failure; Messages carries the error details in the latter case.

type AutoDNSUser

type AutoDNSUser struct {
	Context int32  `json:"context"`
	User    string `json:"user"`
}

AutoDNSUser identifies an AutoDNS account by its numeric context and user name. It appears as the owner and updater on a zone.

type ResponseStatus

type ResponseStatus struct {
	Type string  `json:"type"`
	Code *string `json:"code,omitempty"`
	Text *string `json:"text,omitempty"`
}

ResponseStatus is the status block on an AutoDNSResponse. Type is "SUCCESS" on success and "ERROR" on failure; Code and Text carry optional per-status details.

type ResponseZone

type ResponseZone struct {
	AutoDNSResponse
	Data []ZoneItem `json:"data"`
}

ResponseZone is an AutoDNSResponse whose Data field carries one or more zones. It is returned by /zone/_search (search hits, with SOA and resourceRecords omitted) and by GET /zone/{name}/{ns} (a single, full zone).

Example payload returned for a /zone/_search hit (search results omit resourceRecords and SOA; full zone fields appear via GET /zone/{name}/{ns}).

{
	"created": "2023-10-18T13:56:47.000+0200",
	"updated": "2024-10-25T13:16:43.000+0200",
	"origin": "something.example.org",
	"nameServerGroup": "ns14.net",
	"owner": {
	  "context": 4,
	  "user": "user"
	},
	"updater": {
	  "context": 4,
	  "user": "user"
	},
	"domainsafe": false,
	"wwwInclude": false,
	"virtualNameServer": "a.ns14.net"
}

type SDK

type SDK struct {
	Username   string
	Password   string
	Endpoint   string
	Context    string
	HttpClient *http.Client
}

func (*SDK) CheckZone

func (s *SDK) CheckZone(ctx context.Context, zone string) (*ZoneItem, error)

CheckZone verifies that the zone exists and returns the data required (origin and nameserver) to fetch the full zone via GetZone.

func (*SDK) GetZone

func (s *SDK) GetZone(ctx context.Context, origin, nameserver, zone string) (*ResponseZone, error)

GetZone returns the zone.

func (*SDK) PatchZone

func (s *SDK) PatchZone(ctx context.Context, origin, nameserver string, patch ZonePatch) (*ResponseZone, error)

PatchZone applies a changeset to a zone. Unlike UpdateZone, which sends the full zone, PatchZone sends only the records to add and remove. The returned ResponseZone carries the zone in its updated form.

func (*SDK) UpdateZone

func (s *SDK) UpdateZone(ctx context.Context, origin, nameserver string, zone ZoneItem) error

UpdateZone updates the zone.

type ZoneItem

type ZoneItem struct {
	Created string `json:"created"`
	Updated string `json:"updated"`
	Origin  string `json:"origin"`

	SOA ZoneSOA `json:"soa"`

	NSGroup    string      `json:"nameServerGroup"`
	Owner      AutoDNSUser `json:"owner"`
	Updater    AutoDNSUser `json:"updater"`
	DomainSafe bool        `json:"domainsafe"`
	PurgeType  string      `json:"purgeType"`

	Nameservers []ZoneNameserver `json:"nameServers"`

	Main ZoneItemMain `json:"main"`

	// this enables an automatic `www` record (of type A for the domain)
	WWWInclude bool   `json:"wwwInclude"`
	Nameserver string `json:"virtualNameServer"`
	Action     string `json:"action"`

	Records []ZoneRecord `json:"resourceRecords"`

	ROID int `json:"roid"`
}

ZoneItem is a full AutoDNS zone: SOA, nameservers, the resource record set, and the AutoDNS-specific Main and WWWInclude shortcuts for the apex (and optional www) A record.

func (*ZoneItem) MarshalJSON

func (m *ZoneItem) MarshalJSON() ([]byte, error)

Custom JSON marshaling for Main struct to handle *netip.Addr

func (*ZoneItem) UnmarshalJSON

func (m *ZoneItem) UnmarshalJSON(data []byte) error

type ZoneItemMain

type ZoneItemMain struct {
	// the default IP address to be used, e.g. for an A-record for the domain)
	Address *netip.Addr `json:"address"`
	// the default TTL of the record
	TTL int `json:"ttl"`
}

ZoneItemMain is the apex IP shortcut on a zone. When Address is set, AutoDNS auto-creates an A record at the zone apex; if the zone's WWWInclude is also true, `www` gets the same A record. Neither of these records appears in ZoneItem.Records — to change or remove them, mutate Address (and WWWInclude) directly and call UpdateZone.

type ZoneNameserver

type ZoneNameserver struct {
	Name string `json:"name"`
}

ZoneNameserver is a single entry in ZoneItem.Nameservers — the list of authoritative nameservers AutoDNS reports for the zone.

type ZonePatch

type ZonePatch struct {
	ResourceRecordsAdd []ZoneRecord `json:"resourceRecordsAdd,omitempty"`
	ResourceRecordsRem []ZoneRecord `json:"resourceRecordsRem,omitempty"`
}

ZonePatch is the body of PATCH /zone/{origin}/{nameserver}. Only the changeset is sent: records in ResourceRecordsAdd are added to the zone, records in ResourceRecordsRem are removed.

type ZoneRecord

type ZoneRecord struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Value string `json:"value"`
	Pref  *int   `json:"pref,omitempty"`
	TTL   int    `json:"ttl,omitempty"`
}

ZoneRecord is a single DNS resource record stored inside a zone. Pref is only meaningful for record types that carry a preference (MX); it is nil for everything else. TTL of 0 is omitted on the wire so the zone's SOA TTL applies.

type ZoneSOA

type ZoneSOA struct {
	Refresh int    `json:"refresh"`
	Retry   int    `json:"retry"`
	Expire  int    `json:"expire"`
	TTL     int    `json:"ttl"`
	Email   string `json:"email"`
}

ZoneSOA is the SOA block on a ZoneItem.