chore: baseline before change C-00001-setup-project

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-04 14:26:47 +02:00
commit 47f17445d0
8 changed files with 726 additions and 0 deletions
@@ -0,0 +1,84 @@
+# 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](https://www.rfc-editor.org/rfc/rfc2136))
+- **Zone transfer** — full **AXFR** only ([RFC 5936](https://www.rfc-editor.org/rfc/rfc5936)); 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](changes/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](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](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.