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 backlog
• 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	1.26.4 (workspace go.work)
Public package	godns (package godns at module root)
Git remote (implementation)	ssh://git@gitea.neitzel.de:2222/konrad/go-dns.git

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 (initially)	IXFR, full DNS server, recursive resolver, TSIG key generation, IDNA

Supported operation surface

The authoritative list lives in change 00001-setup-project (spec.md). Summary:

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 — docs/bind-tsig-configuration.md (how to set allow-update + allow-transfer for a key)

Future work: backlog.md (includes IXFR).

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 subsequent changes 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). Requirements and example are in the change spec; the standalone guide will live at docs/bind-tsig-configuration.md (written during implementation).

Change workflow

Features are delivered through documented changes under docs/changes/<Number>-<short-description>/ (spec → plan → implement → verify → changes). The product backlog lives at backlog.md.

Tests

Command	Purpose
go test ./...	Unit tests (encoding, parsing, zone model, typed builders)
go test -tags=integration ./...	BIND testcontainer (Docker required)

Integration tests use testcontainers-go with a BIND image per workspace integration-testing.mdc.

Package layout (planned)

package godns          # public API at module root
internal/              # RFC 2136, AXFR, TSIG, wire format
docs/                  # Project docs incl. bind-tsig-configuration.md, backlog.md

Layout details are finalized in the setup implementation plan.