Files
api-go/README.md
T
2026-11-14 20:49:39 +01:00

122 lines
5.1 KiB
Markdown

# PulseCast API
Go service for PulseCast. It serves sensor series, live forecasts, staffing
plans and scenario state over SSE, and proxies training to FastAPI. It keeps the
FastAPI `/bootstrap` snapshot in memory, so reads survive FastAPI outages.
## Quick start
```sh
go run ./cmd/api
curl -s localhost:8080/api/healthz # {"ok":true}
curl -s localhost:8080/api/readyz # 503 until the first /bootstrap snapshot
```
The API listens on `:8080` and expects FastAPI at `http://localhost:8000`
(`FASTAPI_URL`). It starts without FastAPI; readiness stays `503` until the
first snapshot arrives. Control endpoints return `503` until `CONTROL_USER` and
`CONTROL_PASS` are set.
## Endpoints
| Endpoint | Purpose |
|---|---|
| `GET /api/healthz` | Liveness. |
| `GET /api/readyz` | Data and model readiness; `503` until the first snapshot. |
| `GET /api/meta` | Versions, coverage, metrics and cache status. |
| `GET /api/sensors` | Sensors sorted by id. |
| `GET /api/series` | Observed series; query `sensor`, `from`, `to`, `step=15m\|1h`. |
| `GET /api/context` | Weather and holidays. |
| `GET /api/forecast` | Live forecast or last-good fallback; query `sensor`, `horizon`, `scenario`. |
| `GET /api/playground/forecast` | Read-only forecast with optional `temp_c`, `precip_mm`, `is_holiday`; never mutates scenario state. |
| `GET /api/staffing` | Shift plan; query `sensor`, `scenario`, `standard`. |
| `GET /api/scenario` | Current scenario. |
| `POST /api/scenario` | Set scenario (control auth) and broadcast it over SSE. |
| `GET /api/stream` | SSE scenario events and the 15 s heartbeat. |
| `POST /api/train` | Proxy training to FastAPI (control auth). |
| `GET /api/train/{job_id}` | Training job status (control auth). |
## Checks
```sh
make check
```
Runs `go vet ./...`, `go test -count=1 ./...`, and `go build ./...`. The same
target runs in Gitea Actions on every push and pull request
(`.gitea/workflows/ci.yml`). CI does not run the integration or load tests;
those need the ML checkout and raw CSV.
## Runtime data
The API image contains **no baked data**. At startup it fetches
`GET {FASTAPI_URL}/bootstrap` and keeps `sensors`, `series`, `context` and
`meta` in memory. A background loop refreshes the snapshot; on failure it keeps
the last good snapshot and retries with exponential backoff
**1, 2, 4, 8, 16, 30 s (cap)**, resetting on success.
- `GET /api/readyz` returns `503` until the first valid snapshot is loaded.
After that, FastAPI being down does not fail readiness.
- `GET /api/meta` reports the cache state under `cache`:
`source`, `last_success_at`, `last_error`, `next_retry_at`, `failures`.
- `GET /api/forecast` calls FastAPI `/predict`, remembers the last good points
per `sensor|horizon|scenario`, and serves them with `"cached": true` when
FastAPI is unavailable.
- `testdata/` is used by tests only and is excluded from the image by
`.dockerignore`.
| Env | Default | Purpose |
|---|---|---|
| `PORT` | `8080` | HTTP listen port |
| `FASTAPI_URL` | `http://localhost:8000` | FastAPI base URL |
| `BOOTSTRAP_REFRESH` | `60s` | Healthy snapshot refresh interval |
| `BOOTSTRAP_TIMEOUT` | `20s` | Per-request `/bootstrap` timeout |
| `ML_TIMEOUT` | `1500ms` | Per-request `/predict` timeout |
| `SSE_HEARTBEAT` | `15s` | SSE ping interval |
| `CONTROL_USER` / `CONTROL_PASS` | unset | Basic auth for `POST /api/scenario` and `/api/train*` |
| `CONTROL_TOKEN` | unset | Optional Bearer token forwarded to FastAPI `/train*` |
## Integration and load test
`make integration` runs the real stack (it refuses to start if `:18000` or
`:18080` is busy):
1. starts FastAPI from the ML checkout on `:18000` and the Go API on `:18080`;
2. uploads a date-range CSV subset to `POST /api/train` and polls the job
(`small`, then `forecast` by default);
3. verifies the live forecast still answers, scenario propagation, the 15 s
heartbeat and reconnect behaviour;
4. stops FastAPI, verifies `/api/meta.cache`, snapshot-served sensors, the
last-good forecast (`cached: true`) and staffing fallback;
5. restarts FastAPI and waits for the cache to recover.
`make integration-load` additionally runs `scripts/sse-load`: 120 concurrent
SSE clients for 5 minutes with a scenario change every 30 s. It records peak
connections, drops, per-change and overall p95 latency, and heartbeat cadence.
The tool exits non-zero when a client drops, an event is missing, or p95
scenario latency exceeds the contract's 2 s threshold.
Results land in `/tmp/pulsecast-integration/results` by default. Override with
`WORKDIR=/path` or `RESULTS_DIR=/path`. `make load` runs only the load test
against an API that is already up. The verified run is written up in
[`docs/integration.md`](docs/integration.md) with raw evidence under
`docs/results/`.
## Container
The image is a multi-stage build. The runtime is
`gcr.io/distroless/static-debian12:nonroot` and runs as numeric
**UID/GID `65532:65532`** (`USER 65532:65532` in the `Dockerfile`).
Use the same numbers in Kubernetes:
```yaml
securityContext:
runAsUser: 65532
runAsGroup: 65532
runAsNonRoot: true
```
Do not use named users such as `nonroot` in a `securityContext`: the kubelet
cannot verify a non-numeric image user.