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
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/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
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/readyzreturns503until the first valid snapshot is loaded. After that, FastAPI being down does not fail readiness.GET /api/metareports the cache state undercache:source,last_success_at,last_error,next_retry_at,failures.GET /api/forecastcalls FastAPI/predict, remembers the last good points persensor|horizon|scenario, and serves them with"cached": truewhen 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):
- starts FastAPI from the ML checkout on
:18000and the Go API on:18080; - uploads a date-range CSV subset to
POST /api/trainand polls the job (small, thenforecastby default); - verifies the live forecast still answers, scenario propagation, the 15 s heartbeat and reconnect behaviour;
- stops FastAPI, verifies
/api/meta.cache, snapshot-served sensors, the last-good forecast (cached: true) and staffing fallback; - 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 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:
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.