hosterby

README

hoster.by for libdns

This package implements the libdns interfaces for hoster.by, allowing you to manage DNS records via the hoster.by API.

Authenticating

The provider needs the access key and secret key of an API service account, which can be generated in the hoster.by control panel under hoster API (see the guide).

hoster.by offers two kinds of keys:

• Temporary keys expire after at most six months and have to be regenerated before that.
• Permanent keys don't expire, but only work from a single static IPv4 address.

The keys need access to the DNS hosting service: listing the services, and listing, adding, changing and deleting the records of the types you intend to manage. GetRecords and deleting records without a type also need the permission to list all records. For ACME DNS challenges, the TXT record permissions are sufficient.

The zone must be a domain with the hoster.by DNS hosting service on the same account.

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/libdns/hosterby"
	"github.com/libdns/libdns"
)

func main() {
	provider := &hosterby.Provider{
		AccessKey: "YOUR_ACCESS_KEY",
		SecretKey: "YOUR_SECRET_KEY",
	}

	records, err := provider.AppendRecords(context.Background(), "example.by.", []libdns.Record{
		libdns.TXT{Name: "_acme-challenge", TTL: 10 * time.Minute, Text: "token"},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(records)
}

Configuration

Field	Description
AccessKey	Access key of the API service account. Required.
SecretKey	Secret key of the API service account. Required.
BaseURL	API endpoint. Defaults to https://serviceapi.hoster.by.
HTTPClient	Custom HTTP client. Defaults to a client with a 30s timeout.

Caveats

• The API manages record sets: all records with the same name and type are written together. Appending or deleting a record rewrites its record set. This is serialized within one Provider value, but not across clients.
• Each record set is written with a separate request, so a failed call may leave the record sets written before the failure changed.
• All records of a record set share one TTL, and appending keeps the existing TTL. TTLs are clamped to the API range of 10 minutes to 7 days, and records without a TTL get 10 minutes.
• Internationalized zones and names are handled in Punycode (e.g. xn--80aaa.xn--90ais.). At the time of writing, the API fails to return the records of internationalized zones (dns_error_getting_records_data), so they can't be managed yet.
• Disabled records are hidden from GetRecords and preserved by AppendRecords and DeleteRecords. Appending a disabled record enables it. SetRecords replaces them like any other record.
• Only A, AAAA, ALIAS, CAA, CNAME, MX, NS, SRV and TXT records can be written. GetRecords returns all types, including SOA. The API allows underscores only in TXT and SRV names, and ALIAS records only at the zone apex.

Testing

Unit tests use an in-memory fake of the API:

go test ./...

The integration test uses the live API and covers all writable types. It creates records only below a random libdns-test-* name, with documentation IP addresses and example.com targets, and removes them afterwards. The keys need permissions to list services and to list, add, change and delete records of all types:

HOSTERBY_ACCESS_KEY=... HOSTERBY_SECRET_KEY=... HOSTERBY_TEST_ZONE=example.by go test -run Integration -v ./...

ALIAS records are accepted only at the zone apex, so the ALIAS test briefly changes how the zone resolves. It runs only with HOSTERBY_TEST_APEX_ALIAS=1 and if the apex has no A, AAAA or ALIAS records.

Documentation

Overview

Package hosterby implements a DNS record management client compatible with the libdns interfaces for hoster.by.

Authentication

The provider authenticates with an access key and a secret key, which can be issued in the hoster.by control panel. Short-lived access tokens are created from them and renewed automatically.

Appending, setting and deleting records lists only the records of their types, so the keys need permissions for these types only. Provider.GetRecords and deleting records without a type list all records, which needs a separate permission.

Record sets

The API manages record sets (RRsets): all records of the same name and type are written together and share one TTL. Consequently:

• Appending or deleting a record rewrites its record set. This is serialized within a Provider value, but not across clients.
• Each record set is written with a separate request, so a failed call may leave the record sets written before the failure changed.
• Appending to an existing record set keeps its TTL. Within a call, the first TTL given for a record set is used.
• TTLs are clamped to the API range of 10 minutes to 7 days, and records without a TTL get 10 minutes.
• Disabled records are hidden from Provider.GetRecords and preserved by Append and Delete. Appending a disabled record enables it.

Record types

Provider.GetRecords returns all types. Only A, AAAA, ALIAS, CAA, CNAME, MX, NS, SRV and TXT records can be written.

Index

• type Provider
  • func (p *Provider) AppendRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) DeleteRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)
  • func (p *Provider) ListZones(ctx context.Context) ([]libdns.Zone, error)
  • func (p *Provider) SetRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

Types

type Provider

type Provider struct {
	// AccessKey is the access key of the API service account.
	AccessKey string `json:"access_key,omitempty"`

	// SecretKey is the secret key of the API service account.
	SecretKey string `json:"secret_key,omitempty"`

	// BaseURL overrides the default API endpoint, https://serviceapi.hoster.by.
	BaseURL string `json:"base_url,omitempty"`

	// HTTPClient overrides the default HTTP client, which has a 30 second
	// timeout.
	HTTPClient *http.Client `json:"-"`
	// contains filtered or unexported fields
}

Provider facilitates DNS record manipulation with hoster.by.

func (*Provider) AppendRecords

func (p *Provider) AppendRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

AppendRecords adds records to the zone and returns the added ones. Records that already exist are skipped.

func (*Provider) DeleteRecords

func (p *Provider) DeleteRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

DeleteRecords deletes matching records from the zone and returns them. An empty type, TTL or data matches any value. TTLs are clamped to the API range before comparison. Records of types that can't be written are not deleted.

func (*Provider) GetRecords

func (p *Provider) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)

GetRecords lists all the records in the zone.

func (*Provider) ListZones

func (p *Provider) ListZones(ctx context.Context) ([]libdns.Zone, error)

ListZones lists the zones of the account, with internationalized names in Punycode.

func (*Provider) SetRecords

func (p *Provider) SetRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

SetRecords makes the input records the only records of their (name, type) pairs in the zone, replacing all others, including disabled ones. It returns the records that were set.