ci: fix setup-go cache and refresh docs
ci / check (push) Successful in 54s
ci / check (pull_request) Successful in 56s

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.
This commit is contained in:
Noel Sabia committed 2026-11-14 09:14:09 +01:00
1 parent 80c8eeb0b9
commit f4693af748
12 files changed
+66 -26

No files matched your search

+4
View File
@@ -10,6 +10,7 @@ permissions:
jobs: jobs:
check: check:
runs-on: ubuntu-latest runs-on: ubuntu-latest
timeout-minutes: 10
steps: steps:
- name: Check out - name: Check out
uses: actions/checkout@v4 uses: actions/checkout@v4
@@ -18,6 +19,9 @@ jobs:
uses: actions/setup-go@v5 uses: actions/setup-go@v5
with: with:
go-version-file: go.mod go-version-file: go.mod
# The module is stdlib-only, so there is no go.sum for the action's
# default cache key. Remove this once the module has dependencies.
cache: false
- name: Check - name: Check
run: make check run: make check
+40 -5
View File
@@ -1,6 +1,39 @@
# api-go # PulseCast API
Golang API that is the backbone for daily usage, while python works in batches and is heavy in compute while Golang handles concurrent usage cheap 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/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 ## Checks
@@ -10,7 +43,8 @@ make check
Runs `go vet ./...`, `go test -count=1 ./...`, and `go build ./...`. The same Runs `go vet ./...`, `go test -count=1 ./...`, and `go build ./...`. The same
target runs in Gitea Actions on every push and pull request target runs in Gitea Actions on every push and pull request
(`.gitea/workflows/ci.yml`). (`.gitea/workflows/ci.yml`). CI does not run the integration or load tests;
those need the ML checkout and raw CSV.
## Runtime data ## Runtime data
@@ -32,10 +66,12 @@ the last good snapshot and retries with exponential backoff
| Env | Default | Purpose | | Env | Default | Purpose |
|---|---|---| |---|---|---|
| `PORT` | `8080` | HTTP listen port |
| `FASTAPI_URL` | `http://localhost:8000` | FastAPI base URL | | `FASTAPI_URL` | `http://localhost:8000` | FastAPI base URL |
| `BOOTSTRAP_REFRESH` | `60s` | Healthy snapshot refresh interval | | `BOOTSTRAP_REFRESH` | `60s` | Healthy snapshot refresh interval |
| `BOOTSTRAP_TIMEOUT` | `20s` | Per-request `/bootstrap` timeout | | `BOOTSTRAP_TIMEOUT` | `20s` | Per-request `/bootstrap` timeout |
| `ML_TIMEOUT` | `1500ms` | Per-request `/predict` 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_USER` / `CONTROL_PASS` | unset | Basic auth for `POST /api/scenario` and `/api/train*` |
| `CONTROL_TOKEN` | unset | Optional Bearer token forwarded to FastAPI `/train*` | | `CONTROL_TOKEN` | unset | Optional Bearer token forwarded to FastAPI `/train*` |
@@ -45,7 +81,7 @@ the last good snapshot and retries with exponential backoff
`:18080` is busy): `:18080` is busy):
1. starts FastAPI from the ML checkout on `:18000` and the Go API on `:18080`; 1. starts FastAPI from the ML checkout on `:18000` and the Go API on `:18080`;
2. uploads a 24k-row CSV subset to `POST /api/train` and polls the job 2. uploads a date-range CSV subset to `POST /api/train` and polls the job
(`small`, then `forecast` by default); (`small`, then `forecast` by default);
3. verifies the live forecast still answers, scenario propagation, the 15 s 3. verifies the live forecast still answers, scenario propagation, the 15 s
heartbeat and reconnect behaviour; heartbeat and reconnect behaviour;
@@ -65,7 +101,6 @@ 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/integration.md`](docs/integration.md) with raw evidence under
`docs/results/`. `docs/results/`.
## Container ## Container
The image is a multi-stage build. The runtime is The image is a multi-stage build. The runtime is
+1 -1
View File
@@ -56,7 +56,7 @@ verification process held `18000`/`18080`) timed `GET /api/staffing`:
| Check | Result | | Check | Result |
|---|---| |---|---|
| Cold call (live `/predict` + plan build) | **19 ms** | | Cold call (live `/predict` + plan build) | **19 ms** |
| Warm call (cached by `sensor|scenario|standard|version|weather`) | **< 1 ms** | | Warm call (same plan key) | **< 1 ms** |
| Plan size | 70 store hours (7 days × 10:00–20:00), 21 shift blocks | | Plan size | 70 store hours (7 days × 10:00–20:00), 21 shift blocks |
| Coverage | 100%, cost €3,360 | | Coverage | 100%, cost €3,360 |
| `cached` on the live plan | `false` | | `cached` on the live plan | `false` |
+1
View File
@@ -157,6 +157,7 @@ func (s *Server) handleContext(w http.ResponseWriter, _ *http.Request) {
cached := true cached := true
if s.cache != nil { if s.cache != nil {
ctx = s.cache.Context() ctx = s.cache.Context()
// A failed refresh keeps the old context in place, so mark it cached.
cached = !s.cache.Fresh() cached = !s.cache.Fresh()
} }
s.setVersions(w) s.setVersions(w)
+1
View File
@@ -87,6 +87,7 @@ func (s *Server) liveForecast(ctx context.Context, sensor, horizon, scenarioName
ctxData := s.cache.Context() ctxData := s.cache.Context()
precip := ctxData.Weather.Now.PrecipMM precip := ctxData.Weather.Now.PrecipMM
// A zero override means "no scenario rain"; keep the cached current value.
if state.Scenario.Weather.PrecipMM > 0 { if state.Scenario.Weather.PrecipMM > 0 {
precip = state.Scenario.Weather.PrecipMM precip = state.Scenario.Weather.PrecipMM
} }
+2 -2
View File
@@ -13,8 +13,8 @@ import (
"pulsecast/api/internal/model" "pulsecast/api/internal/model"
) )
// maxTrainBody bounds an uploaded CSV. The raw dataset is ~18 MB; 64 MB leaves // maxTrainBody bounds an uploaded CSV so a client cannot stream an unbounded
// room for a larger export without letting the API accept unbounded bodies. // body through the proxy.
const maxTrainBody = 64 << 20 const maxTrainBody = 64 << 20
// handleTrain proxies POST /api/train to FastAPI. The request is queued there, // handleTrain proxies POST /api/train to FastAPI. The request is queued there,
+3 -1
View File
@@ -1,5 +1,5 @@
// Package api wires the HTTP handlers, scenario state, SSE hub and cache // Package api wires the HTTP handlers, scenario state, SSE hub and cache
// fallback into the Go service described by CONTRACT.md. // fallback into the Go service.
package api package api
import ( import (
@@ -108,6 +108,8 @@ var methodTable = map[string][]string{
"/api/stream": {"GET"}, "/api/stream": {"GET"},
} }
// routeCheck keeps unknown routes and methods in the JSON error envelope;
// ServeMux would otherwise answer them in plain text.
func (s *Server) routeCheck(next http.Handler) http.Handler { func (s *Server) routeCheck(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
methods, ok := methodTable[r.URL.Path] methods, ok := methodTable[r.URL.Path]
-4
View File
@@ -286,7 +286,6 @@ func (c *Cache) Sensors() []model.Sensor {
return out return out
} }
// Sensor looks up one sensor.
func (c *Cache) Sensor(id string) (model.Sensor, bool) { func (c *Cache) Sensor(id string) (model.Sensor, bool) {
c.mu.RLock() c.mu.RLock()
defer c.mu.RUnlock() defer c.mu.RUnlock()
@@ -308,7 +307,6 @@ func (c *Cache) Series(id string) ([]model.Point, bool) {
return points, ok return points, ok
} }
// Context returns the current weather/holiday context.
func (c *Cache) Context() model.ContextData { func (c *Cache) Context() model.ContextData {
c.mu.RLock() c.mu.RLock()
defer c.mu.RUnlock() defer c.mu.RUnlock()
@@ -318,7 +316,6 @@ func (c *Cache) Context() model.ContextData {
return c.snapshot.Context return c.snapshot.Context
} }
// Versions returns data, model and context version strings.
func (c *Cache) Versions() (data, modelVersion, contextVersion string) { func (c *Cache) Versions() (data, modelVersion, contextVersion string) {
c.mu.RLock() c.mu.RLock()
defer c.mu.RUnlock() defer c.mu.RUnlock()
@@ -328,7 +325,6 @@ func (c *Cache) Versions() (data, modelVersion, contextVersion string) {
return c.snapshot.DataVersion, c.snapshot.ModelVersion, c.snapshot.ContextVersion return c.snapshot.DataVersion, c.snapshot.ModelVersion, c.snapshot.ContextVersion
} }
// Len returns the number of sensors in the current snapshot.
func (c *Cache) Len() int { func (c *Cache) Len() int {
c.mu.RLock() c.mu.RLock()
defer c.mu.RUnlock() defer c.mu.RUnlock()
+6 -6
View File
@@ -1,6 +1,6 @@
// Package ml is the FastAPI client. Prediction calls are bounded by a 1.5 s // Package ml is the FastAPI client. Prediction calls use the caller's deadline
// timeout; callers fall back to the last good forecast on any error. The larger // (1.5 s by default); callers fall back to the last good forecast on any error.
// /bootstrap snapshot gets its own, longer transport timeout. // The larger /bootstrap snapshot gets its own, longer transport timeout.
package ml package ml
import ( import (
@@ -91,7 +91,7 @@ func (c *Client) Bootstrap(ctx context.Context) (model.Bootstrap, error) {
return out, nil return out, nil
} }
// PredictRequest mirrors CONTRACT.md §3 POST /predict. // PredictRequest mirrors the API contract POST /predict.
type PredictRequest struct { type PredictRequest struct {
Sensor string `json:"sensor"` Sensor string `json:"sensor"`
Horizon string `json:"horizon"` Horizon string `json:"horizon"`
@@ -106,7 +106,7 @@ type WeatherInput struct {
PrecipMM float64 `json:"precip_mm"` PrecipMM float64 `json:"precip_mm"`
} }
// SimulateRequest mirrors CONTRACT.md §3 POST /simulate. // SimulateRequest mirrors the API contract POST /simulate.
type SimulateRequest struct { type SimulateRequest struct {
Scenario string `json:"scenario"` Scenario string `json:"scenario"`
Weather model.WeatherInput `json:"weather"` Weather model.WeatherInput `json:"weather"`
@@ -119,7 +119,7 @@ type TrainRequest struct {
Model string `json:"model"` Model string `json:"model"`
} }
// TrainModels are the accepted training targets from CONTRACT.md §3. // TrainModels are the accepted training targets.
var TrainModels = []string{"small", "forecast"} var TrainModels = []string{"small", "forecast"}
// Predict calls POST /predict and returns the forecast points. The contract // Predict calls POST /predict and returns the forecast points. The contract
+3 -2
View File
@@ -1,10 +1,11 @@
// Package model contains the wire types shared by the HTTP handlers, the // Package model contains the wire types shared by the HTTP handlers, the
// baked-data store and the FastAPI client. JSON tags mirror CONTRACT.md. // in-memory snapshot cache and the FastAPI client. JSON tags mirror the API
// contract.
package model package model
import "time" import "time"
// Horizons and enums from CONTRACT.md §1. // Horizons and enums from the API contract.
var ( var (
Horizons = []string{"15m", "1h", "48h", "7d"} Horizons = []string{"15m", "1h", "48h", "7d"}
Scenarios = []string{"base", "sunny-saturday-market", "rainy-saturday", "weekday-event"} Scenarios = []string{"base", "sunny-saturday-market", "rainy-saturday", "weekday-event"}
+4 -4
View File
@@ -1,6 +1,5 @@
// Package staffing implements the deterministic decision heuristic from // Package staffing turns forecast points into an explainable shift plan using
// CONTRACT.md §5. It never calls the model: it consumes forecast points and // the deterministic heuristic in the API contract. It never calls the model.
// turns them into an explainable shift plan.
package staffing package staffing
import ( import (
@@ -12,7 +11,8 @@ import (
"pulsecast/api/internal/model" "pulsecast/api/internal/model"
) )
// Build creates a plan for one sensor/scenario/standard. // Build creates a plan for one sensor/scenario/standard from the forecast's
// complete store days.
func Build(sensor, scenario, standard string, points []model.ForecastPoint, ctx model.ContextData) (model.StaffingResponse, error) { func Build(sensor, scenario, standard string, points []model.ForecastPoint, ctx model.ContextData) (model.StaffingResponse, error) {
perStaff, ok := visitorsPerStaff(standard) perStaff, ok := visitorsPerStaff(standard)
if !ok { if !ok {
+1 -1
View File
@@ -545,7 +545,7 @@ func buildSummary(rec *recorder, changes []changeResult, base string, clientsN,
sum.LatencyP50MS, sum.LatencyP95MS, sum.LatencyP99MS, sum.LatencyMaxMS = percentiles(all) sum.LatencyP50MS, sum.LatencyP95MS, sum.LatencyP99MS, sum.LatencyMaxMS = percentiles(all)
sum.Ping = buildPingSummary(pingTimes, rec.clients) sum.Ping = buildPingSummary(pingTimes, rec.clients)
// Pass criteria from CONTRACT.md §6: 120 clients for 5 minutes, no dropped // Pass criteria from the API contract: 120 clients for 5 minutes, no dropped
// connections, p95 scenario latency below 2 s. // connections, p95 scenario latency below 2 s.
if peak < clientsN { if peak < clientsN {
sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("peak connections %d < %d", peak, clientsN)) sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("peak connections %d < %d", peak, clientsN))