gdns

README

gdns

This is a library and a CLI tool for interacting with the Gandi LiveDNS API.

CLI

The CLI supports the following features:

• Listing available domains
• Retrieving information about specific domains
• Retrieving the nameservers for specific domains
• Listing, adding, updating, and removing records for specific domains

As an example, let's say we want to add a new record to the example.com domain:

$ gdns records add example.com <("foo a 10.0.0.1")

But, oops, we used the wrong value for the record:

$ gdns records update example.com <("foo a 10.0.0.2")

And then later we decide that we need to remove that record:

$ gdns records remove example.com <("foo a 10.0.0.2")

See gdns help for more information.

CLI Configuration

The CLI tool requires your API key or token in order to work correctly. Use gdns config generate to generate a configuration file. The app will look for .gdns.yaml in the current directory, the $HOME directory, or the directory specified in the environment variable GDNS_CONFIG_FILE.

The config file may also be omitted by providing either of the environment variables: GDNS_API_KEY or GDNS_BEARER_TOKEN.

Documentation

Index

• Variables
• func InterceptorChain(rt http.RoundTripper, interceptors ...Interceptor) http.RoundTripper
• type Client
  • func New(opts ...Option) (*Client, error)
  • func (c *Client) AddDomainRecord(fqdn string, record RecordSet) (int, error)
  • func (c *Client) AddRecordByName(fqdn string, record RecordSet) (int, error)
  • func (c *Client) AddRecordByNameAndType(fqdn string, record RecordSet) (int, error)
  • func (c *Client) GetDomainInfo(fqdn string) (*DomainInfo, error)
  • func (c *Client) GetDomainRecords(fqdn string, rqp *RecordsQueryParams) ([]RecordSet, *PagingDetails, error)
  • func (c *Client) GetDomains(params *DomainsQueryParams) ([]DomainInfo, *PagingDetails, error)
  • func (c *Client) GetNameservers(fqdn string) ([]string, error)
  • func (c *Client) GetRecordTypes() ([]string, error)
  • func (c *Client) GetRecordsByName(fqdn string, name string) ([]RecordSet, error)
  • func (c *Client) GetRecordsByNameAndType(fqdn string, name string, kind string) ([]RecordSet, error)
  • func (c *Client) RemoveAllDomainRecords(fqdn string) (int, error)
  • func (c *Client) RemoveAllRecordsWithName(fqdn string, name string) (int, error)
  • func (c *Client) RemoveRecordByNameAndType(fqdn string, record RecordSet) (int, error)
  • func (c *Client) ReplaceAllRecordsByName(fqdn string, records []RecordSet) (int, error)
  • func (c *Client) ReplaceDomainRecords(fqdn string, records []RecordSet) (int, error)
  • func (c *Client) ReplaceRecordByNameAndType(fqdn string, record RecordSet) (int, error)
  • func (c *Client) UpdateDomainInfo(fqdn string, info DomainInfo) (int, error)
• type DomainInfo
• type DomainsQueryParams
  • func (dqp *DomainsQueryParams) Values() url.Values
• type Interceptor
  • func AuthInterceptor(authHeader string) Interceptor
• type InterceptorRT
  • func (irt InterceptorRT) RoundTrip(req *http.Request) (*http.Response, error)
• type Option
  • func WithApiKey(key string) Option
  • func WithBaseUrl(value url.URL) Option
  • func WithHttpDebug() Option
  • func WithPersonalAccessToken(token string) Option
• type PagingDetails
• type QueryParams
• type RecordSet
• type RecordsQueryParams
  • func (rqp *RecordsQueryParams) Values() url.Values

Variables

var ErrAuthAlreadyDefined = errors.New("only one authorization token may be set at a time")

var ErrAuthTokenRequired = errors.New("one of api key or personal access token must be set")

var ErrEmptySet = errors.New("required set is empty")

var ErrHttpReqFailed = errors.New("failed to get data from Gandi")

var ErrMismatch = errors.New("values do not match")

var ErrMissingRequiredField = errors.New("missing required field")

