# go-dns

Shared Go library for authoritative DNS against BIND-compatible nameservers: full zone transfer (AXFR) and RFC 2136 dynamic UPDATE, authenticated with a caller-supplied TSIG key.

Import: `gitea.neitzel.de/konrad/go-dns` (package `godns`).

```bash
go get gitea.neitzel.de/konrad/go-dns
```

- [Guide](docs/guide.md) — how to call each capability
- [API](docs/api.md) — every exported symbol
- [Domain language](CONTEXT.md)

## Included

- [Session](docs/guide.md#session) — one nameserver, zone, and TSIG key
- [AXFR](docs/guide.md#axfr) — full zone read over TCP
- [UPDATE](docs/guide.md#update) — RFC 2136 add and delete (UDP, then TCP)
- [TSIG](docs/guide.md#tsig) — caller-supplied key name, algorithm, and base64 secret
- [Typed RR builders](docs/guide.md#typed-rr-builders) — A, AAAA, MX, TXT, CNAME, NS, SRV, PTR, CAA
- [Zone, RRSet, and Record](docs/guide.md#zone-rrset-and-record) — in-memory zone model

## Excluded

- IXFR
- TSIG key generation and BIND configuration (see [BIND TSIG configuration](docs/bind-tsig-configuration.md))
- DNSSEC signing or validation
- Non-ASCII and IDN names

## Testing

Unit tests cover message construction and record builders. They do not need a nameserver.

Optional BIND integration tests use the `integration` build tag and Docker. See `bind_integration_test.go`.

```bash
go test ./...
go test -tags=integration ./...
```

`go test ./...` fails when [`docs/api.md`](docs/api.md) does not match the exported API. Regenerate it with:

```bash
UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1
```

Runnable package examples (construction only, no live nameserver): `go test -run Example`.

## Related

- **CheckDNS** — ExApp that consumes this library
- [Project specification](docs/project-specification.md)
- [BIND TSIG configuration](docs/bind-tsig-configuration.md)