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

Drop the local Cursor rules and point docs at the Workspace.

Browse Source 
Issues live in the ExApp Workspace; this repo keeps the Library spec and BIND guide.
This commit is contained in:
Konrad Neitzel
2026-08-25 14:00:17 +02:00
parent eff7637f86
commit afbe268cb5
7 changed files with 11 additions and 650 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/project-specification.md
+9 -17
View File
@@ -5,7 +5,7 @@
**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
- **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`.
@@ -15,9 +15,11 @@ Callers perform updates and full zone reads in Go with typed **zone data structu
| Item | Value |
|------|-------|
| Module path | `gitea.neitzel.de/konrad/go-dns` |
| Go version | 1.26.4 (workspace `go.work`) |
| Go version | Workspace `go.work` (currently 1.26.4) |
| Public package | **`godns`** (`package godns` at module root) |
| Git remote (implementation) | `ssh://git@gitea.neitzel.de:2222/konrad/go-dns.git` |
| 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 and Issues for this Library live in the Workspace under `docs/issues/`, not in this repository.
## Target environment
@@ -27,24 +29,20 @@ Callers perform updates and full zone reads in Go with typed **zone data structu
| 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 |
| Out of scope (v1) | 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** — [bind-tsig-configuration.md](bind-tsig-configuration.md) (`allow-update` + `allow-transfer` for a TSIG 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
- Exact method names follow in later Workspace Issues after the catalog is agreed
## Zone data model (logical)
@@ -62,10 +60,6 @@ Operators configure BIND so a TSIG key may **update** and **transfer** a zone (`
**[docs/bind-tsig-configuration.md](bind-tsig-configuration.md)**
## 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 |
@@ -73,14 +67,12 @@ Features are delivered through documented changes under `docs/changes/<Number>-<
| `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`.
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/ # Project docs incl. bind-tsig-configuration.md, backlog.md
docs/ # Library spec and BIND TSIG guide
```
Layout details are finalized in the setup implementation plan.