go-dns/docs/project-specification.md

go-dns — Project Specification

Overview

go-dns is a Go library for authoritative DNS operations against BIND (and compatible servers):

• Dynamic updates — RFC 2136 add and delete of records (RFC 2136); prerequisite sections are out of scope
• Zone transfer — full AXFR only (RFC 5936); IXFR is out of scope for v1
• TSIG authentication — callers supply existing shared keys; key generation is out of scope

Callers perform updates and full zone reads in Go with an in-memory zone (Record rdata is presentation format) and typed RR builders instead of shelling out to nsupdate or dig axfr.

Module metadata

Item	Value
Module path	gitea.neitzel.de/konrad/go-dns
Go version	go 1.27.0 in this module's go.mod
Public package	godns (package godns at module root)
Git remote	ssh://git@gitea.neitzel.de:2222/konrad/go-dns.git

This is a Library in the ExApp Workspace. Workspace Go rules live in .cursor/rules/ (go.mdc, go-testing.mdc). Specs, Issues, and ADRs for this Library live in the Workspace (docs/issues/, docs/adr/go-dns/), not in this repository.

Target environment

Item	Value
Nameserver	BIND 9.x (primary reference)
Protocols	RFC 2136 UPDATE (UDP + automatic TCP fallback); AXFR over TCP
Authentication	TSIG (RFC 2845 / RFC 8945) — required for documented happy path
Domain names	ASCII only in v1 (no IDNA)
Out of scope (v1)	IXFR, full DNS server, recursive resolver, TSIG key generation, IDNA

Supported operation surface

1. Session & TSIG key — server, zone, transport, existing key (name, algorithm, secret)
2. Dynamic update — add, delete, and batch UPDATE; typed RR builders (A, AAAA, MX, TXT, CNAME, NS, SRV, PTR, CAA)
3. Zone transfer — AXFR only; parse stream into zone data
4. Zone data model — Record, RRSet, Zone, UpdateResult, TransferResult
5. BIND guide — bind-tsig-configuration.md (allow-update + allow-transfer for a TSIG key)

API style

• Typed builders per RR type (A, AAAA, MX, TXT, CNAME, NS, SRV, PTR, CAA) — not a generic (type, rdata string) API
• How to call them: guide.md. Every exported symbol: api.md

Zone data model (logical)

Type	Purpose
Record	Single RR: owner, class, type, TTL, presentation-format rdata
RRSet	Group of RRs with same owner/class/type
Zone	Origin + full record set + SOA/serial (complete zone in memory)
UpdateResult	UPDATE response status
TransferResult	AXFR result + populated Zone + serial metadata

BIND configuration

Operators configure BIND so a TSIG key may update and transfer a zone (allow-update, allow-transfer). Step-by-step instructions, security notes, and a minimal named.conf example:

bind-tsig-configuration.md

Tests

Command	Purpose
go test ./...	Unit tests (encoding, parsing, zone model, typed builders). Fails when docs/api.md is stale
UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1	Rewrite docs/api.md after an exported API change
go test -tags=integration ./...	BIND testcontainer (Docker required)

Follow the Workspace .cursor/rules/go-testing.mdc. This Library's integration image is BIND.

Package layout

package godns          # public API at module root
docs/guide.md          # consumer guide
docs/api.md            # generated exported API
docs/project-specification.md
docs/bind-tsig-configuration.md