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.
This commit is contained in:
1 parent
80c8eeb0b9
commit
f4693af748
12 files changed
+66
-26
No files matched your search
@@ -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
|
||||||
@@ -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
@@ -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` |
|
||||||
|
|||||||
@@ -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)
|
||||||
|
|||||||
@@ -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
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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,
|
||||||
|
|||||||
@@ -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]
|
||||||
|
|||||||
Vendored
-4
@@ -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()
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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"}
|
||||||
|
|||||||
@@ -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 {
|
||||||
|
|||||||
@@ -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))
|
||||||
|
|||||||
Reference in new issue
Block a user