var ErrParseResFailed = errors.New("failed to parse response from Gandi")

var ErrRecordExists = errors.New("record already exists according to Gandi")

Functions

func InterceptorChain

func InterceptorChain(rt http.RoundTripper, interceptors ...Interceptor) http.RoundTripper

InterceptorChain is a series of Interceptor functions that will be applied on each request. A chain should be supplied as the http.Client.Transport on a http client.

Types

type Client

type Client struct {
	BaseUrl url.URL
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) (*Client, error)

func (*Client) AddDomainRecord

func (c *Client) AddDomainRecord(fqdn string, record RecordSet) (int, error)

AddDomainRecord implements https://api.gandi.net/docs/livedns/#post-v5-livedns-domains-fqdn-records

func (*Client) AddRecordByName

func (c *Client) AddRecordByName(fqdn string, record RecordSet) (int, error)

AddRecordByName implements https://api.gandi.net/docs/livedns/#post-v5-livedns-domains-fqdn-records-rrset_name

func (*Client) AddRecordByNameAndType

func (c *Client) AddRecordByNameAndType(fqdn string, record RecordSet) (int, error)

AddRecordByNameAndType implements https://api.gandi.net/docs/livedns/#post-v5-livedns-domains-fqdn-records-rrset_name-rrset_type

func (*Client) GetDomainInfo

func (c *Client) GetDomainInfo(fqdn string) (*DomainInfo, error)

GetDomainInfo implements the `GET` method of https://api.gandi.net/docs/livedns/#v5-livedns-domains-fqdn

func (*Client) GetDomainRecords

func (c *Client) GetDomainRecords(fqdn string, rqp *RecordsQueryParams) ([]RecordSet, *PagingDetails, error)

GetDomainRecords implements https://api.gandi.net/docs/livedns/#get-v5-livedns-domains-fqdn-records

func (*Client) GetDomains

func (c *Client) GetDomains(params *DomainsQueryParams) ([]DomainInfo, *PagingDetails, error)

GetDomains implements https://api.gandi.net/docs/livedns/#get-v5-livedns-domains

The returned list of DomainInfo will only have the Fqdn, Href, and RecordsHref properties set as described by the API documentation.

func (*Client) GetNameservers

func (c *Client) GetNameservers(fqdn string) ([]string, error)

GetNameservers implements https://api.gandi.net/docs/livedns/#patch-v5-livedns-domains-fqdn

func (*Client) GetRecordTypes

func (c *Client) GetRecordTypes() ([]string, error)

GetRecordTypes implements https://api.gandi.net/docs/livedns/#get-v5-livedns-dns-rrtypes

func (*Client) GetRecordsByName

func (c *Client) GetRecordsByName(fqdn string, name string) ([]RecordSet, error)

GetRecordsByName implements https://api.gandi.net/docs/livedns/#get-v5-livedns-domains-fqdn-records-rrset_name

func (*Client) GetRecordsByNameAndType

func (c *Client) GetRecordsByNameAndType(fqdn string, name string, kind string) ([]RecordSet, error)

GetRecordsByNameAndType implements https://api.gandi.net/docs/livedns/#get-v5-livedns-domains-fqdn-records-rrset_name-rrset_type

func (*Client) RemoveAllDomainRecords

func (c *Client) RemoveAllDomainRecords(fqdn string) (int, error)

RemoveAllDomainRecords implements https://api.gandi.net/docs/livedns/#delete-v5-livedns-domains-fqdn-records

func (*Client) RemoveAllRecordsWithName

func (c *Client) RemoveAllRecordsWithName(fqdn string, name string) (int, error)

RemoveAllRecordsWithName implements https://api.gandi.net/docs/livedns/#delete-v5-livedns-domains-fqdn-records-rrset_name

func (*Client) RemoveRecordByNameAndType

func (c *Client) RemoveRecordByNameAndType(fqdn string, record RecordSet) (int, error)

RemoveRecordByNameAndType implements https://api.gandi.net/docs/livedns/#delete-v5-livedns-domains-fqdn-records-rrset_name-rrset_type

