Add CONTEXT.md, consumer README skeleton, and package Examples.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-27 22:00:02 +02:00
parent 992899c354
commit a722194b5a
3 changed files with 120 additions and 12 deletions
@@ -1,24 +1,61 @@
 # go-dns

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

- **Dynamic updates** — `nsupdate`-style changes (RFC 2136)
- **Zone transfer** — full zone read via **AXFR** (IXFR out of scope for v1)
- **TSIG key authentication** (callers provide keys; generation out of scope)
-
-## Status
-
-Library: AXFR over TCP, RFC 2136 UPDATE (UDP with TCP fallback), caller-supplied TSIG, typed RR builders. ASCII names only.
-
-## Module
+Import: `gitea.neitzel.de/konrad/go-dns` (package `godns`).

 ```bash
 go get gitea.neitzel.de/konrad/go-dns
 ```

-Module path: `gitea.neitzel.de/konrad/go-dns` — import as **`godns`**.
+## Scope

-## Documentation
+**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 (ASCII names)
+- **Zone / RRSet / Record** — in-memory zone model from AXFR
+
+**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.
+
+## Testing
+
+Unit tests cover message construction and record builders. Optional BIND integration tests live behind build tags / env (see `bind_integration_test.go`).
+
+## Related
+
+- **CheckDNS** — ExApp that consumes this library
 - [Project specification](docs/project-specification.md)
 - [BIND TSIG configuration](docs/bind-tsig-configuration.md)