246 lines
5.9 KiB
Markdown
246 lines
5.9 KiB
Markdown
# API
|
|
|
|
Generated from the package comment and every exported declaration. Do not edit.
|
|
Regenerate with `UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1`.
|
|
|
|
## Package godns
|
|
|
|
Package godns is a library for authoritative DNS against BIND-compatible nameservers: full zone transfer (AXFR) over TCP and RFC 2136 dynamic UPDATE, authenticated with caller-supplied TSIG. Domain names are ASCII only in v1.
|
|
|
|
## Types
|
|
|
|
### Action
|
|
|
|
```go
|
|
type Action int
|
|
```
|
|
|
|
Action is one RFC 2136 UPDATE operation.
|
|
|
|
#### ActionAdd
|
|
|
|
#### ActionDelete
|
|
|
|
```go
|
|
const (
|
|
// ActionAdd inserts a record.
|
|
ActionAdd Action = iota
|
|
// ActionDelete removes one record that matches owner, type, and rdata.
|
|
ActionDelete
|
|
)
|
|
```
|
|
|
|
### Change
|
|
|
|
```go
|
|
type Change struct {
|
|
Action Action
|
|
Record Record
|
|
}
|
|
```
|
|
|
|
Change is one add or delete of one record inside an Update batch.
|
|
|
|
#### Add
|
|
|
|
```go
|
|
func Add(rec Record) Change
|
|
```
|
|
|
|
Add builds an insert change for rec.
|
|
|
|
#### Delete
|
|
|
|
```go
|
|
func Delete(rec Record) Change
|
|
```
|
|
|
|
Delete builds a delete of one matching record (owner, type, and rdata).
|
|
|
|
### Client
|
|
|
|
```go
|
|
type Client struct {
|
|
// contains filtered or unexported fields
|
|
}
|
|
```
|
|
|
|
Client is one session: one nameserver, one zone, and one TSIG key. AXFR and Update both use that key. There is no unsigned mode.
|
|
|
|
#### NewClient
|
|
|
|
```go
|
|
func NewClient(server, zone string, key TSIG) (*Client, error)
|
|
```
|
|
|
|
NewClient starts a session for one nameserver, zone, and TSIG key. server is a host or host:port. A missing port becomes 53. An IPv6 host must be written in brackets. It returns an error when server, zone, or any TSIG field is empty, when zone or the key name is not ASCII, or when server is a bare IPv6 address.
|
|
|
|
#### Client.AXFR
|
|
|
|
```go
|
|
func (c *Client) AXFR(ctx context.Context) (*TransferResult, error)
|
|
```
|
|
|
|
AXFR reads the full zone over TCP, signed with the session TSIG key. It returns an error when ctx is done, the transfer fails, a record owner is not ASCII, or the stream contains no SOA. The closing SOA of the transfer is not appended again.
|
|
|
|
#### Client.Update
|
|
|
|
```go
|
|
func (c *Client) Update(ctx context.Context, changes ...Change) (*UpdateResult, error)
|
|
```
|
|
|
|
Update sends an RFC 2136 UPDATE for changes, signed with the session TSIG key. It tries UDP, then TCP when the UDP exchange fails or the response is truncated. No changes returns success and does not contact the nameserver. It returns an error when ctx is done, a record cannot be encoded, the exchange fails, the nameserver rcode is not NOERROR, or Action is neither ActionAdd nor ActionDelete.
|
|
|
|
### RRSet
|
|
|
|
```go
|
|
type RRSet struct {
|
|
Owner string
|
|
Class string
|
|
Type string
|
|
Records []Record
|
|
}
|
|
```
|
|
|
|
RRSet groups records that share owner, class, and type.
|
|
|
|
### Record
|
|
|
|
```go
|
|
type Record struct {
|
|
Owner string
|
|
Class string
|
|
Type string
|
|
TTL uint32
|
|
RData string
|
|
}
|
|
```
|
|
|
|
Record is one resource record. Owner is a trailing-dot FQDN. Class and Type are presentation names such as IN and A. RData is the presentation-format rdata, without the owner, TTL, class, or type.
|
|
|
|
#### A
|
|
|
|
```go
|
|
func A(owner string, ttl uint32, ip net.IP) (Record, error)
|
|
```
|
|
|
|
A builds an IN A record. It returns an error when ip is not IPv4, or when owner is empty or not ASCII. Owner is stored as a trailing-dot FQDN.
|
|
|
|
#### AAAA
|
|
|
|
```go
|
|
func AAAA(owner string, ttl uint32, ip net.IP) (Record, error)
|
|
```
|
|
|
|
AAAA builds an IN AAAA record. It returns an error when ip is missing, is IPv4, or when owner is empty or not ASCII. Owner is stored as a trailing-dot FQDN.
|
|
|
|
#### CAA
|
|
|
|
```go
|
|
func CAA(owner string, ttl uint32, flag uint8, tag, value string) (Record, error)
|
|
```
|
|
|
|
CAA builds an IN CAA record (RFC 8659) with flag, tag, and value. It returns an error when owner is empty or not ASCII.
|
|
|
|
#### CNAME
|
|
|
|
```go
|
|
func CNAME(owner string, ttl uint32, target string) (Record, error)
|
|
```
|
|
|
|
CNAME builds an IN CNAME record pointing at target. It returns an error when owner or target is empty or not ASCII.
|
|
|
|
#### MX
|
|
|
|
```go
|
|
func MX(owner string, ttl uint32, pref uint16, target string) (Record, error)
|
|
```
|
|
|
|
MX builds an IN MX record for preference pref and exchanger target. It returns an error when owner or target is empty or not ASCII.
|
|
|
|
#### NS
|
|
|
|
```go
|
|
func NS(owner string, ttl uint32, target string) (Record, error)
|
|
```
|
|
|
|
NS builds an IN NS record pointing at target. It returns an error when owner or target is empty or not ASCII.
|
|
|
|
#### PTR
|
|
|
|
```go
|
|
func PTR(owner string, ttl uint32, target string) (Record, error)
|
|
```
|
|
|
|
PTR builds an IN PTR record pointing at target. It returns an error when owner or target is empty or not ASCII.
|
|
|
|
#### SRV
|
|
|
|
```go
|
|
func SRV(owner string, ttl uint32, prio, weight, port uint16, target string) (Record, error)
|
|
```
|
|
|
|
SRV builds an IN SRV record. It returns an error when owner or target is empty or not ASCII.
|
|
|
|
#### TXT
|
|
|
|
```go
|
|
func TXT(owner string, ttl uint32, text string) (Record, error)
|
|
```
|
|
|
|
TXT builds an IN TXT record whose rdata is text. It returns an error when owner is empty or not ASCII.
|
|
|
|
### TSIG
|
|
|
|
```go
|
|
type TSIG struct {
|
|
Name string
|
|
Algorithm string
|
|
Secret string
|
|
}
|
|
```
|
|
|
|
TSIG is caller-supplied key material. The library does not generate keys or write BIND configuration. Name is the key name presented to the nameserver. Algorithm is a BIND name such as hmac-sha256 (also hmac-md5, hmac-sha1, hmac-sha224, hmac-sha384, and hmac-sha512). Secret is the base64 secret.
|
|
|
|
### TransferResult
|
|
|
|
```go
|
|
type TransferResult struct {
|
|
Zone Zone
|
|
Serial uint32
|
|
}
|
|
```
|
|
|
|
TransferResult is a completed AXFR. Serial is the SOA serial and is the same value stored on Zone.
|
|
|
|
### UpdateResult
|
|
|
|
```go
|
|
type UpdateResult struct {
|
|
Rcode string
|
|
}
|
|
```
|
|
|
|
UpdateResult is a successful UPDATE response. Rcode is the nameserver rcode text, which is NOERROR on success.
|
|
|
|
### Zone
|
|
|
|
```go
|
|
type Zone struct {
|
|
Origin string
|
|
Serial uint32
|
|
Records []Record
|
|
}
|
|
```
|
|
|
|
Zone is an in-memory zone: origin, SOA serial, and a flat record list. AXFR returns one. Callers can also assemble a Zone and call RRSets.
|
|
|
|
#### Zone.RRSets
|
|
|
|
```go
|
|
func (z Zone) RRSets() []RRSet
|
|
```
|
|
|
|
RRSets groups Zone records by owner, class, and type, in first-seen order.
|
|
|