# 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`.