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:
check:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Check out
uses: actions/checkout@v4
@@ -18,6 +19,9 @@ jobs:
uses: actions/setup-go@v5
with:
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
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
@@ -10,7 +43,8 @@ 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`).
(`.gitea/workflows/ci.yml`). CI does not run the integration or load tests;
those need the ML checkout and raw CSV.
## Runtime data
@@ -32,10 +66,12 @@ the last good snapshot and retries with exponential backoff
| 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*` |
@@ -45,7 +81,7 @@ the last good snapshot and retries with exponential backoff
`:18080` is busy):
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);
3. verifies the live forecast still answers, scenario propagation, the 15 s
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/results/`.
## Container
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 |
|---|---|
| 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 |
| Coverage | 100%, cost €3,360 |
| `cached` on the live plan | `false` |
+1
View File
@@ -157,6 +157,7 @@ func (s *Server) handleContext(w http.ResponseWriter, _ *http.Request) {
cached := true
if s.cache != nil {
ctx = s.cache.Context()
// A failed refresh keeps the old context in place, so mark it cached.
cached = !s.cache.Fresh()
}
s.setVersions(w)
+1
View File
@@ -87,6 +87,7 @@ func (s *Server) liveForecast(ctx context.Context, sensor, horizon, scenarioName
ctxData := s.cache.Context()
precip := ctxData.Weather.Now.PrecipMM
// A zero override means "no scenario rain"; keep the cached current value.
if state.Scenario.Weather.PrecipMM > 0 {
precip = state.Scenario.Weather.PrecipMM
}
+2 -2
View File
@@ -13,8 +13,8 @@ import (
"pulsecast/api/internal/model"
)
// maxTrainBody bounds an uploaded CSV. The raw dataset is ~18 MB; 64 MB leaves
// room for a larger export without letting the API accept unbounded bodies.
// maxTrainBody bounds an uploaded CSV so a client cannot stream an unbounded
// body through the proxy.
const maxTrainBody = 64 << 20
// 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
// fallback into the Go service described by CONTRACT.md.
// fallback into the Go service.
package api
import (
@@ -108,6 +108,8 @@ var methodTable = map[string][]string{
"/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 {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
methods, ok := methodTable[r.URL.Path]
-4
View File
@@ -286,7 +286,6 @@ func (c *Cache) Sensors() []model.Sensor {
return out
}
// Sensor looks up one sensor.
func (c *Cache) Sensor(id string) (model.Sensor, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
@@ -308,7 +307,6 @@ func (c *Cache) Series(id string) ([]model.Point, bool) {
return points, ok
}
// Context returns the current weather/holiday context.
func (c *Cache) Context() model.ContextData {
c.mu.RLock()
defer c.mu.RUnlock()
@@ -318,7 +316,6 @@ func (c *Cache) Context() model.ContextData {
return c.snapshot.Context
}
// Versions returns data, model and context version strings.
func (c *Cache) Versions() (data, modelVersion, contextVersion string) {
c.mu.RLock()
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
}
// Len returns the number of sensors in the current snapshot.
func (c *Cache) Len() int {
c.mu.RLock()
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
// timeout; callers fall back to the last good forecast on any error. The larger
// /bootstrap snapshot gets its own, longer transport timeout.
// Package ml is the FastAPI client. Prediction calls use the caller's deadline
// (1.5 s by default); callers fall back to the last good forecast on any error.
// The larger /bootstrap snapshot gets its own, longer transport timeout.
package ml
import (
@@ -91,7 +91,7 @@ func (c *Client) Bootstrap(ctx context.Context) (model.Bootstrap, error) {
return out, nil
}
// PredictRequest mirrors CONTRACT.md §3 POST /predict.
// PredictRequest mirrors the API contract POST /predict.
type PredictRequest struct {
Sensor string `json:"sensor"`
Horizon string `json:"horizon"`
@@ -106,7 +106,7 @@ type WeatherInput struct {
PrecipMM float64 `json:"precip_mm"`
}
// SimulateRequest mirrors CONTRACT.md §3 POST /simulate.
// SimulateRequest mirrors the API contract POST /simulate.
type SimulateRequest struct {
Scenario string `json:"scenario"`
Weather model.WeatherInput `json:"weather"`
@@ -119,7 +119,7 @@ type TrainRequest struct {
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"}
// 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
// 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
import "time"
// Horizons and enums from CONTRACT.md §1.
// Horizons and enums from the API contract.
var (
Horizons = []string{"15m", "1h", "48h", "7d"}
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
// CONTRACT.md §5. It never calls the model: it consumes forecast points and
// turns them into an explainable shift plan.
// Package staffing turns forecast points into an explainable shift plan using
// the deterministic heuristic in the API contract. It never calls the model.
package staffing
import (
@@ -12,7 +11,8 @@ import (
"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) {
perStaff, ok := visitorsPerStaff(standard)
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.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.
if peak < clientsN {
sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("peak connections %d < %d", peak, clientsN))