setup-go@v5 aborts when go.sum is missing, and this stdlib-only module has none. Disable the action cache and cap the job at 10 minutes. Lead the README with what the service does and a runnable quick start, fix stale contract and cache comments, and remove comments that only restate the code.
5.0 KiB
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.