dnscale

DNScale Go SDK

Go 1.25+ client for the DNScale API, generated from the public OpenAPI contract bundled as openapi.yaml.

Installation

From your Go module, install the SDK:

go get github.com/dnscaleou/dnscale-go

Quick start

Create an API key in the DNScale dashboard and pass it through Options.APIKey or export it as DNSCALE_API_KEY.

package main

import (
    "context"
    "log"

    dnscale "github.com/dnscaleou/dnscale-go"
)

func main() {
    dns, err := dnscale.New(dnscale.Options{}) // reads DNSCALE_API_KEY
    if err != nil { log.Fatal(err) }
    defer dns.Close()
    ctx := context.Background()

    for zone, err := range dns.Zones.Iter(ctx, 100) {
        if err != nil { log.Fatal(err) }
        for record, err := range dns.Records.Iter(ctx, zone.Id.String(), 100) {
            if err != nil { log.Fatal(err) }
            log.Printf("%s %s %s", zone.Name, record.Name, record.Content)
        }
    }
}

Resources

Zones and Records provide List, Iter, Get, Create, Update, and Delete. Zone IDs are accepted as UUID strings. Record IDs are opaque and content-derived: retain the returned ID after an update.

zone, err := dns.Zones.Create(ctx, dnscale.CreateZoneRequest{Name: "example.com"})
if err != nil { return err }
record, err := dns.Records.Create(ctx, zone.Id.String(), dnscale.CreateRecordRequest{
    Name: "www", Type: "A", Content: "192.0.2.10", Ttl: dnscale.Ptr(300),
})
if err != nil { return err }
err = dns.Records.Delete(ctx, zone.Id.String(), record.Id)

List returns one page. Iter(ctx, pageSize) lazily follows returned counts and has_more, rejects inconsistent/non-progressing pages, and stops making requests when the caller breaks out. Iterators accept page sizes 1–100. Listing is not an atomic snapshot during concurrent writes.

Records.UpdateByName(ctx, zoneID, name, type, body, oldContent) selects an old value when the final pointer is non-nil. Records.DeleteByName(ctx, zoneID, name, type, content) deletes a selected value; nil deletes the entire RRset. An empty content pointer is rejected by the delete helper.

Generated request models use pointers for optional values. dnscale.Ptr(false) and dnscale.Ptr(0) preserve explicit zero values. Nullable fields such as comment use github.com/oapi-codegen/nullable: zero value omits the field, nullable.NewNullNullable[string]() sends null, and nullable.NewNullableWithValue("note") sends a value.

Transport and errors

Options supports APIKey, BaseURL (including /v1), HTTPClient, Timeout, MaxRetries, and RetryBackoff. The default endpoint is https://api.dnscale.eu/v1. The supplied HTTP client is copied, then its timeout and redirect policy are set; its transport and cookie jar are retained.

Only GET/HEAD/OPTIONS without request bodies retry network errors and transient 408/429/500/502/503/504 statuses, up to twice. Mutations are never automatically retried. MaxRetries: dnscale.Ptr(0) disables retries. Retry-After dates and seconds are supported. A delay beyond the 30-second waiting budget surfaces the response instead of retrying too early. Requests have a default total 10-second deadline, including retries; context cancellation interrupts retry waiting. Redirects are not followed. Close() releases idle connections.

Use errors.As for *dnscale.APIError (StatusCode, Code, Message, RequestID, Details) and *dnscale.RateLimitError (also RetryAfter). RateLimitError unwraps to APIError. HTTP metadata survives HTML gateway errors. Transport errors remain standard Go errors. Unexpected success envelopes return *dnscale.ProtocolError.

Full API coverage

dns.API exposes the generated client for all documented operations; models live in github.com/dnscaleou/dnscale-go/api:

result, err := dns.API.GetCurrentUsageWithResponse(ctx)

Both layers use the configured transport and return API errors on unsuccessful HTTP statuses. Directly constructing api.NewClientWithResponses bypasses the SDK's authentication, timeout, retry, and error policy.

Development

GOCACHE="$PWD/.gocache" go test -race ./...
GOCACHE="$PWD/.gocache" go vet ./...
bash scripts/generate.sh

Generation uses pinned oapi-codegen and bundled openapi.yaml. Commit both the contract and generated files. Keep go.mod and go.sum committed.

Live verification creates/deletes a unique disposable zone and requires explicit test credentials with zone/record read/write scopes:

export DNSCALE_TEST_BASE_URL=https://api-sandbox.dnscale.eu/v1
export DNSCALE_TEST_API_KEY=your-disposable-account-key
DNSCALE_LIVE_TEST=1 GOCACHE="$PWD/.gocache" go test -run TestLiveLifecycle -v .

Normal tests skip that lifecycle.