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 — same semantics as nsupdate (RFC 2136)
• 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 typed zone data structures 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	Workspace go.work (currently 1.26.4)
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 and Issues for this Library live in the Workspace under docs/issues/, 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, prerequisites, batch UPDATE; typed RR builders
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 (e.g. A, AAAA, MX, SRV) — not a generic (type, rdata string) API
• Exact method names follow in later Workspace Issues after the catalog is agreed

Zone data model (logical)

Type	Purpose
Record	Single RR: owner, class, type, TTL, typed 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:

docs/bind-tsig-configuration.md

Tests

Command	Purpose
go test ./...	Unit tests (encoding, parsing, zone model, typed builders)
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 (planned)

package godns          # public API at module root
internal/              # RFC 2136, AXFR, TSIG, wire format
docs/                  # Library spec and BIND TSIG guide