func (*Client) ReplaceAllRecordsByName

func (c *Client) ReplaceAllRecordsByName(fqdn string, records []RecordSet) (int, error)

ReplaceAllRecordsByName implements https://api.gandi.net/docs/livedns/#put-v5-livedns-domains-fqdn-records-rrset_name

func (*Client) ReplaceDomainRecords

func (c *Client) ReplaceDomainRecords(fqdn string, records []RecordSet) (int, error)

ReplaceDomainRecords implements https://api.gandi.net/docs/livedns/#put-v5-livedns-domains-fqdn-records

func (*Client) ReplaceRecordByNameAndType

func (c *Client) ReplaceRecordByNameAndType(fqdn string, record RecordSet) (int, error)

ReplaceRecordByNameAndType implements https://api.gandi.net/docs/livedns/#put-v5-livedns-domains-fqdn-records-rrset_name-rrset_type

func (*Client) UpdateDomainInfo

func (c *Client) UpdateDomainInfo(fqdn string, info DomainInfo) (int, error)

UpdateDomainInfo implements https://api.gandi.net/docs/livedns/#patch-v5-livedns-domains-fqdn

type DomainInfo

type DomainInfo struct {
	Fqdn               string `json:"fqdn"`
	Href               string `json:"domain_href"`
	RecordsHref        string `json:"domain_records_href"`
	KeysHref           string `json:"domain_keys_href"`
	AutomaticSnapshots bool   `json:"automatic_snapshots"`
}

type DomainsQueryParams

type DomainsQueryParams struct {
	Page      int    `json:"page"`
	PerPage   int    `json:"per_page"`
	SharingId string `json:"sharing_id"`
}

DomainsQueryParams represent the query parameters supported by Client.GetDomains.

func (*DomainsQueryParams) Values

func (dqp *DomainsQueryParams) Values() url.Values

type Interceptor

type Interceptor func(http.RoundTripper) InterceptorRT

Interceptor is a function that can perform actions on a request before and/or after sending.

func AuthInterceptor

func AuthInterceptor(authHeader string) Interceptor

type InterceptorRT

type InterceptorRT func(*http.Request) (*http.Response, error)

InterceptorRT implements the http.RoundTripper interface and simplifies creating new middlewares by eliminating the need for middlewares to implement the interface.

func (InterceptorRT) RoundTrip

func (irt InterceptorRT) RoundTrip(req *http.Request) (*http.Response, error)

type Option

type Option func(c *Client) error

func WithApiKey

func WithApiKey(key string) Option

func WithBaseUrl

func WithBaseUrl(value url.URL) Option

func WithHttpDebug

func WithHttpDebug() Option

func WithPersonalAccessToken

func WithPersonalAccessToken(token string) Option

type PagingDetails

type PagingDetails struct {
	TotalItems int
	NextPage   *url.URL
	LastPage   *url.URL
}

PagingDetails represent endpoint paging information returned by some GET methods of the Gandi LiveDNS API. The information can be used to construct parameters for subsequent calls to the API to retrieve pages of data.

type QueryParams

type QueryParams interface {
	Values() url.Values
}

type RecordSet

type RecordSet struct {
	Href   string   `json:"rrset_href"`
	Name   string   `json:"rrset_name"`
	Type   string   `json:"rrset_type"`
	Ttl    int      `json:"rrset_ttl"`
	Values []string `json:"rrset_values"`
}

RecordSet represents a record as returned, or accepted, by the Gandi LiveDNS API.

type RecordsQueryParams

type RecordsQueryParams struct {
	Page    int
	PerPage int
	Type    string
	SortBy  string
}

RecordsQueryParams represents the URI query parameters supported by the https://api.gandi.net/docs/livedns/#v5-livedns-domains-fqdn-records API. The API documented defaults will be used when any field is set to its zero value, e.g. `Page: 0` will result in `page=1`.

func (*RecordsQueryParams) Values

func (rqp *RecordsQueryParams) Values() url.Values