cloudns

README

ClouDNS for libdns

This package implements the libdns interfaces for ClouDNS, allowing you to manage DNS records.

Installation

To install this package, use go get:

go get github.com/libdns/cloudns

Usage

Here is an example of how to use this package to manage DNS records:

package main

import (
	"context"
	"fmt"
	"github.com/libdns/cloudns"
	"github.com/libdns/libdns"
	"time"
)

func main() {
	provider := &cloudns.Provider{
		AuthId:       "your_auth_id",
		SubAuthId:    "your_sub_auth_id",
		AuthPassword: "your_auth_password",
	}

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	// Get records
	records, err := provider.GetRecords(ctx, "example.com")
	if err != nil {
		fmt.Printf("Failed to get records: %s\n", err)
		return
	}
	fmt.Printf("Records: %+v\n", records)

	// Append a record
	newRecord := libdns.Record{
		Type:  "TXT",
		Name:  "test",
		Value: "test-value",
		TTL:   300 * time.Second,
	}
	addedRecords, err := provider.AppendRecords(ctx, "example.com", []libdns.Record{newRecord})
	if err != nil {
		fmt.Printf("Failed to append record: %s\n", err)
		return
	}
	fmt.Printf("Added Records: %+v\n", addedRecords)
}

Configuration

The Provider struct has the following fields:

• AuthId (string, optional): Your ClouDNS authentication ID.
• SubAuthId (string, optional): Your ClouDNS sub-authentication ID.
• AuthPassword (string): Your ClouDNS authentication password.

Testing

To run the tests, you need to set up your ClouDNS credentials and zone in the test file provider_test.go. The tests require a live ClouDNS account.

var (
TAuthId = "your_auth_id"
TSubAuthId = "your_sub_auth_id"
TAuthPassword = "your_auth_password"
TZone = "example.com"
)

Run the tests using the following command:

go test ./...

License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation

Index

• Constants
• func RetryWithBackoff(ctx context.Context, operation func() error, maxRetries int, ...) error
• type ApiDnsRecord
• type ApiResponse
• type Client
  • func UseClient(authId, subAuthId, authPassword string) *Client
  • func (c *Client) AddRecord(ctx context.Context, zone string, record ApiDnsRecord) (libdns.Record, error)
  • func (c *Client) DeleteRecord(ctx context.Context, zone string, recordId string) error
  • func (c *Client) GetClouDNSRecords(ctx context.Context, zone string) ([]ApiDnsRecord, error)
  • func (c *Client) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)
  • func (c *Client) UpdateRecord(ctx context.Context, zone string, record ApiDnsRecord) (libdns.Record, error)
• 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)

Constants

const (
	// DefaultOperationRetries is the default number of retries for DNS operations
	DefaultOperationRetries = 5

	// DefaultInitialBackoff is the default initial backoff duration for retries
	DefaultInitialBackoff = 1 * time.Second

	// DefaultMaxBackoff is the default maximum backoff duration for retries
	DefaultMaxBackoff = 30 * time.Second
)

Default configuration values for DNS operations

Functions

func RetryWithBackoff

func RetryWithBackoff(ctx context.Context, operation func() error, maxRetries int, initialBackoff, maxBackoff time.Duration) error

RetryWithBackoff executes the given function with exponential backoff retry logic. It will retry the function until it succeeds or the maximum number of retries is reached.

Parameters:

• ctx: Context for timeout and cancellation
• operation: Function to execute
• maxRetries: Maximum number of retry attempts
• initialBackoff: Initial backoff duration
• maxBackoff: Maximum backoff duration

Returns:

• error: The last error returned by the operation, or nil if it succeeded

Types

type ApiDnsRecord

type ApiDnsRecord struct {
	Id       string `json:"id"                        parameters:"record-id"`
	Type     string `json:"type"                      parameters:"record-type"`
	Host     string `json:"host"`
	Record   string `json:"record,omitempty"`
	Failover string `json:"failover"`
	Ttl      string `json:"ttl"`
	CAAFlag  uint8  `json:"caa_flag,string,omitempty"`
	CAAType  string `json:"caa_type,omitempty"`
	CAAValue string `json:"caa_value,omitempty"`
	Priority uint16 `json:"priority,string,omitempty"`
	Port     uint16 `json:"port,string,omitempty"`
	Weight   uint16 `json:"weight,string,omitempty"`
	Status   int    `json:"status"`
}

