Scaffold tomswallapi control-plane service

2026-07-19 13:31:14 +10:00
commit 6de48552fb
19 changed files with 1021 additions and 0 deletions
@@ -0,0 +1,64 @@
+# tomswallapi
+
+Fleet control plane for [tomswall](https://git.unkin.net/unkin/tomswall).
+
+Declare zones, address groups, and firewall policy **once**; the API compiles each
+intent into the concrete per-device rules every firewall and router on the path
+needs, and serves each device its rendered `tomswall.yaml`. A connection that
+crosses several firewalls — `src → rt1 → rt2 → rt3 → dest` — is expressed as a
+single rule.
+
+The full design (data model, compile algorithm, invariants, agent protocol) lives
+in [`DESIGN.md`](https://git.unkin.net/unkin/tomswall/src/branch/main/DESIGN.md) in
+the tomswall repo.
+
+## Architecture
+
+- **tomswallapi** (this repo) — Terraform-managed HTTP API. Stores the fleet model
+  in Postgres, peers with FRR for reachability, compiles intents into per-device
+  configs, and serves them.
+- **tomswall agent** — pulls its rendered config, runs the existing differential
+  `apply`, maintains dns-backed ipsets via an on-device resolver, and reports the
+  config generation it has applied. Does **not** fail closed on API-unreachable.
+
+## Running locally
+
+```sh
+docker compose up --build
+# API on :8000, Postgres on :5432
+curl -s localhost:8000/healthz
+```
+
+## Configuration
+
+All configuration is via environment variables (`TOMSWALLAPI_*`):
+
+| var | default | purpose |
+|---|---|---|
+| `TOMSWALLAPI_LISTEN_ADDR` | `:8000` | HTTP listen address |
+| `TOMSWALLAPI_DB_HOST` | `localhost` | Postgres host |
+| `TOMSWALLAPI_DB_PORT` | `5432` | Postgres port |
+| `TOMSWALLAPI_DB_USER` | `tomswallapi` | Postgres user |
+| `TOMSWALLAPI_DB_PASSWORD` | — | Postgres password |
+| `TOMSWALLAPI_DB_NAME` | `tomswallapi` | Postgres database |
+| `TOMSWALLAPI_DB_SSLMODE` | `disable` | Postgres sslmode |
+| `TOMSWALLAPI_WRITE_TOKEN` | — | bearer token guarding mutating endpoints (Terraform) |
+| `TOMSWALLAPI_AGENT_TOKEN` | — | bearer token guarding the per-device config endpoint (agents) |
+| `TOMSWALLAPI_IPLOCATE_API_KEY` | — | iplocate key for ASN address-group expansion |
+
+Migrations are embedded and applied automatically on startup.
+
+## Development
+
+```sh
+make build      # build the binary
+make test       # run tests
+make lint       # gofmt + go vet
+make run        # build and run
+```
+
+## Releases
+
+`make patch|minor|major` computes and pushes the next `v*` tag, which triggers the
+Woodpecker docker pipeline to build and push the image to
+`git.unkin.net/unkin/tomswallapi`.