44 lines
2 KiB
Markdown
44 lines
2 KiB
Markdown
# Cache Service
|
|
|
|
The central hub. Sits between the Pi and Discord.
|
|
|
|
It does two things: polls the Pi on a timer to keep a local copy of the door state, and receives push webhooks from the Pi when the state actually changes. Either way, updates get written to SQLite and forwarded to downstream services via outbound webhooks.
|
|
|
|
If the Pi stops responding to polls (configurable threshold, default 3 misses), the cache marks it as offline and notifies downstream.
|
|
|
|
## API
|
|
|
|
| Method | Path | Auth | Description |
|
|
|--------|------|------|-------------|
|
|
| `GET` | `/status` | — | Current door status (`status`, `since`, `last_checked`) |
|
|
| `POST` | `/webhook` | Bearer | Inbound webhook from the Pi |
|
|
| `GET` | `/health` | — | Health check |
|
|
|
|
`since` is the Pi-reported time when the current state began. `last_checked` is when the cache most recently attempted a poll.
|
|
|
|
## Configuration
|
|
|
|
NixOS options under `services.noisebell-cache`:
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `domain` | required | Caddy virtual host domain |
|
|
| `piAddress` | required | Pi URL (e.g. `http://noisebell:80`) |
|
|
| `piApiKeyFile` | required | Key file for authenticating to the Pi |
|
|
| `inboundApiKeyFile` | required | Key file for validating inbound webhooks |
|
|
| `port` | `3000` | Listen port |
|
|
| `statusPollIntervalSecs` | `60` | How often to poll `GET /` on the Pi |
|
|
| `offlineThreshold` | `3` | Consecutive failed polls before marking offline |
|
|
| `retryAttempts` | `3` | Outbound webhook retry count |
|
|
| `retryBaseDelaySecs` | `1` | Exponential backoff base delay |
|
|
| `httpTimeoutSecs` | `10` | HTTP request timeout |
|
|
| `dataDir` | `/var/lib/noisebell-cache` | SQLite database location |
|
|
| `outboundWebhooks` | `[]` | List of `{url, secretFile}` for downstream services |
|
|
|
|
## Secrets
|
|
|
|
| Secret | What it's for |
|
|
|--------|---------------|
|
|
| `piApiKeyFile` | Bearer token to poll the Pi's GET endpoints |
|
|
| `inboundApiKeyFile` | Bearer token the Pi sends when POSTing to `/webhook` |
|
|
| `outboundWebhooks[].secretFile` | Bearer token sent with outbound webhook POSTs |
|