diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 12e99cf..18da05c 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -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 diff --git a/README.md b/README.md index 81396bc..b2b8c09 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/integration.md b/docs/integration.md index 12796ac..9068d4b 100644 --- a/docs/integration.md +++ b/docs/integration.md @@ -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` | diff --git a/internal/api/handlers_data.go b/internal/api/handlers_data.go index 854d1ff..81d8dfd 100644 --- a/internal/api/handlers_data.go +++ b/internal/api/handlers_data.go @@ -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) diff --git a/internal/api/handlers_forecast.go b/internal/api/handlers_forecast.go index ea2611e..db90fdb 100644 --- a/internal/api/handlers_forecast.go +++ b/internal/api/handlers_forecast.go @@ -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 } diff --git a/internal/api/handlers_train.go b/internal/api/handlers_train.go index 6e9e003..f362093 100644 --- a/internal/api/handlers_train.go +++ b/internal/api/handlers_train.go @@ -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, diff --git a/internal/api/server.go b/internal/api/server.go index a6616c8..d8f2065 100644 --- a/internal/api/server.go +++ b/internal/api/server.go @@ -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] diff --git a/internal/cache/cache.go b/internal/cache/cache.go index a5da3e8..1f4c6e0 100644 --- a/internal/cache/cache.go +++ b/internal/cache/cache.go @@ -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() diff --git a/internal/ml/client.go b/internal/ml/client.go index 9c6688e..ff1ab07 100644 --- a/internal/ml/client.go +++ b/internal/ml/client.go @@ -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 diff --git a/internal/model/types.go b/internal/model/types.go index 1c0d135..6706e02 100644 --- a/internal/model/types.go +++ b/internal/model/types.go @@ -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"} diff --git a/internal/staffing/staffing.go b/internal/staffing/staffing.go index efc424f..8a347da 100644 --- a/internal/staffing/staffing.go +++ b/internal/staffing/staffing.go @@ -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 { diff --git a/scripts/sse-load/main.go b/scripts/sse-load/main.go index 74dbdf6..07a72bb 100755 --- a/scripts/sse-load/main.go +++ b/scripts/sse-load/main.go @@ -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))