konrad/go-dns
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document every exported symbol and how callers use the library.

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
konrad
2026-09-29 19:25:43 +02:00
co-authored by Cursor
parent c2cdd85ef1
commit 1bb7abd96b
10 changed files with 842 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/project-specification.md
+15 -12
View File
@@ -4,18 +4,18 @@
**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))
- **Dynamic updates** — RFC 2136 add and delete of records ([RFC 2136](https://www.rfc-editor.org/rfc/rfc2136)); prerequisite sections are out of scope
- **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`.
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 | Workspace `go.work` (currently 1.26.4) |
| 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` |
@@ -34,21 +34,21 @@ This is a **Library** in the ExApp Workspace. Workspace Go rules live in `.curso
## 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
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](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
- **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](guide.md). Every exported symbol: [api.md](api.md)
## Zone data model (logical)
| Type | Purpose |
|------|---------|
| **Record** | Single RR: owner, class, type, TTL, typed rdata |
| **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 |
@@ -58,21 +58,24 @@ This is a **Library** in the ExApp Workspace. Workspace Go rules live in `.curso
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)**
**[bind-tsig-configuration.md](bind-tsig-configuration.md)**
## Tests
| Command | Purpose |
|---------|---------|
| `go test ./...` | Unit tests (encoding, parsing, zone model, typed builders) |
| `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 (planned)
## Package layout
```
package godns # public API at module root
internal/ # RFC 2136, AXFR, TSIG, wire format
docs/ # Library spec and BIND TSIG guide
docs/guide.md # consumer guide
docs/api.md # generated exported API
docs/project-specification.md
docs/bind-tsig-configuration.md
```