Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-29 19:25:43 +02:00
parent c2cdd85ef1
commit 1bb7abd96b
10 changed files with 842 additions and 81 deletions
@@ -1,6 +1,6 @@
 # go-dns

-Shared Go library for authoritative DNS against BIND-compatible nameservers: full zone transfer (AXFR) and RFC 2136 dynamic UPDATE, authenticated with caller-supplied TSIG.
+Shared Go library for authoritative DNS against BIND-compatible nameservers: full zone transfer (AXFR) and RFC 2136 dynamic UPDATE, authenticated with a caller-supplied TSIG key.

 Import: `gitea.neitzel.de/konrad/go-dns` (package `godns`).

@@ -8,51 +8,44 @@ Import: `gitea.neitzel.de/konrad/go-dns` (package `godns`).
 go get gitea.neitzel.de/konrad/go-dns
 ```

-## Scope
+- [Guide](docs/guide.md) — how to call each capability
+- [API](docs/api.md) — every exported symbol
+- [Domain language](CONTEXT.md)

-**Included**
+## Included

- **Session (`Client`)** — one nameserver + zone + TSIG key
- **AXFR** — full zone read over TCP
- **RFC 2136 UPDATE** — typed add/delete changes (UDP with TCP fallback)
- **TSIG** — caller-supplied key name, algorithm, and base64 secret
- **Typed RR builders** — A, AAAA, MX, TXT, CNAME, NS, SRV, PTR, CAA (ASCII names)
- **Zone / RRSet / Record** — in-memory zone model from AXFR
+- [Session](docs/guide.md#session) — one nameserver, zone, and TSIG key
+- [AXFR](docs/guide.md#axfr) — full zone read over TCP
+- [UPDATE](docs/guide.md#update) — RFC 2136 add and delete (UDP, then TCP)
+- [TSIG](docs/guide.md#tsig) — caller-supplied key name, algorithm, and base64 secret
+- [Typed RR builders](docs/guide.md#typed-rr-builders) — A, AAAA, MX, TXT, CNAME, NS, SRV, PTR, CAA
+- [Zone, RRSet, and Record](docs/guide.md#zone-rrset-and-record) — in-memory zone model

-**Excluded**
+## Excluded

- IXFR / incremental transfer
- TSIG key generation or BIND config writing (see docs for operator notes)
- DNSSEC signing / validation as a product feature
- Non-ASCII / IDN domain names (v1)
-
-## Usage
-
-```go
-key := godns.TSIG{
-    Name:      "exapp-key.",
-    Algorithm: "hmac-sha256",
-    Secret:    "base64-secret-from-bind",
-}
-client, err := godns.NewClient("ns.example:53", "example.com.", key)
-
-// AXFR
-tr, err := client.AXFR(ctx)
-
-// UPDATE
-rec, err := godns.A("www.example.com.", 300, net.ParseIP("192.0.2.10"))
-_, err = client.Update(ctx, godns.Add(rec))
-```
-
-Runnable package examples (construction only, no live nameserver): `go test -run Example`.
-
-## Domain language
-
-See [CONTEXT.md](./CONTEXT.md) for Session, Zone / RRSet / Record, UPDATE, AXFR, and TSIG key terminology.
+- IXFR
+- TSIG key generation and BIND configuration (see [BIND TSIG configuration](docs/bind-tsig-configuration.md))
+- DNSSEC signing or validation
+- Non-ASCII and IDN names

 ## Testing

-Unit tests cover message construction and record builders. Optional BIND integration tests live behind build tags / env (see `bind_integration_test.go`).
+Unit tests cover message construction and record builders. They do not need a nameserver.
+
+Optional BIND integration tests use the `integration` build tag and Docker. See `bind_integration_test.go`.
+
+```bash
+go test ./...
+go test -tags=integration ./...
+```
+
+`go test ./...` fails when [`docs/api.md`](docs/api.md) does not match the exported API. Regenerate it with:
+
+```bash
+UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1
+```
+
+Runnable package examples (construction only, no live nameserver): `go test -run Example`.

 ## Related