dinahosting

README

Dinahosting DNS for libdns

This package implements the libdns interfaces for the Dinahosting API, allowing you to manage DNS records for your domains.

Compatible with libdns v1.x (the provider returns the RR-type-specific structs defined by libdns, such as libdns.Address, libdns.TXT and libdns.CNAME).

Supported record types

This package was primarily written to be used as a Caddy plugin for solving ACME challenges and adding dynamic DNS capabilities. The following record types are supported for writes (AppendRecords, SetRecords, DeleteRecords):

• A
• AAAA
• TXT
• CNAME

GetRecords also returns any other record types present in the zone (MX, SRV, URL, FRAME, SPF, ANAME, ...) as opaque libdns.RR values so callers can still enumerate them.

Authenticating

Dinahosting does not provide API keys, so you need to use the username and password of your panel account.

Reliability in production

The Dinahosting API is noticeably slow — a single zone-modifying request can take 10–30 seconds to return — and occasional upstream failures (HTTP 5xx, TCP resets, DNS hiccups) can surface as transient errors. To make the provider safe for automated flows such as ACME renewals, the provider:

• Uses a per-request HTTP timeout of 45 seconds by default.
• Retries up to 3 times with exponential backoff (1s, 2s, 4s) on transport-level errors (connection refused, EOF, timeouts…) and on HTTP 5xx responses.
• Does not retry on HTTP 200 responses that carry a business-logic error (Dinahosting's responseCode field): those errors are deterministic and retrying would only amplify load.
• Respects the caller's context.Context — if the context is cancelled during a backoff sleep, the call returns immediately with ctx.Err().

Callers that need a custom transport (proxy, custom TLS, their own retry layer, tracing, etc.) can inject their own http.Client:

p := &dinahosting.Provider{
    Username:   "YOUR_USERNAME",
    Password:   "YOUR_PASSWORD",
    HTTPClient: myCustomClient, // optional
}

Testing

The test suite has two parts:

• Unit tests for the HTTP retry logic, which run without credentials against an in-process httptest server.
• Integration tests that talk to the real Dinahosting API. They create and delete fixture records on a zone you own, and clean up after themselves.

To enable the integration tests edit the constants at the top of provider_test.go:

const (
    username = "YOUR_USERNAME"
    password = "YOUR_PASSWORD"
    zone     = "example.com"
)

Then run:

go test -v ./...

The integration tests skip themselves automatically when password is left at its default placeholder, so the suite is safe to run in CI without credentials. Because each API call takes several seconds, a full live run currently takes ~6 minutes.

Example usage

package main

import (
    "context"

    "github.com/libdns/libdns"
    "github.com/plorenzo/libdns-dinahosting"
)

func main() {
    p := &dinahosting.Provider{
        Username: "YOUR_USERNAME",
        Password: "YOUR_PASSWORD",
    }

    _, err := p.AppendRecords(context.Background(), "example.org.", []libdns.Record{
        libdns.TXT{
            Name: "_acme-challenge",
            Text: "123456",
        },
    })
    if err != nil {
        panic(err)
    }
}

Documentation

Overview

Package dinahosting implements a DNS record management client compatible with the libdns interfaces for Dinahosting (https://es.dinahosting.com/api).

This package supports the following record types for writes (Append, Set, Delete): A, AAAA, TXT and CNAME. GetRecords additionally returns any other record types present in the zone as opaque libdns.RR values.

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) SetRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

Types

type Provider

type Provider struct {
	Username string `json:"username,omitempty"`
	Password string `json:"password,omitempty"`

	// HTTPClient, if non-nil, is used to perform requests to the Dinahosting
	// API. When nil, an internal client with a generous per-request timeout
	// is used. Callers that need a custom transport, proxy, TLS config or
	// their own retry/observability layer can inject their own client here.
	HTTPClient *http.Client `json:"-"`
}

Provider facilitates DNS record manipulation with Dinahosting.

func (*Provider) AppendRecords

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

AppendRecords adds records to the zone. It returns the records that were added as concrete libdns RR-type structs (A/AAAA as libdns.Address, TXT as libdns.TXT, CNAME as libdns.CNAME).

Supported record types: A, AAAA, TXT, CNAME.

API docs: https://es.dinahosting.com/api/documentation

func (*Provider) DeleteRecords

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

DeleteRecords deletes the records from the zone. It returns the records that were deleted as concrete libdns RR-type structs.

Supported record types: A, AAAA, TXT, CNAME.

API docs: https://es.dinahosting.com/api/documentation

func (*Provider) GetRecords

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

GetRecords lists all the records in the zone.

A and AAAA records are returned as libdns.Address, TXT as libdns.TXT, CNAME as libdns.CNAME. Any other record type is returned as an opaque libdns.RR so callers can still enumerate what exists in the zone.

API docs: https://es.dinahosting.com/api/documentation

func (*Provider) SetRecords

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

SetRecords updates the zone so that the RRset formed by each input record's (Name, Type) pair contains exactly the input records. It implements the canonical semantics described in the godoc of libdns.RecordSetter: existing records in the same RRset are deleted first, then the new records are appended.

API docs: https://es.dinahosting.com/api/documentation