Files
api-go/README.md
Noel Sabia f4693af748
ci / check (push) Successful in 54s
ci / check (pull_request) Successful in 56s
ci: fix setup-go cache and refresh docs
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.
2026-11-14 09:14:09 +01:00

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/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 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.