Konrad NeitzelandCursor
7055eac0ae
Callers get a session API, typed RR builders, and BIND testcontainer proof so CheckDNS can stay off the DNS wire. Co-authored-by: Cursor <cursoragent@cursor.com>
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# 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 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, 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, 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](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](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
|
|
```
|