ApiDnsRecord represents a DNS record retrieved from or sent to the API. It includes fields for record identification, configuration, and status.

type ApiResponse

type ApiResponse struct {
	Status            string `json:"status"`
	StatusDescription string `json:"statusDescription"`
	Data              struct {
		Id int `json:"id"`
	} `json:"data,omitempty"`
}

ApiResponse represents the structure of a standard response from the API, including status and optional data.

type Client

type Client struct {
	AuthId       string `json:"auth_id"`
	SubAuthId    string `json:"sub_auth_id"`
	AuthPassword string `json:"auth_password"`
}

func UseClient

func UseClient(authId, subAuthId, authPassword string) *Client

UseClient initializes and returns a new Client instance with provided authentication details.

func (*Client) AddRecord

func (c *Client) AddRecord(ctx context.Context, zone string, record ApiDnsRecord) (libdns.Record, error)

AddRecord creates a new DNS record in the specified zone with the given properties and returns the created record or an error. It handles API communication, response parsing, and error handling.

Parameters:

• ctx: Context for timeout and cancellation
• zone: The DNS zone (domain) to add the record to
• record: The DNS record to add

Returns:

• libdns.Record: The created record
• error: Any error that occurred during the operation

func (*Client) DeleteRecord

func (c *Client) DeleteRecord(ctx context.Context, zone string, recordId string) error

DeleteRecord deletes a DNS record identified by its ID in the specified zone.

Parameters:

• ctx: Context for timeout and cancellation
• zone: The DNS zone (domain) containing the record
• recordId: ID of the record to delete

Returns:

• libdns.Record: The deleted record, or nil if the record was not found
• error: Any error that occurred during the operation

func (*Client) GetClouDNSRecords

func (c *Client) GetClouDNSRecords(ctx context.Context, zone string) ([]ApiDnsRecord, error)

GetClouDNSRecords returns the raw upstream results from ClouDNS. For use when the IDs of the individual records needs to be preserved, which cannot be done with the generic libdns.Record interface.

Parameters:

• ctx: Context for timeout and cancellation
• zone: The DNS zone (domain) to retrieve records from

Returns:

• []ApiDnsRecord: Slice of all DNS records in the zone
• error: Any error that occurred during the operation

func (*Client) GetRecords

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

GetRecords retrieves DNS records for the specified zone. It returns a slice of libdns.Record or an error if the request fails.

func (*Client) UpdateRecord

func (c *Client) UpdateRecord(ctx context.Context, zone string, record ApiDnsRecord) (libdns.Record, error)

UpdateRecord updates an existing DNS record in the specified zone with the provided values and returns the updated record. It handles API communication, response parsing, and error handling.

Parameters:

• ctx: Context for timeout and cancellation
• zone: The DNS zone (domain) containing the record
• record: The record to update

Returns:

• libdns.Record: The updated record
• error: Any error that occurred during the operation

type Provider

type Provider struct {
	AuthId           string        `json:"auth_id,omitempty"`
	SubAuthId        string        `json:"sub_auth_id,omitempty"`
	AuthPassword     string        `json:"auth_password"`
	OperationRetries int           `json:"operation_retries,omitempty"`
	InitialBackoff   time.Duration `json:"initial_backoff,omitempty"`
	MaxBackoff       time.Duration `json:"max_backoff,omitempty"`
}

Provider facilitates DNS record manipulation with ClouDNS.

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.

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.

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) SetRecords

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

SetRecords sets the records in the zone, either by updating existing records or creating new ones. ClouDNS does not offer an atomic update, so updates here can leave the zone in an inconsistent state upon error. No rollback is attempted.

All updates are attempted, even if an error is encountered. All successfully updated records are returned.