feat: ci docs #3

Merged
Noel merged 9 commits from feat/ci-docs into main 2026-11-14 08:34:35 +00:00
19 changed files with 1400 additions and 384 deletions
Showing only changes of commit aa6bb23e24 - Show all commits

No files matched your search

+2
View File
@@ -2,3 +2,5 @@
.gitignore
*.md
opencode.json
# Fixtures are for tests only; the runtime image fetches FastAPI /bootstrap.
testdata
+3 -4
View File
@@ -17,11 +17,10 @@ FROM gcr.io/distroless/static-debian12:nonroot
WORKDIR /app
COPY --from=build /out/api /app/api
# Baked fallback data lives in the image; there is no runtime data fetch.
COPY --from=build /src/testdata/data /app/data
ENV DATA_DIR=/app/data \
PORT=8080
# No data is baked into the image. The API fetches FastAPI /bootstrap at
# startup, caches the snapshot in memory, and refreshes it in the background.
ENV PORT=8080
EXPOSE 8080
# Numeric UID/GID: the kubelet cannot verify named users for runAsNonRoot.
+25
View File
@@ -12,6 +12,31 @@ 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`).
## 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 |
|---|---|---|
| `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 |
## Container
The image is a multi-stage build. The runtime is
+14 -11
View File
@@ -1,4 +1,4 @@
// Command api serves the PulseCast Go API, SSE stream and cached fallback.
// Command api serves the PulseCast Go API, SSE stream and runtime snapshot cache.
package main
import (
@@ -12,38 +12,41 @@ import (
"time"
"pulsecast/api/internal/api"
"pulsecast/api/internal/cache"
"pulsecast/api/internal/config"
"pulsecast/api/internal/ml"
"pulsecast/api/internal/sse"
"pulsecast/api/internal/store"
)
func main() {
cfg := config.Load()
// A partial dataset is not fatal: the process starts and /api/readyz reports
// 503 until the baked artifacts are complete, instead of crash-looping.
st, err := store.Load(cfg.DataDir)
if err != nil {
slog.Error("baked data is incomplete", "dir", cfg.DataDir, "error", err)
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
client := ml.NewWithToken(cfg.FastAPIURL, cfg.MLTimeout, cfg.ControlToken)
snapshots := cache.New(client, cache.Options{
RefreshInterval: cfg.RefreshInterval,
Timeout: cfg.BootstrapTimeout,
})
// Loading happens in the background so the process can answer /api/readyz
// with 503 immediately instead of crash-looping while FastAPI starts.
go snapshots.Run(ctx)
hub := sse.NewHub(cfg.Heartbeat)
go hub.Run(ctx)
server := &http.Server{
Addr: cfg.Addr,
Handler: api.New(cfg, st, ml.NewWithToken(cfg.FastAPIURL, cfg.MLTimeout, cfg.ControlToken), hub).Handler(),
Handler: api.New(cfg, snapshots, client, hub).Handler(),
ReadHeaderTimeout: 5 * time.Second,
IdleTimeout: 120 * time.Second,
}
serveErr := make(chan error, 1)
go func() {
slog.Info("api listening", "addr", cfg.Addr, "data_dir", cfg.DataDir, "fastapi", cfg.FastAPIURL)
slog.Info("api listening", "addr", cfg.Addr, "fastapi", cfg.FastAPIURL,
"refresh", cfg.RefreshInterval)
serveErr <- server.ListenAndServe()
}()
+357 -32
View File
@@ -10,18 +10,77 @@ import (
"io"
"net/http"
"net/http/httptest"
"os"
"strings"
"sync"
"testing"
"time"
"pulsecast/api/internal/cache"
"pulsecast/api/internal/config"
"pulsecast/api/internal/ml"
"pulsecast/api/internal/model"
"pulsecast/api/internal/sse"
"pulsecast/api/internal/store"
)
const fixtureDir = "../../testdata/data"
const fixtureBootstrap = "../../testdata/data/bootstrap.json"
type stubFetcher struct {
mu sync.RWMutex
payload model.Bootstrap
err error
refreshFn func(context.Context) (model.Bootstrap, error)
}
func (s *stubFetcher) Bootstrap(ctx context.Context) (model.Bootstrap, error) {
s.mu.RLock()
fn := s.refreshFn
payload, err := s.payload, s.err
s.mu.RUnlock()
if fn != nil {
return fn(ctx)
}
if err != nil {
return model.Bootstrap{}, err
}
return payload, nil
}
func (s *stubFetcher) fail(err error) {
s.mu.Lock()
s.err = err
s.mu.Unlock()
}
func (s *stubFetcher) recover(payload model.Bootstrap) {
s.mu.Lock()
s.payload, s.err = payload, nil
s.mu.Unlock()
}
func loadFixtureBootstrap(t *testing.T) model.Bootstrap {
t.Helper()
raw, err := os.ReadFile(fixtureBootstrap)
if err != nil {
t.Fatalf("read fixture: %v", err)
}
var payload model.Bootstrap
if err := json.Unmarshal(raw, &payload); err != nil {
t.Fatalf("decode fixture: %v", err)
}
return payload
}
func newFixtureCache(t *testing.T) (*cache.Cache, *stubFetcher) {
t.Helper()
payload := loadFixtureBootstrap(t)
fetcher := &stubFetcher{payload: payload}
snapshots := cache.New(fetcher, cache.Options{RefreshInterval: time.Hour, Timeout: time.Second})
if err := snapshots.Refresh(context.Background()); err != nil {
t.Fatalf("prime cache: %v", err)
}
return snapshots, fetcher
}
type stubML struct {
predict func(context.Context, ml.PredictRequest) ([]model.ForecastPoint, error)
@@ -58,20 +117,16 @@ func (s *stubML) TrainStatus(ctx context.Context, jobID string) (int, []byte, er
return s.trainStatus(ctx, jobID)
}
func loadFixtureStore(t *testing.T) *store.Store {
func newTestServer(t *testing.T, client MLClient, mutate func(*config.Config)) (*Server, *httptest.Server) {
t.Helper()
st, err := store.Load(fixtureDir)
if err != nil {
t.Fatalf("load fixtures: %v", err)
}
return st
snapshots, _ := newFixtureCache(t)
return newTestServerWithCache(t, snapshots, client, mutate)
}
func newTestServer(t *testing.T, client MLClient, mutate func(*config.Config)) (*Server, *httptest.Server) {
func newTestServerWithCache(t *testing.T, snapshots *cache.Cache, client MLClient, mutate func(*config.Config)) (*Server, *httptest.Server) {
t.Helper()
cfg := config.Config{
Addr: ":0",
DataDir: fixtureDir,
FastAPIURL: "http://127.0.0.1:1",
Heartbeat: time.Hour,
MLTimeout: 100 * time.Millisecond,
@@ -85,12 +140,47 @@ func newTestServer(t *testing.T, client MLClient, mutate func(*config.Config)) (
t.Cleanup(cancel)
go hub.Run(ctx)
srv := New(cfg, loadFixtureStore(t), client, hub)
srv := New(cfg, snapshots, client, hub)
ts := httptest.NewServer(srv.Handler())
t.Cleanup(ts.Close)
return srv, ts
}
func forecastPoints(n int) []model.ForecastPoint {
start := time.Date(2026, 11, 16, 9, 0, 0, 0, time.UTC)
points := make([]model.ForecastPoint, n)
for i := range points {
points[i] = model.ForecastPoint{
T: start.Add(time.Duration(i) * time.Hour),
V: float64(10 + i),
Lo: float64(5 + i),
Hi: float64(15 + i),
}
}
return points
}
// weekForecast builds seven complete store-hour days (10:00-20:00 Berlin),
// which is what the staffing planner consumes.
func weekForecast(t *testing.T) []model.ForecastPoint {
t.Helper()
loc, err := time.LoadLocation(model.StoreHours.TZ)
if err != nil {
t.Fatal(err)
}
start := time.Date(2026, 11, 16, model.StoreHours.Open, 0, 0, 0, loc)
var points []model.ForecastPoint
for day := 0; day < 7; day++ {
for hour := 0; hour < model.StoreHours.Close-model.StoreHours.Open; hour++ {
points = append(points, model.ForecastPoint{
T: start.AddDate(0, 0, day).Add(time.Duration(hour) * time.Hour).UTC(),
V: 25,
})
}
}
return points
}
func getJSON(t *testing.T, url string, dst any) *http.Response {
t.Helper()
resp, err := http.Get(url)
@@ -125,13 +215,11 @@ func TestHealthAndReady(t *testing.T) {
}
}
func TestReadyzWithoutData(t *testing.T) {
cfg := config.Config{Addr: ":0", DataDir: t.TempDir(), FastAPIURL: "http://127.0.0.1:1", Heartbeat: time.Hour, MLTimeout: 50 * time.Millisecond}
st, err := store.Load(cfg.DataDir)
if err != nil {
t.Logf("expected load error: %v", err)
}
srv := New(cfg, st, &stubML{}, sse.NewHub(time.Hour))
func TestReadyzWithoutSnapshot(t *testing.T) {
cfg := config.Config{Addr: ":0", FastAPIURL: "http://127.0.0.1:1", Heartbeat: time.Hour, MLTimeout: 50 * time.Millisecond}
fetcher := &stubFetcher{err: errors.New("fastapi unavailable")}
snapshots := cache.New(fetcher, cache.Options{RefreshInterval: time.Hour, Timeout: time.Second})
srv := New(cfg, snapshots, &stubML{}, sse.NewHub(time.Hour))
ts := httptest.NewServer(srv.Handler())
defer ts.Close()
@@ -143,6 +231,70 @@ func TestReadyzWithoutData(t *testing.T) {
if ready["ok"] || ready["data"] || ready["model"] {
t.Fatalf("readyz body=%v, want all false", ready)
}
// One failed bootstrap attempt must not make the cache ready.
if err := snapshots.Refresh(context.Background()); err == nil {
t.Fatal("expected the bootstrap refresh to fail")
}
resp = getJSON(t, ts.URL+"/api/readyz", &ready)
if resp.StatusCode != http.StatusServiceUnavailable || ready["ok"] {
t.Fatalf("readyz after failed refresh: status=%d body=%v", resp.StatusCode, ready)
}
}
func TestReadyzSurvivesFastAPIFailureAfterFirstSnapshot(t *testing.T) {
snapshots, fetcher := newFixtureCache(t)
cfg := config.Config{Addr: ":0", FastAPIURL: "http://127.0.0.1:1", Heartbeat: time.Hour, MLTimeout: 50 * time.Millisecond}
srv := New(cfg, snapshots, &stubML{}, sse.NewHub(time.Hour))
ts := httptest.NewServer(srv.Handler())
defer ts.Close()
var ready map[string]bool
resp := getJSON(t, ts.URL+"/api/readyz", &ready)
if resp.StatusCode != http.StatusOK || !ready["ok"] || !ready["data"] || !ready["model"] {
t.Fatalf("readyz status=%d body=%v", resp.StatusCode, ready)
}
fetcher.fail(errors.New("connection refused"))
if err := snapshots.Refresh(context.Background()); err == nil {
t.Fatal("expected the refresh to fail")
}
resp = getJSON(t, ts.URL+"/api/readyz", &ready)
if resp.StatusCode != http.StatusOK || !ready["ok"] || !ready["data"] || !ready["model"] {
t.Fatalf("readyz after FastAPI failure: status=%d body=%v, want 200 with the last snapshot", resp.StatusCode, ready)
}
var meta model.Meta
getJSON(t, ts.URL+"/api/meta", &meta)
if meta.Cache.Failures != 1 || meta.Cache.LastError == nil ||
!strings.Contains(*meta.Cache.LastError, "connection refused") {
t.Fatalf("cache status=%+v", meta.Cache)
}
if meta.Cache.LastSuccessAt == nil || meta.Cache.NextRetryAt == nil {
t.Fatalf("cache timestamps missing: %+v", meta.Cache)
}
// The context endpoint comes from the snapshot; it is now stale.
var ctx model.ContextResponse
getJSON(t, ts.URL+"/api/context", &ctx)
if !ctx.Cached {
t.Error("context cached=false after a failed refresh, want true")
}
// A later success clears the failure state.
fetcher.recover(loadFixtureBootstrap(t))
if err := snapshots.Refresh(context.Background()); err != nil {
t.Fatalf("recovery refresh: %v", err)
}
getJSON(t, ts.URL+"/api/meta", &meta)
if meta.Cache.Failures != 0 || meta.Cache.LastError != nil || meta.Cache.NextRetryAt != nil {
t.Fatalf("cache status after recovery=%+v", meta.Cache)
}
getJSON(t, ts.URL+"/api/context", &ctx)
if ctx.Cached {
t.Error("context cached=true after a successful refresh, want false")
}
}
func TestMetaSensorsAndVersionHeaders(t *testing.T) {
@@ -156,6 +308,10 @@ func TestMetaSensorsAndVersionHeaders(t *testing.T) {
if meta.Coverage.Sensors != 8 || meta.ModelVersion == "" || meta.ContextVersion == "" {
t.Fatalf("meta=%+v", meta)
}
if meta.Cache.Source != "fastapi" || meta.Cache.LastSuccessAt == nil ||
meta.Cache.LastError != nil || meta.Cache.NextRetryAt != nil || meta.Cache.Failures != 0 {
t.Fatalf("meta cache=%+v", meta.Cache)
}
for _, header := range []string{"X-Data-Version", "X-Model-Version", "X-Context-Version"} {
if resp.Header.Get(header) == "" {
t.Errorf("missing %s header", header)
@@ -180,6 +336,58 @@ func TestMetaSensorsAndVersionHeaders(t *testing.T) {
}
}
func TestDataEndpointsFollowSnapshotRefresh(t *testing.T) {
snapshots, fetcher := newFixtureCache(t)
_, ts := newTestServerWithCache(t, snapshots, &stubML{}, nil)
var sensors []model.Sensor
getJSON(t, ts.URL+"/api/sensors", &sensors)
if len(sensors) != 8 {
t.Fatalf("sensors=%d, want 8", len(sensors))
}
updated := loadFixtureBootstrap(t)
updated.DataVersion = "2026-11-14T05:00:00Z"
updated.ContextVersion = "2026-11-14T05:00:00Z"
updated.Sensors = updated.Sensors[:1]
updated.Series = map[string][]model.Point{
updated.Sensors[0].ID: {{T: time.Date(2026, 11, 1, 10, 0, 0, 0, time.UTC), V: 42}},
}
fetcher.recover(updated)
if err := snapshots.Refresh(context.Background()); err != nil {
t.Fatalf("refresh: %v", err)
}
sensors = nil
resp := getJSON(t, ts.URL+"/api/sensors", &sensors)
if len(sensors) != 1 || sensors[0].ID != updated.Sensors[0].ID {
t.Fatalf("sensors after refresh=%+v", sensors)
}
if got := resp.Header.Get("X-Data-Version"); got != updated.DataVersion {
t.Errorf("X-Data-Version=%q, want %q", got, updated.DataVersion)
}
var series struct {
Points []model.Point `json:"points"`
}
getJSON(t, ts.URL+"/api/series?sensor="+updated.Sensors[0].ID+"&step=15m", &series)
if len(series.Points) != 1 || series.Points[0].V != 42 {
t.Fatalf("series after refresh=%+v", series.Points)
}
var ctx model.ContextResponse
getJSON(t, ts.URL+"/api/context", &ctx)
if ctx.UpdatedAt.IsZero() || ctx.Cached {
t.Fatalf("context after refresh=%+v", ctx)
}
var meta model.Meta
getJSON(t, ts.URL+"/api/meta", &meta)
if meta.DataVersion != updated.DataVersion || meta.Cache.Failures != 0 {
t.Fatalf("meta after refresh=%+v", meta)
}
}
func TestSeriesRangeStepAndErrors(t *testing.T) {
_, ts := newTestServer(t, &stubML{}, nil)
@@ -241,37 +449,96 @@ func TestContextEndpoint(t *testing.T) {
if ctx.UpdatedAt.IsZero() {
t.Error("expected updated_at")
}
if ctx.Cached {
t.Error("cached=true while the last snapshot refresh succeeded, want false")
}
}
func TestForecastFallsBackWhenMLIsDown(t *testing.T) {
_, ts := newTestServer(t, &stubML{}, nil)
func TestForecastServesLastGoodWhenMLIsDown(t *testing.T) {
live := forecastPoints(168)
var down bool
var mu sync.Mutex
client := &stubML{predict: func(context.Context, ml.PredictRequest) ([]model.ForecastPoint, error) {
mu.Lock()
defer mu.Unlock()
if down {
return nil, errors.New("connection refused")
}
return live, nil
}}
_, ts := newTestServer(t, client, nil)
var forecast model.ForecastResponse
resp := getJSON(t, ts.URL+"/api/forecast?sensor=hn-bahnhof-01&horizon=7d", &forecast)
if resp.StatusCode != http.StatusOK {
t.Fatalf("forecast status=%d", resp.StatusCode)
t.Fatalf("live forecast status=%d", resp.StatusCode)
}
if !forecast.Cached {
if forecast.Cached || len(forecast.Points) != 168 {
t.Fatalf("live forecast cached=%v points=%d, want false/168", forecast.Cached, len(forecast.Points))
}
mu.Lock()
down = true
mu.Unlock()
var fallback model.ForecastResponse
resp = getJSON(t, ts.URL+"/api/forecast?sensor=hn-bahnhof-01&horizon=7d", &fallback)
if resp.StatusCode != http.StatusOK {
t.Fatalf("fallback status=%d", resp.StatusCode)
}
if !fallback.Cached {
t.Error("cached=false, want true when FastAPI is down")
}
if len(forecast.Points) != 168 {
t.Fatalf("points=%d, want 168", len(forecast.Points))
if len(fallback.Points) != 168 || fallback.Points[0].T != forecast.Points[0].T ||
fallback.Points[0].V != forecast.Points[0].V {
t.Fatalf("fallback points do not match the last good forecast: %+v", fallback.Points[0])
}
if forecast.Scenario != "base" || forecast.DataVersion == "" || forecast.ModelVersion == "" {
t.Fatalf("forecast=%+v", forecast)
if fallback.Scenario != "base" || fallback.DataVersion == "" || fallback.ModelVersion == "" {
t.Fatalf("forecast=%+v", fallback)
}
}
func TestForecastTimeoutFallsBack(t *testing.T) {
func TestForecastWithoutLastGoodFails503(t *testing.T) {
_, ts := newTestServer(t, &stubML{}, nil)
var errBody model.ErrorBody
resp := getJSON(t, ts.URL+"/api/forecast?sensor=hn-bahnhof-01&horizon=7d", &errBody)
if resp.StatusCode != http.StatusServiceUnavailable {
t.Fatalf("status=%d, want 503", resp.StatusCode)
}
if errBody.Error.Code != "forecast_unavailable" {
t.Fatalf("error=%+v", errBody)
}
}
func TestForecastTimeoutServesLastGood(t *testing.T) {
live := forecastPoints(48)
var mu sync.Mutex
slow := false
client := &stubML{predict: func(ctx context.Context, _ ml.PredictRequest) ([]model.ForecastPoint, error) {
<-ctx.Done()
return nil, ctx.Err()
mu.Lock()
block := slow
mu.Unlock()
if block {
<-ctx.Done()
return nil, ctx.Err()
}
return live, nil
}}
_, ts := newTestServer(t, client, func(cfg *config.Config) { cfg.MLTimeout = 20 * time.Millisecond })
var primed model.ForecastResponse
resp := getJSON(t, ts.URL+"/api/forecast?sensor=hn-stadtgalerie-01&horizon=48h&scenario=sunny-saturday-market", &primed)
if resp.StatusCode != http.StatusOK || primed.Cached {
t.Fatalf("prime forecast status=%d cached=%v", resp.StatusCode, primed.Cached)
}
mu.Lock()
slow = true
mu.Unlock()
start := time.Now()
var forecast model.ForecastResponse
resp := getJSON(t, ts.URL+"/api/forecast?sensor=hn-stadtgalerie-01&horizon=48h&scenario=sunny-saturday-market", &forecast)
resp = getJSON(t, ts.URL+"/api/forecast?sensor=hn-stadtgalerie-01&horizon=48h&scenario=sunny-saturday-market", &forecast)
if resp.StatusCode != http.StatusOK {
t.Fatalf("forecast status=%d", resp.StatusCode)
}
@@ -327,7 +594,11 @@ func TestForecastValidation(t *testing.T) {
}
func TestStaffingPlan(t *testing.T) {
_, ts := newTestServer(t, &stubML{}, nil)
points := weekForecast(t)
client := &stubML{predict: func(context.Context, ml.PredictRequest) ([]model.ForecastPoint, error) {
return points, nil
}}
_, ts := newTestServer(t, client, nil)
start := time.Now()
var plan model.StaffingResponse
@@ -350,9 +621,12 @@ func TestStaffingPlan(t *testing.T) {
if plan.Summary.CoveragePct != 100 {
t.Errorf("coverage=%v, want 100", plan.Summary.CoveragePct)
}
if plan.Summary.CostEUR <= 0 || plan.Summary.FlatScheduleCostEUR <= 0 {
if plan.Summary.CostEUR != 2240 || plan.Summary.FlatScheduleCostEUR != 2240 {
t.Errorf("summary=%+v", plan.Summary)
}
if plan.Cached {
t.Error("cached=true, want false for a live plan")
}
if len(plan.Why) == 0 {
t.Error("expected a non-empty why list")
}
@@ -363,6 +637,57 @@ func TestStaffingPlan(t *testing.T) {
}
}
func TestStaffingFallsBackToLastGoodForecast(t *testing.T) {
points := weekForecast(t)
var mu sync.Mutex
down := false
client := &stubML{predict: func(context.Context, ml.PredictRequest) ([]model.ForecastPoint, error) {
mu.Lock()
defer mu.Unlock()
if down {
return nil, errors.New("connection refused")
}
return points, nil
}}
_, ts := newTestServer(t, client, nil)
var live model.StaffingResponse
resp := getJSON(t, ts.URL+"/api/staffing?sensor=hn-bahnhof-01&scenario=base&standard=standard", &live)
if resp.StatusCode != http.StatusOK || live.Cached {
t.Fatalf("live staffing status=%d cached=%v", resp.StatusCode, live.Cached)
}
mu.Lock()
down = true
mu.Unlock()
// Different standard -> different plan key, so the handler must rebuild
// from the last good 7d forecast.
var fallback model.StaffingResponse
resp = getJSON(t, ts.URL+"/api/staffing?sensor=hn-bahnhof-01&scenario=base&standard=premium", &fallback)
if resp.StatusCode != http.StatusOK {
t.Fatalf("fallback staffing status=%d", resp.StatusCode)
}
if !fallback.Cached {
t.Error("cached=false, want true when built from the last good forecast")
}
if len(fallback.Hours) != 70 || len(fallback.Shifts) != 21 {
t.Fatalf("fallback plan hours=%d shifts=%d", len(fallback.Hours), len(fallback.Shifts))
}
}
func TestStaffingUnavailableWithoutForecast(t *testing.T) {
_, ts := newTestServer(t, &stubML{}, nil)
var errBody model.ErrorBody
resp := getJSON(t, ts.URL+"/api/staffing?sensor=hn-bahnhof-01&scenario=base&standard=standard", &errBody)
if resp.StatusCode != http.StatusServiceUnavailable {
t.Fatalf("status=%d, want 503", resp.StatusCode)
}
if errBody.Error.Code != "staffing_unavailable" {
t.Fatalf("error=%+v", errBody)
}
}
func TestStaffingValidation(t *testing.T) {
_, ts := newTestServer(t, &stubML{}, nil)
for _, tc := range []struct {
+25 -10
View File
@@ -14,9 +14,11 @@ func (s *Server) handleHealthz(w http.ResponseWriter, _ *http.Request) {
}
func (s *Server) handleReadyz(w http.ResponseWriter, _ *http.Request) {
ready := s.store != nil && s.store.Ready()
dataOK := s.store != nil && s.store.Len() > 0 && !s.store.Context().UpdatedAt.IsZero()
modelOK := s.store != nil && s.store.Meta().ModelVersion != ""
dataOK, modelOK := false, false
if s.cache != nil {
dataOK, modelOK = s.cache.Readiness()
}
ready := dataOK && modelOK
status := http.StatusOK
if !ready {
status = http.StatusServiceUnavailable
@@ -26,12 +28,16 @@ func (s *Server) handleReadyz(w http.ResponseWriter, _ *http.Request) {
func (s *Server) handleMeta(w http.ResponseWriter, _ *http.Request) {
s.setVersions(w)
writeJSON(w, http.StatusOK, s.store.Meta())
writeJSON(w, http.StatusOK, s.meta())
}
func (s *Server) handleSensors(w http.ResponseWriter, _ *http.Request) {
s.setVersions(w)
writeJSON(w, http.StatusOK, s.store.Sensors())
if s.cache == nil {
writeJSON(w, http.StatusOK, []model.Sensor{})
return
}
writeJSON(w, http.StatusOK, s.cache.Sensors())
}
func (s *Server) handleSeries(w http.ResponseWriter, r *http.Request) {
@@ -41,7 +47,11 @@ func (s *Server) handleSeries(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, "bad_request", "sensor is required")
return
}
if _, ok := s.store.Sensor(sensor); !ok {
if s.cache == nil {
writeError(w, http.StatusNotFound, "not_found", "unknown sensor")
return
}
if _, ok := s.cache.Sensor(sensor); !ok {
writeError(w, http.StatusNotFound, "not_found", "unknown sensor")
return
}
@@ -54,7 +64,7 @@ func (s *Server) handleSeries(w http.ResponseWriter, r *http.Request) {
return
}
raw, _ := s.store.Series(sensor)
raw, _ := s.cache.Series(sensor)
if len(raw) == 0 {
s.setVersions(w)
writeJSON(w, http.StatusOK, map[string]any{"sensor": sensor, "step": step, "points": []model.Point{}})
@@ -69,7 +79,7 @@ func (s *Server) handleSeries(w http.ResponseWriter, r *http.Request) {
return
}
to = parsed.UTC()
} else if len(raw) > 0 {
} else {
to = raw[len(raw)-1].T.UTC()
}
@@ -143,12 +153,17 @@ func hourlyMean(points []model.Point) []model.Point {
}
func (s *Server) handleContext(w http.ResponseWriter, _ *http.Request) {
ctx := s.store.Context()
var ctx model.ContextData
cached := true
if s.cache != nil {
ctx = s.cache.Context()
cached = !s.cache.Fresh()
}
s.setVersions(w)
writeJSON(w, http.StatusOK, model.ContextResponse{
Weather: ctx.Weather,
Holidays: ctx.Holidays,
UpdatedAt: ctx.UpdatedAt,
Cached: false,
Cached: cached,
})
}
+76 -30
View File
@@ -20,7 +20,11 @@ func (s *Server) handleForecast(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, "bad_request", "sensor is required")
return
}
if _, ok := s.store.Sensor(sensor); !ok {
if s.cache == nil {
writeError(w, http.StatusNotFound, "not_found", "unknown sensor")
return
}
if _, ok := s.cache.Sensor(sensor); !ok {
writeError(w, http.StatusNotFound, "not_found", "unknown sensor")
return
}
@@ -53,11 +57,14 @@ func (s *Server) handleForecast(w http.ResponseWriter, r *http.Request) {
if !ok {
slog.Warn("forecast unavailable", "sensor", sensor, "horizon", horizon, "scenario", scenarioName, "error", err)
writeError(w, http.StatusServiceUnavailable, "forecast_unavailable",
"no live forecast and no baked forecast for this sensor, scenario and horizon")
"no live forecast and no last good forecast for this sensor, scenario and horizon")
return
}
} else {
s.rememberForecast(sensor, horizon, scenarioName, points)
}
meta := s.meta()
s.setVersions(w)
writeJSON(w, http.StatusOK, model.ForecastResponse{
Sensor: sensor,
@@ -65,9 +72,9 @@ func (s *Server) handleForecast(w http.ResponseWriter, r *http.Request) {
Scenario: scenarioName,
Points: points,
Cached: cached,
DataVersion: s.store.Meta().DataVersion,
ModelVersion: s.store.Meta().ModelVersion,
ContextVersion: s.store.Meta().ContextVersion,
DataVersion: meta.DataVersion,
ModelVersion: meta.ModelVersion,
ContextVersion: meta.ContextVersion,
})
}
@@ -78,7 +85,7 @@ func (s *Server) liveForecast(ctx context.Context, sensor, horizon, scenarioName
ctx, cancel := context.WithTimeout(ctx, s.cfg.MLTimeout)
defer cancel()
ctxData := s.store.Context()
ctxData := s.cache.Context()
precip := ctxData.Weather.Now.PrecipMM
if state.Scenario.Weather.PrecipMM > 0 {
precip = state.Scenario.Weather.PrecipMM
@@ -100,8 +107,9 @@ func (s *Server) liveForecast(ctx context.Context, sensor, horizon, scenarioName
return sortedForecast(points), nil
}
// fallbackForecast prefers live /simulate output for the current scenario, then
// the baked scenario grid. It never labels base data as another scenario.
// fallbackForecast prefers the live /simulate grid for the current scenario,
// then the last good /predict response for this exact key. It never labels base
// data as another scenario.
func (s *Server) fallbackForecast(sensor, scenarioName, horizon string) ([]model.ForecastPoint, bool) {
s.mu.RLock()
if s.simFor == scenarioName {
@@ -115,10 +123,31 @@ func (s *Server) fallbackForecast(sensor, scenarioName, horizon string) ([]model
}
s.mu.RUnlock()
if points, ok := s.store.Forecast(sensor, scenarioName, horizon); ok {
return sortedForecast(points), true
return s.lastGoodForecast(sensor, horizon, scenarioName)
}
func forecastKey(sensor, horizon, scenarioName string) string {
return sensor + "|" + horizon + "|" + scenarioName
}
func (s *Server) rememberForecast(sensor, horizon, scenarioName string, points []model.ForecastPoint) {
if len(points) == 0 {
return
}
return nil, false
copied := sortedForecast(points)
s.mu.Lock()
s.lastForecast[forecastKey(sensor, horizon, scenarioName)] = copied
s.mu.Unlock()
}
func (s *Server) lastGoodForecast(sensor, horizon, scenarioName string) ([]model.ForecastPoint, bool) {
s.mu.RLock()
points, ok := s.lastForecast[forecastKey(sensor, horizon, scenarioName)]
s.mu.RUnlock()
if !ok || len(points) == 0 {
return nil, false
}
return sortedForecast(points), true
}
func sortedForecast(points []model.ForecastPoint) []model.ForecastPoint {
@@ -129,8 +158,11 @@ func sortedForecast(points []model.ForecastPoint) []model.ForecastPoint {
}
func (s *Server) holidayOn(t time.Time) (string, bool) {
if s.cache == nil {
return "", false
}
day := t.In(s.loc).Format("2006-01-02")
for _, holiday := range s.store.Context().Holidays {
for _, holiday := range s.cache.Context().Holidays {
if holiday.Date == day {
return holiday.Name, true
}
@@ -145,7 +177,11 @@ func (s *Server) handleStaffing(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, "bad_request", "sensor is required")
return
}
if _, ok := s.store.Sensor(sensor); !ok {
if s.cache == nil {
writeError(w, http.StatusNotFound, "not_found", "unknown sensor")
return
}
if _, ok := s.cache.Sensor(sensor); !ok {
writeError(w, http.StatusNotFound, "not_found", "unknown sensor")
return
}
@@ -169,45 +205,49 @@ func (s *Server) handleStaffing(w http.ResponseWriter, r *http.Request) {
}
state := s.scenario.Get()
points, cached, ok := s.staffingForecast(sensor, scenarioName)
if !ok {
writeError(w, http.StatusServiceUnavailable, "staffing_unavailable",
"no 7d forecast for this sensor and scenario")
return
}
meta := s.meta()
s.mu.RLock()
generation := s.simGen
s.mu.RUnlock()
key := fmt.Sprintf("%s|%s|%s|%d|%d", sensor, scenarioName, standard, state.Version, generation)
key := fmt.Sprintf("%s|%s|%s|%s|%d|%d", sensor, scenarioName, standard,
meta.ContextVersion, state.Version, generation)
s.mu.RLock()
plan, hit := s.staffing[key]
s.mu.RUnlock()
if !hit {
built, err := staffing.Build(sensor, scenarioName, standard, points, s.store.Context())
points, cached, ok := s.staffingForecast(r.Context(), sensor, scenarioName, state)
if !ok {
writeError(w, http.StatusServiceUnavailable, "staffing_unavailable",
"no live or last good 7d forecast for this sensor and scenario")
return
}
built, err := staffing.Build(sensor, scenarioName, standard, points, s.cache.Context())
if err != nil {
slog.Warn("staffing build failed", "sensor", sensor, "scenario", scenarioName, "standard", standard, "error", err)
writeError(w, http.StatusServiceUnavailable, "staffing_unavailable", "could not build a plan from the available forecast")
return
}
built.Cached = cached
s.mu.Lock()
s.staffing[key] = built
s.mu.Unlock()
plan = built
}
plan.Cached = cached
plan.DataVersion = s.store.Meta().DataVersion
plan.ModelVersion = s.store.Meta().ModelVersion
plan.ContextVersion = s.store.Meta().ContextVersion
plan.DataVersion = meta.DataVersion
plan.ModelVersion = meta.ModelVersion
plan.ContextVersion = meta.ContextVersion
s.setVersions(w)
writeJSON(w, http.StatusOK, plan)
}
// staffingForecast returns the best 7d points and whether they came from the
// fallback grid rather than live /simulate output.
func (s *Server) staffingForecast(sensor, scenarioName string) ([]model.ForecastPoint, bool, bool) {
// staffingForecast returns 7d points for a plan. Prefer the scenario simulation
// grid, then /predict, and finally the last good forecast. The bool reports
// whether the points came from the cache fallback.
func (s *Server) staffingForecast(ctx context.Context, sensor, scenarioName string, state model.ScenarioState) ([]model.ForecastPoint, bool, bool) {
s.mu.RLock()
if s.simFor == scenarioName {
if horizons, ok := s.sim[sensor]; ok {
@@ -220,8 +260,14 @@ func (s *Server) staffingForecast(sensor, scenarioName string) ([]model.Forecast
}
s.mu.RUnlock()
if points, ok := s.store.Forecast(sensor, scenarioName, "7d"); ok {
return sortedForecast(points), scenarioName != "base", true
points, err := s.liveForecast(ctx, sensor, "7d", scenarioName, state)
if err == nil {
s.rememberForecast(sensor, "7d", scenarioName, points)
return points, false, true
}
slog.Warn("staffing forecast fallback", "sensor", sensor, "scenario", scenarioName, "error", err)
if points, ok := s.lastGoodForecast(sensor, "7d", scenarioName); ok {
return points, true, true
}
return nil, false, false
}
+8
View File
@@ -83,6 +83,14 @@ func (s *Server) refreshSimulation(state model.ScenarioState) {
s.simFor = state.Scenario.Scenario
s.simGen++
s.staffing = make(map[string]model.StaffingResponse)
for sensorID, horizons := range forecasts {
for horizon, points := range horizons {
if len(points) == 0 {
continue
}
s.lastForecast[forecastKey(sensorID, horizon, state.Scenario.Scenario)] = sortedForecast(points)
}
}
s.mu.Unlock()
}
+31 -20
View File
@@ -12,12 +12,12 @@ import (
"sync"
"time"
"pulsecast/api/internal/cache"
"pulsecast/api/internal/config"
"pulsecast/api/internal/ml"
"pulsecast/api/internal/model"
"pulsecast/api/internal/scenario"
"pulsecast/api/internal/sse"
"pulsecast/api/internal/store"
)
// MLClient is the FastAPI prediction surface the data handlers need.
@@ -37,22 +37,23 @@ type TrainClient interface {
// Server holds process-wide state. One instance per pod.
type Server struct {
cfg config.Config
store *store.Store
cache *cache.Cache
ml MLClient
hub *sse.Hub
scenario *scenario.State
loc *time.Location
now func() time.Time
mu sync.RWMutex
sim map[string]map[string][]model.ForecastPoint // sensor -> horizon -> points
simFor string // scenario the sim belongs to
simGen int // invalidates staffing cache
staffing map[string]model.StaffingResponse
mu sync.RWMutex
sim map[string]map[string][]model.ForecastPoint // sensor -> horizon -> points
simFor string // scenario the sim belongs to
simGen int // invalidates staffing cache
staffing map[string]model.StaffingResponse
lastForecast map[string][]model.ForecastPoint // sensor|horizon|scenario -> last live points
}
// New builds a server. hub must be non-nil; main runs hub.Run.
func New(cfg config.Config, st *store.Store, client MLClient, hub *sse.Hub) *Server {
func New(cfg config.Config, snapshots *cache.Cache, client MLClient, hub *sse.Hub) *Server {
loc, err := time.LoadLocation(model.StoreHours.TZ)
if err != nil {
loc = time.UTC
@@ -61,14 +62,15 @@ func New(cfg config.Config, st *store.Store, client MLClient, hub *sse.Hub) *Ser
cfg.MLTimeout = ml.DefaultTimeout
}
return &Server{
cfg: cfg,
store: st,
ml: client,
hub: hub,
scenario: scenario.New(),
loc: loc,
now: time.Now,
staffing: make(map[string]model.StaffingResponse),
cfg: cfg,
cache: snapshots,
ml: client,
hub: hub,
scenario: scenario.New(),
loc: loc,
now: time.Now,
staffing: make(map[string]model.StaffingResponse),
lastForecast: make(map[string][]model.ForecastPoint),
}
}
@@ -194,10 +196,19 @@ func writeError(w http.ResponseWriter, status int, code, message string) {
_, _ = w.Write(raw)
}
// meta snapshots the cache metadata once per response, so versions and the
// cache block cannot disagree when a refresh lands mid-request.
func (s *Server) meta() model.Meta {
if s.cache == nil {
return model.Meta{}
}
return s.cache.Meta()
}
// setVersions adds the contract's version headers.
func (s *Server) setVersions(w http.ResponseWriter) {
data, modelVersion, context := s.store.Versions()
w.Header().Set("X-Data-Version", data)
w.Header().Set("X-Model-Version", modelVersion)
w.Header().Set("X-Context-Version", context)
meta := s.meta()
w.Header().Set("X-Data-Version", meta.DataVersion)
w.Header().Set("X-Model-Version", meta.ModelVersion)
w.Header().Set("X-Context-Version", meta.ContextVersion)
}
+358
View File
@@ -0,0 +1,358 @@
// Package cache keeps the FastAPI /bootstrap snapshot in memory and refreshes
// it in the background. A failed refresh never discards the last good snapshot;
// the next attempt follows the contract backoff 1/2/4/8/16/30 s (cap).
package cache
import (
"context"
"fmt"
"log/slog"
"sort"
"sync"
"time"
"pulsecast/api/internal/model"
)
// Source is the only snapshot producer: the FastAPI /bootstrap endpoint.
const Source = "fastapi"
// DefaultRefreshInterval is how often a healthy snapshot is refreshed.
const DefaultRefreshInterval = 60 * time.Second
// DefaultTimeout bounds one /bootstrap request.
const DefaultTimeout = 20 * time.Second
// DefaultRetryDelays is the contract backoff schedule. The last value repeats.
var DefaultRetryDelays = []time.Duration{
1 * time.Second,
2 * time.Second,
4 * time.Second,
8 * time.Second,
16 * time.Second,
30 * time.Second,
}
// Fetcher is the FastAPI bootstrap surface. *ml.Client implements it.
type Fetcher interface {
Bootstrap(ctx context.Context) (model.Bootstrap, error)
}
// Options configures refresh behaviour. Zero values use the defaults.
type Options struct {
RefreshInterval time.Duration
Timeout time.Duration
}
// snapshot is one immutable /bootstrap payload with its lookup indexes.
type snapshot struct {
DataVersion string
ModelVersion string
ContextVersion string
Sensors []model.Sensor
Series map[string][]model.Point
Context model.ContextData
Coverage model.Coverage
Metrics model.Metrics
Limits []string
sensorBy map[string]model.Sensor
}
// Cache holds the current snapshot and its refresh status. All methods are
// safe for concurrent use.
type Cache struct {
fetcher Fetcher
refresh time.Duration
timeout time.Duration
retry []time.Duration
now func() time.Time
mu sync.RWMutex
snapshot *snapshot
loaded bool
status model.CacheStatus
}
// New returns an empty cache. Call Run (or Refresh) to load the first snapshot.
func New(fetcher Fetcher, opts Options) *Cache {
if opts.RefreshInterval <= 0 {
opts.RefreshInterval = DefaultRefreshInterval
}
if opts.Timeout <= 0 {
opts.Timeout = DefaultTimeout
}
return &Cache{
fetcher: fetcher,
refresh: opts.RefreshInterval,
timeout: opts.Timeout,
retry: append([]time.Duration(nil), DefaultRetryDelays...),
now: time.Now,
status: model.CacheStatus{Source: Source},
}
}
// Run loads the snapshot immediately, then refreshes it. Failures keep the last
// good snapshot and retry with the contract backoff. Run returns when ctx ends.
func (c *Cache) Run(ctx context.Context) {
recovering := false
for {
wasLoaded := c.Loaded()
err := c.Refresh(ctx)
if ctx.Err() != nil {
return
}
var delay time.Duration
if err != nil {
recovering = true
status := c.Status()
delay = c.retryDelay(status.Failures)
slog.Warn("bootstrap refresh failed; keeping last good snapshot",
"error", err, "failures", status.Failures, "retry_in", delay)
} else {
delay = c.refresh
switch {
case !wasLoaded:
slog.Info("bootstrap snapshot loaded", "sensors", c.Len())
case recovering:
slog.Info("bootstrap refresh recovered", "sensors", c.Len())
}
recovering = false
}
timer := time.NewTimer(delay)
select {
case <-ctx.Done():
timer.Stop()
return
case <-timer.C:
}
}
}
// Refresh performs one fetch. A decode/validation failure counts as a failed
// attempt and leaves the previous snapshot untouched.
func (c *Cache) Refresh(ctx context.Context) error {
ctx, cancel := context.WithTimeout(ctx, c.timeout)
defer cancel()
payload, err := c.fetcher.Bootstrap(ctx)
now := c.now().UTC().Truncate(time.Second)
if err == nil {
var snapshot *snapshot
snapshot, err = newSnapshot(payload)
if err == nil {
c.mu.Lock()
c.snapshot = snapshot
c.loaded = true
c.status.LastSuccessAt = timePtr(now)
c.status.LastError = nil
c.status.NextRetryAt = nil
c.status.Failures = 0
c.mu.Unlock()
return nil
}
}
c.mu.Lock()
c.status.Failures++
message := err.Error()
c.status.LastError = &message
next := now.Add(c.retryDelay(c.status.Failures))
c.status.NextRetryAt = &next
c.mu.Unlock()
return err
}
func (c *Cache) retryDelay(failures int) time.Duration {
if failures < 1 {
failures = 1
}
if failures > len(c.retry) {
failures = len(c.retry)
}
return c.retry[failures-1]
}
func newSnapshot(payload model.Bootstrap) (*snapshot, error) {
switch {
case len(payload.Sensors) == 0:
return nil, fmt.Errorf("bootstrap snapshot: no sensors")
case payload.DataVersion == "":
return nil, fmt.Errorf("bootstrap snapshot: missing data_version")
case payload.ModelVersion == "":
return nil, fmt.Errorf("bootstrap snapshot: missing model_version")
case payload.ContextVersion == "":
return nil, fmt.Errorf("bootstrap snapshot: missing context_version")
case payload.Context.UpdatedAt.IsZero():
return nil, fmt.Errorf("bootstrap snapshot: missing context.updated_at")
}
snapshot := &snapshot{
DataVersion: payload.DataVersion,
ModelVersion: payload.ModelVersion,
ContextVersion: payload.ContextVersion,
Sensors: append([]model.Sensor(nil), payload.Sensors...),
Series: make(map[string][]model.Point, len(payload.Series)),
Context: payload.Context,
Coverage: payload.Meta.Coverage,
Metrics: payload.Meta.Metrics,
Limits: append([]string(nil), payload.Meta.Limits...),
sensorBy: make(map[string]model.Sensor, len(payload.Sensors)),
}
sort.Slice(snapshot.Sensors, func(i, j int) bool { return snapshot.Sensors[i].ID < snapshot.Sensors[j].ID })
for _, sensor := range snapshot.Sensors {
snapshot.sensorBy[sensor.ID] = sensor
}
for sensorID, points := range payload.Series {
copied := append([]model.Point(nil), points...)
sort.Slice(copied, func(i, j int) bool { return copied[i].T.Before(copied[j].T) })
snapshot.Series[sensorID] = copied
}
snapshot.Context.Holidays = append([]model.Holiday(nil), payload.Context.Holidays...)
snapshot.Context.Weather.Forecast = append([]model.WeatherPoint(nil), payload.Context.Weather.Forecast...)
return snapshot, nil
}
// Loaded reports whether a snapshot has ever been accepted.
func (c *Cache) Loaded() bool {
c.mu.RLock()
defer c.mu.RUnlock()
return c.loaded
}
// Ready reports whether a complete snapshot is available. FastAPI health is
// deliberately not part of this check: the cache itself is the safety net.
func (c *Cache) Ready() bool {
data, modelOK := c.Readiness()
return data && modelOK
}
// Readiness splits readiness into the data and model signals of /api/readyz.
func (c *Cache) Readiness() (data, modelOK bool) {
c.mu.RLock()
defer c.mu.RUnlock()
if !c.loaded || c.snapshot == nil {
return false, false
}
data = len(c.snapshot.Sensors) > 0 && !c.snapshot.Context.UpdatedAt.IsZero()
modelOK = c.snapshot.ModelVersion != ""
return data, modelOK
}
// Fresh reports whether the most recent refresh attempt succeeded. It is false
// before the first snapshot and after a failed refresh.
func (c *Cache) Fresh() bool {
c.mu.RLock()
defer c.mu.RUnlock()
return c.loaded && c.status.Failures == 0
}
// Status returns a copy of the cache status.
func (c *Cache) Status() model.CacheStatus {
c.mu.RLock()
defer c.mu.RUnlock()
return cloneStatus(c.status)
}
// Meta combines the snapshot metadata with the live cache status.
func (c *Cache) Meta() model.Meta {
c.mu.RLock()
defer c.mu.RUnlock()
meta := model.Meta{Cache: cloneStatus(c.status)}
if c.snapshot == nil {
return meta
}
meta.DataVersion = c.snapshot.DataVersion
meta.ModelVersion = c.snapshot.ModelVersion
meta.ContextVersion = c.snapshot.ContextVersion
meta.Coverage = c.snapshot.Coverage
meta.Metrics = c.snapshot.Metrics
meta.Limits = append([]string(nil), c.snapshot.Limits...)
return meta
}
// Sensors returns the sensors sorted by id.
func (c *Cache) Sensors() []model.Sensor {
c.mu.RLock()
snapshot := c.snapshot
c.mu.RUnlock()
if snapshot == nil {
return []model.Sensor{}
}
out := make([]model.Sensor, len(snapshot.Sensors))
copy(out, snapshot.Sensors)
return out
}
// Sensor looks up one sensor.
func (c *Cache) Sensor(id string) (model.Sensor, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
if c.snapshot == nil {
return model.Sensor{}, false
}
sensor, ok := c.snapshot.sensorBy[id]
return sensor, ok
}
// Series returns the immutable series for a sensor, sorted by time.
func (c *Cache) Series(id string) ([]model.Point, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
if c.snapshot == nil {
return nil, false
}
points, ok := c.snapshot.Series[id]
return points, ok
}
// Context returns the current weather/holiday context.
func (c *Cache) Context() model.ContextData {
c.mu.RLock()
defer c.mu.RUnlock()
if c.snapshot == nil {
return 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()
if c.snapshot == nil {
return "", "", ""
}
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()
if c.snapshot == nil {
return 0
}
return len(c.snapshot.Sensors)
}
func cloneStatus(s model.CacheStatus) model.CacheStatus {
out := s
if s.LastSuccessAt != nil {
v := *s.LastSuccessAt
out.LastSuccessAt = &v
}
if s.LastError != nil {
v := *s.LastError
out.LastError = &v
}
if s.NextRetryAt != nil {
v := *s.NextRetryAt
out.NextRetryAt = &v
}
return out
}
func timePtr(t time.Time) *time.Time { return &t }
+295
View File
@@ -0,0 +1,295 @@
package cache
import (
"context"
"errors"
"sync"
"testing"
"time"
"pulsecast/api/internal/model"
)
type stubFetcher struct {
mu sync.Mutex
calls int
payload model.Bootstrap
err error
fn func(int) (model.Bootstrap, error)
}
func (s *stubFetcher) Bootstrap(context.Context) (model.Bootstrap, error) {
s.mu.Lock()
s.calls++
call := s.calls
payload, err, fn := s.payload, s.err, s.fn
s.mu.Unlock()
if fn != nil {
return fn(call)
}
return payload, err
}
func (s *stubFetcher) set(payload model.Bootstrap, err error) {
s.mu.Lock()
s.payload, s.err = payload, err
s.mu.Unlock()
}
func (s *stubFetcher) callCount() int {
s.mu.Lock()
defer s.mu.Unlock()
return s.calls
}
func fixturePayload() model.Bootstrap {
t0 := time.Date(2026, 11, 14, 3, 0, 0, 0, time.UTC)
return model.Bootstrap{
DataVersion: "2026-11-07T23:51:00Z",
ModelVersion: "histgb-2026-11-14",
ContextVersion: "2026-11-14T03:00:00Z",
Sensors: []model.Sensor{
{ID: "hn-zebra-01", Name: "Zebra", Lat: 49.1, Lon: 9.2, Mean: 1, P95: 2},
{ID: "hn-alpha-01", Name: "Alpha", Lat: 49.1, Lon: 9.2, Mean: 3, P95: 4},
},
Series: map[string][]model.Point{
"hn-alpha-01": {
{T: t0.Add(2 * time.Hour), V: 3},
{T: t0, V: 1},
{T: t0.Add(time.Hour), V: 2},
},
},
Context: model.ContextData{
Weather: model.Weather{
Now: model.WeatherNow{T: t0, TempC: 8.9, HumidityPct: 79},
Forecast: []model.WeatherPoint{{T: t0.Add(time.Hour), TempC: 8.4}},
},
Holidays: []model.Holiday{{Date: "2026-11-01", Name: "Allerheiligen"}},
UpdatedAt: t0,
},
Meta: model.BootstrapMeta{
Coverage: model.Coverage{Sensors: 8, From: "2026-06-12T00:00:00Z", To: "2026-11-07T23:51:00Z", CadenceMin: 15},
Metrics: model.Metrics{Model: "weather", MAE: 3.36, WAPE: 27.8, R2: 0.779},
Limits: []string{"estimated devices, not people"},
},
}
}
func TestRetryDelaySchedule(t *testing.T) {
c := New(&stubFetcher{}, Options{})
want := []time.Duration{1 * time.Second, 2 * time.Second, 4 * time.Second, 8 * time.Second, 16 * time.Second, 30 * time.Second, 30 * time.Second}
for i, expected := range want {
if got := c.retryDelay(i + 1); got != expected {
t.Errorf("retryDelay(%d)=%s, want %s", i+1, got, expected)
}
}
for _, failures := range []int{0, -1} {
if got := c.retryDelay(failures); got != time.Second {
t.Errorf("retryDelay(%d)=%s, want 1s", failures, got)
}
}
}
func TestRefreshLoadsSnapshotAndStatus(t *testing.T) {
fetcher := &stubFetcher{payload: fixturePayload()}
c := New(fetcher, Options{RefreshInterval: time.Minute, Timeout: time.Second})
fixed := time.Date(2026, 11, 14, 4, 0, 0, 0, time.UTC)
c.now = func() time.Time { return fixed }
if err := c.Refresh(context.Background()); err != nil {
t.Fatalf("Refresh: %v", err)
}
if !c.Loaded() || !c.Ready() || !c.Fresh() {
t.Fatalf("loaded=%v ready=%v fresh=%v", c.Loaded(), c.Ready(), c.Fresh())
}
data, modelOK := c.Readiness()
if !data || !modelOK {
t.Fatalf("readiness data=%v model=%v", data, modelOK)
}
if c.Len() != 2 {
t.Fatalf("Len=%d, want 2", c.Len())
}
sensors := c.Sensors()
if len(sensors) != 2 || sensors[0].ID != "hn-alpha-01" || sensors[1].ID != "hn-zebra-01" {
t.Fatalf("sensors not sorted: %+v", sensors)
}
if sensor, ok := c.Sensor("hn-zebra-01"); !ok || sensor.Name != "Zebra" {
t.Fatalf("Sensor: ok=%v sensor=%+v", ok, sensor)
}
if _, ok := c.Sensor("nope"); ok {
t.Fatal("unexpected sensor nope")
}
series, ok := c.Series("hn-alpha-01")
if !ok || len(series) != 3 || !series[0].T.Before(series[1].T) || !series[1].T.Before(series[2].T) {
t.Fatalf("series not sorted: ok=%v points=%+v", ok, series)
}
if ctx := c.Context(); ctx.UpdatedAt.IsZero() || len(ctx.Holidays) != 1 || len(ctx.Weather.Forecast) != 1 {
t.Fatalf("context=%+v", ctx)
}
dataVersion, modelVersion, contextVersion := c.Versions()
if dataVersion != "2026-11-07T23:51:00Z" || modelVersion != "histgb-2026-11-14" || contextVersion != "2026-11-14T03:00:00Z" {
t.Fatalf("versions=%q %q %q", dataVersion, modelVersion, contextVersion)
}
meta := c.Meta()
if meta.Coverage.Sensors != 8 || meta.Metrics.MAE != 3.36 || len(meta.Limits) != 1 {
t.Fatalf("meta=%+v", meta)
}
if meta.Cache.Source != Source || meta.Cache.LastSuccessAt == nil ||
!meta.Cache.LastSuccessAt.Equal(fixed) || meta.Cache.LastError != nil ||
meta.Cache.NextRetryAt != nil || meta.Cache.Failures != 0 {
t.Fatalf("cache status=%+v", meta.Cache)
}
}
func TestRefreshFailureKeepsLastGoodAndCountsBackoff(t *testing.T) {
fetcher := &stubFetcher{payload: fixturePayload()}
c := New(fetcher, Options{RefreshInterval: time.Minute, Timeout: time.Second})
fixed := time.Date(2026, 11, 14, 4, 0, 0, 0, time.UTC)
c.now = func() time.Time { return fixed }
if err := c.Refresh(context.Background()); err != nil {
t.Fatalf("prime: %v", err)
}
primed := c.Sensors()
fetcher.set(model.Bootstrap{}, errors.New("connection refused"))
if err := c.Refresh(context.Background()); err == nil {
t.Fatal("expected refresh failure")
}
if !c.Ready() || c.Fresh() {
t.Fatalf("ready=%v fresh=%v, want ready and not fresh", c.Ready(), c.Fresh())
}
if got := c.Sensors(); len(got) != len(primed) || got[0].ID != primed[0].ID {
t.Fatalf("last good snapshot lost: %+v", got)
}
status := c.Status()
if status.Failures != 1 || status.LastError == nil || *status.LastError != "connection refused" {
t.Fatalf("status=%+v", status)
}
if status.LastSuccessAt == nil || !status.LastSuccessAt.Equal(fixed) {
t.Fatalf("last success=%v", status.LastSuccessAt)
}
if status.NextRetryAt == nil || !status.NextRetryAt.Equal(fixed.Add(time.Second)) {
t.Fatalf("next retry=%v, want %s", status.NextRetryAt, fixed.Add(time.Second))
}
if err := c.Refresh(context.Background()); err == nil {
t.Fatal("expected second refresh failure")
}
status = c.Status()
if status.Failures != 2 || status.NextRetryAt == nil || !status.NextRetryAt.Equal(fixed.Add(2*time.Second)) {
t.Fatalf("second failure status=%+v", status)
}
fetcher.set(fixturePayload(), nil)
if err := c.Refresh(context.Background()); err != nil {
t.Fatalf("recovery: %v", err)
}
status = c.Status()
if status.Failures != 0 || status.LastError != nil || status.NextRetryAt != nil || !c.Fresh() {
t.Fatalf("recovered status=%+v fresh=%v", status, c.Fresh())
}
if status.LastSuccessAt == nil || !status.LastSuccessAt.Equal(fixed) {
t.Fatalf("last success after recovery=%v", status.LastSuccessAt)
}
}
func TestRefreshRejectsIncompleteSnapshot(t *testing.T) {
for name, mutate := range map[string]func(*model.Bootstrap){
"no sensors": func(b *model.Bootstrap) { b.Sensors = nil },
"no data version": func(b *model.Bootstrap) { b.DataVersion = "" },
"no model version": func(b *model.Bootstrap) { b.ModelVersion = "" },
"no context version": func(b *model.Bootstrap) { b.ContextVersion = "" },
"no context time": func(b *model.Bootstrap) { b.Context.UpdatedAt = time.Time{} },
} {
t.Run(name, func(t *testing.T) {
payload := fixturePayload()
mutate(&payload)
c := New(&stubFetcher{payload: payload}, Options{Timeout: time.Second})
fixed := time.Date(2026, 11, 14, 4, 0, 0, 0, time.UTC)
c.now = func() time.Time { return fixed }
if err := c.Refresh(context.Background()); err == nil {
t.Fatal("expected validation error")
}
if c.Loaded() || c.Ready() {
t.Fatalf("loaded=%v ready=%v after invalid snapshot", c.Loaded(), c.Ready())
}
if status := c.Status(); status.Failures != 1 || status.LastError == nil ||
status.NextRetryAt == nil || !status.NextRetryAt.Equal(fixed.Add(time.Second)) {
t.Fatalf("status=%+v", status)
}
})
}
}
func TestRunRetriesWithBackoffThenLoads(t *testing.T) {
fetcher := &stubFetcher{fn: func(call int) (model.Bootstrap, error) {
if call <= 2 {
return model.Bootstrap{}, errors.New("not ready")
}
return fixturePayload(), nil
}}
c := New(fetcher, Options{RefreshInterval: 10 * time.Millisecond, Timeout: time.Second})
c.retry = []time.Duration{5 * time.Millisecond, 10 * time.Millisecond, 20 * time.Millisecond}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
done := make(chan struct{})
go func() {
c.Run(ctx)
close(done)
}()
deadline := time.Now().Add(2 * time.Second)
for !c.Loaded() {
if time.Now().After(deadline) {
t.Fatalf("cache did not load after retries; calls=%d status=%+v", fetcher.callCount(), c.Status())
}
time.Sleep(5 * time.Millisecond)
}
if got := fetcher.callCount(); got < 3 {
t.Fatalf("calls=%d, want at least 3", got)
}
if status := c.Status(); status.Failures != 0 || status.LastError != nil {
t.Fatalf("status after recovery=%+v", status)
}
cancel()
select {
case <-done:
case <-time.After(time.Second):
t.Fatal("Run did not stop after context cancellation")
}
}
func TestRunStopsWhenContextCancelled(t *testing.T) {
fetcher := &stubFetcher{err: errors.New("down")}
c := New(fetcher, Options{RefreshInterval: time.Hour, Timeout: time.Second})
c.retry = []time.Duration{time.Hour}
ctx, cancel := context.WithCancel(context.Background())
done := make(chan struct{})
go func() {
c.Run(ctx)
close(done)
}()
deadline := time.Now().Add(time.Second)
for fetcher.callCount() == 0 {
if time.Now().After(deadline) {
t.Fatal("Run never attempted the first fetch")
}
time.Sleep(time.Millisecond)
}
cancel()
select {
case <-done:
case <-time.After(time.Second):
t.Fatal("Run did not stop after context cancellation")
}
if status := c.Status(); status.Failures != 1 || status.NextRetryAt == nil {
t.Fatalf("status=%+v", status)
}
}
+14 -9
View File
@@ -10,13 +10,17 @@ import (
// Config is the process configuration.
type Config struct {
Addr string
DataDir string
FastAPIURL string
ControlUser string
ControlPass string
ControlToken string
Heartbeat time.Duration
MLTimeout time.Duration
// RefreshInterval is how often a healthy /bootstrap snapshot is refreshed.
RefreshInterval time.Duration
// BootstrapTimeout bounds one /bootstrap request.
BootstrapTimeout time.Duration
}
// Load reads configuration from env with local-development defaults.
@@ -26,14 +30,15 @@ type Config struct {
func Load() Config {
port := getenv("PORT", "8080")
return Config{
Addr: ":" + port,
DataDir: getenv("DATA_DIR", "testdata/data"),
FastAPIURL: getenv("FASTAPI_URL", "http://localhost:8000"),
ControlUser: os.Getenv("CONTROL_USER"),
ControlPass: os.Getenv("CONTROL_PASS"),
ControlToken: os.Getenv("CONTROL_TOKEN"),
Heartbeat: durationEnv("SSE_HEARTBEAT", 15*time.Second),
MLTimeout: durationEnv("ML_TIMEOUT", 1500*time.Millisecond),
Addr: ":" + port,
FastAPIURL: getenv("FASTAPI_URL", "http://localhost:8000"),
ControlUser: os.Getenv("CONTROL_USER"),
ControlPass: os.Getenv("CONTROL_PASS"),
ControlToken: os.Getenv("CONTROL_TOKEN"),
Heartbeat: durationEnv("SSE_HEARTBEAT", 15*time.Second),
MLTimeout: durationEnv("ML_TIMEOUT", 1500*time.Millisecond),
RefreshInterval: durationEnv("BOOTSTRAP_REFRESH", 60*time.Second),
BootstrapTimeout: durationEnv("BOOTSTRAP_TIMEOUT", 20*time.Second),
}
}
+23 -6
View File
@@ -6,22 +6,25 @@ import (
)
func TestLoadDefaults(t *testing.T) {
for _, key := range []string{"PORT", "DATA_DIR", "FASTAPI_URL", "CONTROL_USER", "CONTROL_PASS", "CONTROL_TOKEN", "SSE_HEARTBEAT", "ML_TIMEOUT"} {
for _, key := range []string{
"PORT", "FASTAPI_URL", "CONTROL_USER", "CONTROL_PASS", "CONTROL_TOKEN",
"SSE_HEARTBEAT", "ML_TIMEOUT", "BOOTSTRAP_REFRESH", "BOOTSTRAP_TIMEOUT",
} {
t.Setenv(key, "")
}
cfg := Load()
if cfg.Addr != ":8080" {
t.Errorf("Addr=%q", cfg.Addr)
}
if cfg.DataDir != "testdata/data" {
t.Errorf("DataDir=%q", cfg.DataDir)
}
if cfg.FastAPIURL != "http://localhost:8000" {
t.Errorf("FastAPIURL=%q", cfg.FastAPIURL)
}
if cfg.Heartbeat != 15*time.Second || cfg.MLTimeout != 1500*time.Millisecond {
t.Errorf("timeouts: heartbeat=%s ml=%s", cfg.Heartbeat, cfg.MLTimeout)
}
if cfg.RefreshInterval != 60*time.Second || cfg.BootstrapTimeout != 20*time.Second {
t.Errorf("snapshot: refresh=%s timeout=%s", cfg.RefreshInterval, cfg.BootstrapTimeout)
}
if cfg.ControlAuthConfigured() {
t.Error("control auth should be unconfigured by default")
}
@@ -32,16 +35,17 @@ func TestLoadDefaults(t *testing.T) {
func TestLoadFromEnv(t *testing.T) {
t.Setenv("PORT", "9999")
t.Setenv("DATA_DIR", "/data")
t.Setenv("FASTAPI_URL", "http://ml:8000")
t.Setenv("CONTROL_USER", "user")
t.Setenv("CONTROL_PASS", "pass")
t.Setenv("CONTROL_TOKEN", "token-123")
t.Setenv("SSE_HEARTBEAT", "5s")
t.Setenv("ML_TIMEOUT", "2s")
t.Setenv("BOOTSTRAP_REFRESH", "30s")
t.Setenv("BOOTSTRAP_TIMEOUT", "10s")
cfg := Load()
if cfg.Addr != ":9999" || cfg.DataDir != "/data" || cfg.FastAPIURL != "http://ml:8000" {
if cfg.Addr != ":9999" || cfg.FastAPIURL != "http://ml:8000" {
t.Fatalf("cfg=%+v", cfg)
}
if cfg.ControlToken != "token-123" {
@@ -50,6 +54,9 @@ func TestLoadFromEnv(t *testing.T) {
if cfg.Heartbeat != 5*time.Second || cfg.MLTimeout != 2*time.Second {
t.Fatalf("timeouts: heartbeat=%s ml=%s", cfg.Heartbeat, cfg.MLTimeout)
}
if cfg.RefreshInterval != 30*time.Second || cfg.BootstrapTimeout != 10*time.Second {
t.Fatalf("snapshot: refresh=%s timeout=%s", cfg.RefreshInterval, cfg.BootstrapTimeout)
}
if !cfg.ControlAuthConfigured() {
t.Fatal("control auth should be configured")
}
@@ -58,17 +65,27 @@ func TestLoadFromEnv(t *testing.T) {
func TestDurationAcceptsPlainSeconds(t *testing.T) {
t.Setenv("SSE_HEARTBEAT", "7")
t.Setenv("ML_TIMEOUT", "3")
t.Setenv("BOOTSTRAP_REFRESH", "45")
t.Setenv("BOOTSTRAP_TIMEOUT", "12")
cfg := Load()
if cfg.Heartbeat != 7*time.Second || cfg.MLTimeout != 3*time.Second {
t.Fatalf("timeouts: heartbeat=%s ml=%s", cfg.Heartbeat, cfg.MLTimeout)
}
if cfg.RefreshInterval != 45*time.Second || cfg.BootstrapTimeout != 12*time.Second {
t.Fatalf("snapshot: refresh=%s timeout=%s", cfg.RefreshInterval, cfg.BootstrapTimeout)
}
}
func TestDurationFallsBackOnInvalidValue(t *testing.T) {
t.Setenv("SSE_HEARTBEAT", "soon")
t.Setenv("ML_TIMEOUT", "-1s")
t.Setenv("BOOTSTRAP_REFRESH", "later")
t.Setenv("BOOTSTRAP_TIMEOUT", "-3s")
cfg := Load()
if cfg.Heartbeat != 15*time.Second || cfg.MLTimeout != 1500*time.Millisecond {
t.Fatalf("timeouts: heartbeat=%s ml=%s", cfg.Heartbeat, cfg.MLTimeout)
}
if cfg.RefreshInterval != 60*time.Second || cfg.BootstrapTimeout != 20*time.Second {
t.Fatalf("snapshot: refresh=%s timeout=%s", cfg.RefreshInterval, cfg.BootstrapTimeout)
}
}
+43 -2
View File
@@ -1,5 +1,6 @@
// Package ml is the FastAPI client. Every call is bounded by a 1.5 s timeout;
// callers fall back to baked JSON on any error.
// 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
import (
@@ -23,11 +24,16 @@ const DefaultTimeout = 1500 * time.Millisecond
// larger than prediction payloads, so they get more than DefaultTimeout.
const controlTimeout = 30 * time.Second
// bootstrapTimeout is the upper transport bound for the /bootstrap snapshot,
// which carries the full hourly series for every sensor.
const bootstrapTimeout = 30 * time.Second
// Client talks to the FastAPI ML service.
type Client struct {
baseURL string
http *http.Client
control *http.Client
bootstrap *http.Client
controlToken string
}
@@ -46,10 +52,45 @@ func NewWithToken(baseURL string, timeout time.Duration, controlToken string) *C
baseURL: strings.TrimRight(baseURL, "/"),
http: &http.Client{Timeout: timeout},
control: &http.Client{Timeout: controlTimeout},
bootstrap: &http.Client{Timeout: bootstrapTimeout},
controlToken: controlToken,
}
}
// Bootstrap fetches GET /bootstrap, the runtime snapshot the API caches. The
// caller supplies the shorter request deadline; this method only validates the
// transport response and that the snapshot is usable.
func (c *Client) Bootstrap(ctx context.Context) (model.Bootstrap, error) {
var out model.Bootstrap
req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/bootstrap", nil)
if err != nil {
return out, fmt.Errorf("ml: build request: %w", err)
}
req.Header.Set("Accept", "application/json")
resp, err := c.bootstrap.Do(req)
if err != nil {
return out, fmt.Errorf("ml: /bootstrap: %w", err)
}
defer resp.Body.Close()
if resp.StatusCode < 200 || resp.StatusCode > 299 {
snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 256))
return out, fmt.Errorf("ml: /bootstrap: status %d: %s", resp.StatusCode, strings.TrimSpace(string(snippet)))
}
raw, err := io.ReadAll(io.LimitReader(resp.Body, 64<<20))
if err != nil {
return out, fmt.Errorf("ml: read /bootstrap: %w", err)
}
if err := json.Unmarshal(raw, &out); err != nil {
return out, fmt.Errorf("ml: decode /bootstrap: %w", err)
}
if len(out.Sensors) == 0 {
return out, fmt.Errorf("ml: /bootstrap returned no sensors")
}
return out, nil
}
// PredictRequest mirrors CONTRACT.md §3 POST /predict.
type PredictRequest struct {
Sensor string `json:"sensor"`
+88
View File
@@ -121,6 +121,94 @@ func TestSimulate(t *testing.T) {
}
}
func TestBootstrapFetchesSnapshot(t *testing.T) {
var gotMethod, gotPath, gotAuth string
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
gotMethod, gotPath, gotAuth = r.Method, r.URL.Path, r.Header.Get("Authorization")
_, _ = w.Write([]byte(`{
"data_version":"2026-11-07T23:51:00Z",
"model_version":"histgb-2026-11-14",
"context_version":"2026-11-14T03:00:00Z",
"sensors":[{"id":"hn-bahnhof-01","name":"Bahnhof","lat":49.14,"lon":9.2,"mean":24.2,"p95":88.2,"battery":71}],
"series":{"hn-bahnhof-01":[{"t":"2026-11-01T10:00:00Z","v":12.3}]},
"context":{"weather":{"now":{"t":"2026-11-14T03:00:00Z","temp_c":8.9,"precip_mm":0,"cloud_pct":80,"wind_kmh":11,"humidity_pct":79},"forecast":[]},"holidays":[{"date":"2026-11-01","name":"Allerheiligen"}],"updated_at":"2026-11-14T03:00:00Z"},
"meta":{"coverage":{"sensors":8,"from":"2026-06-12T00:00:00Z","to":"2026-11-07T23:51:00Z","cadence_min":15},"metrics":{"model":"weather","mae":3.36,"wape":27.8,"r2":0.779,"baseline_mae":5.4,"baseline_wape":44.7},"limits":["estimated devices, not people"]}
}`))
}))
defer srv.Close()
// The control token is for /train only; /bootstrap must stay unauthenticated.
payload, err := NewWithToken(srv.URL, time.Second, "secret-token").Bootstrap(context.Background())
if err != nil {
t.Fatalf("Bootstrap: %v", err)
}
if gotMethod != http.MethodGet || gotPath != "/bootstrap" {
t.Fatalf("request=%s %s, want GET /bootstrap", gotMethod, gotPath)
}
if gotAuth != "" {
t.Errorf("Authorization=%q, want none", gotAuth)
}
if len(payload.Sensors) != 1 || payload.Sensors[0].ID != "hn-bahnhof-01" || payload.Sensors[0].Battery == nil {
t.Fatalf("sensors=%+v", payload.Sensors)
}
if len(payload.Series["hn-bahnhof-01"]) != 1 || payload.Series["hn-bahnhof-01"][0].V != 12.3 {
t.Fatalf("series=%+v", payload.Series)
}
if payload.Context.UpdatedAt.IsZero() || len(payload.Context.Holidays) != 1 {
t.Fatalf("context=%+v", payload.Context)
}
if payload.DataVersion == "" || payload.ModelVersion == "" || payload.ContextVersion == "" {
t.Fatalf("versions=%+v", payload)
}
if payload.Meta.Coverage.Sensors != 8 || payload.Meta.Metrics.MAE != 3.36 || len(payload.Meta.Limits) != 1 {
t.Fatalf("meta=%+v", payload.Meta)
}
}
func TestBootstrapRejectsErrorAndEmptySensors(t *testing.T) {
boom := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
http.Error(w, "not ready", http.StatusServiceUnavailable)
}))
defer boom.Close()
if _, err := New(boom.URL, time.Second).Bootstrap(context.Background()); err == nil {
t.Fatal("expected an error for HTTP 503")
}
empty := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
_, _ = w.Write([]byte(`{"sensors":[]}`))
}))
defer empty.Close()
if _, err := New(empty.URL, time.Second).Bootstrap(context.Background()); err == nil {
t.Fatal("expected an error for an empty sensor list")
}
bad := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
_, _ = w.Write([]byte(`{`))
}))
defer bad.Close()
if _, err := New(bad.URL, time.Second).Bootstrap(context.Background()); err == nil {
t.Fatal("expected an error for invalid JSON")
}
}
func TestBootstrapTimeout(t *testing.T) {
slow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
time.Sleep(150 * time.Millisecond)
_, _ = w.Write([]byte(`{"sensors":[{"id":"s"}]}`))
}))
defer slow.Close()
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
defer cancel()
start := time.Now()
if _, err := New(slow.URL, time.Second).Bootstrap(ctx); err == nil {
t.Fatal("expected a context timeout")
}
if elapsed := time.Since(start); elapsed > time.Second {
t.Fatalf("timeout took %s", elapsed)
}
}
func TestNewUsesDefaultTimeout(t *testing.T) {
client := New("http://example.invalid", 0)
if client.http.Timeout != DefaultTimeout {
+37 -6
View File
@@ -66,12 +66,43 @@ type Metrics struct {
// Meta is GET /api/meta.
type Meta struct {
DataVersion string `json:"data_version"`
ModelVersion string `json:"model_version"`
ContextVersion string `json:"context_version"`
Coverage Coverage `json:"coverage"`
Metrics Metrics `json:"metrics"`
Limits []string `json:"limits"`
DataVersion string `json:"data_version"`
ModelVersion string `json:"model_version"`
ContextVersion string `json:"context_version"`
Coverage Coverage `json:"coverage"`
Metrics Metrics `json:"metrics"`
Limits []string `json:"limits"`
Cache CacheStatus `json:"cache"`
}
// CacheStatus is the runtime snapshot state exposed by GET /api/meta.
// LastError, LastSuccessAt and NextRetryAt are null when they do not apply.
type CacheStatus struct {
Source string `json:"source"`
LastSuccessAt *time.Time `json:"last_success_at"`
LastError *string `json:"last_error"`
NextRetryAt *time.Time `json:"next_retry_at"`
Failures int `json:"failures"`
}
// BootstrapMeta is the nested meta block of FastAPI GET /bootstrap.
type BootstrapMeta struct {
Coverage Coverage `json:"coverage"`
Metrics Metrics `json:"metrics"`
Limits []string `json:"limits"`
}
// Bootstrap is the snapshot FastAPI serves at GET /bootstrap and Go keeps in
// memory. Forecasts are deliberately absent: they come from /predict and are
// cached separately as they are requested.
type Bootstrap struct {
DataVersion string `json:"data_version"`
ModelVersion string `json:"model_version"`
ContextVersion string `json:"context_version"`
Sensors []Sensor `json:"sensors"`
Series map[string][]Point `json:"series"`
Context ContextData `json:"context"`
Meta BootstrapMeta `json:"meta"`
}
// WeatherNow is the current conditions block.
-189
View File
@@ -1,189 +0,0 @@
// Package store loads the baked JSON artifacts described in CONTRACT.md §4.
// The data is immutable after Load; all accessors are safe for concurrent use.
package store
import (
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"sort"
"strings"
"pulsecast/api/internal/model"
)
// Store is the in-memory baked dataset.
type Store struct {
meta model.Meta
sensors []model.Sensor
sensorBy map[string]model.Sensor
series map[string][]model.Point
forecasts map[string]map[string]map[string][]model.ForecastPoint
context model.ContextData
}
// Load reads every artifact from dir. It returns a usable (possibly partial)
// store together with a joined error so callers can start the API and let
// /api/readyz report 503 instead of crash-looping.
func Load(dir string) (*Store, error) {
s := &Store{
sensorBy: make(map[string]model.Sensor),
series: make(map[string][]model.Point),
forecasts: make(map[string]map[string]map[string][]model.ForecastPoint),
}
var errs []error
if err := readJSON(filepath.Join(dir, "sensors.json"), &s.sensors); err != nil {
errs = append(errs, err)
}
sort.Slice(s.sensors, func(i, j int) bool { return s.sensors[i].ID < s.sensors[j].ID })
for _, sensor := range s.sensors {
s.sensorBy[sensor.ID] = sensor
}
if err := readJSON(filepath.Join(dir, "metrics.json"), &s.meta); err != nil {
errs = append(errs, err)
}
if err := readJSON(filepath.Join(dir, "context.json"), &s.context); err != nil {
errs = append(errs, err)
}
if err := loadSeries(dir, s); err != nil {
errs = append(errs, err)
}
if err := readJSON(filepath.Join(dir, "forecasts.json"), &s.forecasts); err != nil {
errs = append(errs, err)
}
for sensorID, scenarios := range s.forecasts {
for scenario, horizons := range scenarios {
for horizon, points := range horizons {
sort.Slice(points, func(i, j int) bool { return points[i].T.Before(points[j].T) })
horizons[horizon] = points
}
scenarios[scenario] = horizons
}
s.forecasts[sensorID] = scenarios
}
return s, errors.Join(errs...)
}
func loadSeries(dir string, s *Store) error {
var errs []error
// Contract allows a single series.json mapping sensor id -> points.
var combined map[string][]model.Point
err := readJSON(filepath.Join(dir, "series.json"), &combined)
switch {
case err == nil:
for sensorID, points := range combined {
sort.Slice(points, func(i, j int) bool { return points[i].T.Before(points[j].T) })
s.series[sensorID] = points
}
case !errors.Is(err, os.ErrNotExist):
errs = append(errs, err)
}
// Contract also allows series/<id>.json; these override the combined file.
entries, err := os.ReadDir(filepath.Join(dir, "series"))
if err != nil {
if !errors.Is(err, os.ErrNotExist) {
errs = append(errs, fmt.Errorf("series dir: %w", err))
}
return errors.Join(errs...)
}
for _, entry := range entries {
if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
continue
}
var points []model.Point
path := filepath.Join(dir, "series", entry.Name())
if err := readJSON(path, &points); err != nil {
errs = append(errs, err)
continue
}
sort.Slice(points, func(i, j int) bool { return points[i].T.Before(points[j].T) })
s.series[strings.TrimSuffix(entry.Name(), ".json")] = points
}
return errors.Join(errs...)
}
func readJSON(path string, dst any) error {
raw, err := os.ReadFile(path)
if err != nil {
return fmt.Errorf("read %s: %w", path, err)
}
if err := json.Unmarshal(raw, dst); err != nil {
return fmt.Errorf("decode %s: %w", path, err)
}
return nil
}
// Meta returns the model/data metadata.
func (s *Store) Meta() model.Meta { return s.meta }
// Sensors returns the sensors sorted by id.
func (s *Store) Sensors() []model.Sensor {
out := make([]model.Sensor, len(s.sensors))
copy(out, s.sensors)
return out
}
// Sensor looks up one sensor.
func (s *Store) Sensor(id string) (model.Sensor, bool) {
sensor, ok := s.sensorBy[id]
return sensor, ok
}
// Series returns the raw (15-minute) series for a sensor.
func (s *Store) Series(id string) ([]model.Point, bool) {
points, ok := s.series[id]
return points, ok
}
// Forecast returns baked points for sensor/scenario/horizon.
func (s *Store) Forecast(sensor, scenario, horizon string) ([]model.ForecastPoint, bool) {
scenarios, ok := s.forecasts[sensor]
if !ok {
return nil, false
}
horizons, ok := scenarios[scenario]
if !ok {
return nil, false
}
points, ok := horizons[horizon]
if !ok || len(points) == 0 {
return nil, false
}
return points, true
}
// Context returns the baked weather/holiday context.
func (s *Store) Context() model.ContextData { return s.context }
// Versions returns data, model and context version strings.
func (s *Store) Versions() (data, modelVersion, context string) {
return s.meta.DataVersion, s.meta.ModelVersion, s.meta.ContextVersion
}
// Ready reports whether the minimum baked set is present. FastAPI health is
// deliberately not part of readiness: the cache fallback is the safety net.
func (s *Store) Ready() bool {
if len(s.sensors) == 0 || s.meta.ModelVersion == "" || s.context.UpdatedAt.IsZero() {
return false
}
for _, sensor := range s.sensors {
if _, ok := s.Forecast(sensor.ID, "base", "7d"); ok {
return true
}
}
return false
}
// Len returns the number of loaded sensors (used in tests/logs).
func (s *Store) Len() int { return len(s.sensors) }
-65
View File
@@ -1,65 +0,0 @@
package store
import (
"testing"
)
func TestLoadFixtures(t *testing.T) {
st, err := Load("../../testdata/data")
if err != nil {
t.Fatalf("Load: %v", err)
}
if !st.Ready() {
t.Fatal("Ready()=false for the fixture dataset")
}
if st.Len() != 8 {
t.Fatalf("Len()=%d, want 8", st.Len())
}
sensors := st.Sensors()
for i := 1; i < len(sensors); i++ {
if sensors[i-1].ID >= sensors[i].ID {
t.Fatalf("sensors not sorted: %q then %q", sensors[i-1].ID, sensors[i].ID)
}
}
if _, ok := st.Sensor("hn-bahnhof-01"); !ok {
t.Fatal("missing hn-bahnhof-01")
}
if _, ok := st.Sensor("nope"); ok {
t.Fatal("unexpected sensor nope")
}
if points, ok := st.Series("hn-bahnhof-01"); !ok || len(points) == 0 {
t.Fatalf("series: ok=%v points=%d", ok, len(points))
}
if points, ok := st.Forecast("hn-bahnhof-01", "sunny-saturday-market", "7d"); !ok || len(points) != 168 {
t.Fatalf("forecast: ok=%v points=%d", ok, len(points))
}
if _, ok := st.Forecast("hn-bahnhof-01", "base", "2h"); ok {
t.Fatal("unexpected horizon 2h")
}
if ctx := st.Context(); ctx.UpdatedAt.IsZero() || len(ctx.Weather.Forecast) == 0 || len(ctx.Holidays) == 0 {
t.Fatalf("context incomplete: %+v", ctx)
}
data, modelVersion, context := st.Versions()
if data == "" || modelVersion == "" || context == "" {
t.Fatalf("versions: data=%q model=%q context=%q", data, modelVersion, context)
}
}
func TestLoadMissingDirectoryIsPartial(t *testing.T) {
st, err := Load(t.TempDir())
if err == nil {
t.Fatal("expected an error for an empty data dir")
}
if st == nil {
t.Fatal("Load returned a nil store; handlers need a usable store")
}
if st.Ready() {
t.Fatal("Ready()=true without data")
}
if st.Len() != 0 {
t.Fatalf("Len()=%d, want 0", st.Len())
}
}
+1
View File
@@ -0,0 +1 @@
{"data_version":"2026-11-07T23:51:00Z","model_version":"histgb-2026-11-14","context_version":"2026-11-14T03:00:00Z","sensors":[{"id":"hn-bahnhof-01","name":"Bahnhof","lat":49.1429,"lon":9.2076,"mean":24.2,"p95":88.2,"battery":71},{"id":"hn-deutschhof-01","name":"Deutschhof","lat":49.1397,"lon":9.2149,"mean":14.0,"p95":49.6,"battery":null},{"id":"hn-kaiserstrasse-01","name":"Kaiserstra\u00dfe","lat":49.1419,"lon":9.2096,"mean":21.1,"p95":74.1,"battery":64},{"id":"hn-marktplatz-01","name":"Marktplatz","lat":49.1426,"lon":9.212,"mean":17.9,"p95":63.8,"battery":83},{"id":"hn-neckar-01","name":"Neckarufer","lat":49.1448,"lon":9.2087,"mean":9.4,"p95":35.4,"battery":92},{"id":"hn-rathaus-01","name":"Rathaus","lat":49.1422,"lon":9.2131,"mean":15.6,"p95":55.9,"battery":58},{"id":"hn-stadtgalerie-01","name":"Stadtgalerie","lat":49.1427,"lon":9.2109,"mean":22.6,"p95":67.2,"battery":87},{"id":"hn-theater-01","name":"Theater","lat":49.1402,"lon":9.2124,"mean":11.7,"p95":41.7,"battery":49}],"series":{"hn-bahnhof-01":[{"t":"2026-10-25T00:00:00Z","v":3.6},{"t":"2026-10-25T00:15:00Z","v":4.1},{"t":"2026-10-25T00:30:00Z","v":4.4},{"t":"2026-10-25T00:45:00Z","v":4.0},{"t":"2026-10-25T01:00:00Z","v":3.7},{"t":"2026-10-25T01:15:00Z","v":3.6},{"t":"2026-10-25T01:30:00Z","v":4.3},{"t":"2026-10-25T01:45:00Z","v":3.8},{"t":"2026-10-25T02:00:00Z","v":4.5},{"t":"2026-10-25T02:15:00Z","v":3.7},{"t":"2026-10-25T02:30:00Z","v":4.4},{"t":"2026-10-25T02:45:00Z","v":4.3},{"t":"2026-10-25T03:00:00Z","v":4.2},{"t":"2026-10-25T03:15:00Z","v":4.1},{"t":"2026-10-25T03:30:00Z","v":3.9},{"t":"2026-10-25T03:45:00Z","v":3.8},{"t":"2026-10-25T04:00:00Z","v":3.8},{"t":"2026-10-25T04:15:00Z","v":3.7},{"t":"2026-10-25T04:30:00Z","v":4.4},{"t":"2026-10-25T04:45:00Z","v":4.1},{"t":"2026-10-25T05:00:00Z","v":12.8},{"t":"2026-10-25T05:15:00Z","v":12.7},{"t":"2026-10-25T05:30:00Z","v":12.9},{"t":"2026-10-25T05:45:00Z","v":11.4},{"t":"2026-10-25T06:00:00Z","v":16.3},{"t":"2026-10-25T06:15:00Z","v":17.5},{"t":"2026-10-25T06:30:00Z","v":17.3},{"t":"2026-10-25T06:45:00Z","v":17.0},{"t":"2026-10-25T07:00:00Z","v":23.5},{"t":"2026-10-25T07:15:00Z","v":23.5},{"t":"2026-10-25T07:30:00Z","v":20.4},{"t":"2026-10-25T07:45:00Z","v":19.5},{"t":"2026-10-25T08:00:00Z","v":26.7},{"t":"2026-10-25T08:15:00Z","v":25.3},{"t":"2026-10-25T08:30:00Z","v":28.2},{"t":"2026-10-25T08:45:00Z","v":23.6},{"t":"2026-10-25T09:00:00Z","v":30.1},{"t":"2026-10-25T09:15:00Z","v":31.2},{"t":"2026-10-25T09:30:00Z","v":30.4},{"t":"2026-10-25T09:45:00Z","v":33.7},{"t":"2026-10-25T10:00:00Z","v":37.2},{"t":"2026-10-25T10:15:00Z","v":32.1},{"t":"2026-10-25T10:30:00Z","v":36.9},{"t":"2026-10-25T10:45:00Z","v":30.6},{"t":"2026-10-25T11:00:00Z","v":35.9},{"t":"2026-10-25T11:15:00Z","v":31.7},{"t":"2026-10-25T11:30:00Z","v":30.7},{"t":"2026-10-25T11:45:00Z","v":35.4},{"t":"2026-10-25T12:00:00Z","v":36.0},{"t":"2026-10-25T12:15:00Z","v":31.3},{"t":"2026-10-25T12:30:00Z","v":30.0},{"t":"2026-10-25T12:45:00Z","v":32.9},{"t":"2026-10-25T13:00:00Z","v":27.5},{"t":"2026-10-25T13:15:00Z","v":26.5},{"t":"2026-10-25T13:30:00Z","v":28.1},{"t":"2026-10-25T13:45:00Z","v":29.8},{"t":"2026-10-25T14:00:00Z","v":26.4},{"t":"2026-10-25T14:15:00Z","v":26.5},{"t":"2026-10-25T14:30:00Z","v":29.2},{"t":"2026-10-25T14:45:00Z","v":29.3},{"t":"2026-10-25T15:00:00Z","v":30.5},{"t":"2026-10-25T15:15:00Z","v":30.7},{"t":"2026-10-25T15:30:00Z","v":27.4},{"t":"2026-10-25T15:45:00Z","v":25.2},{"t":"2026-10-25T16:00:00Z","v":31.8},{"t":"2026-10-25T16:15:00Z","v":28.9},{"t":"2026-10-25T16:30:00Z","v":33.3},{"t":"2026-10-25T16:45:00Z","v":32.8},{"t":"2026-10-25T17:00:00Z","v":33.7},{"t":"2026-10-25T17:15:00Z","v":31.5},{"t":"2026-10-25T17:30:00Z","v":33.8},{"t":"2026-10-25T17:45:00Z","v":31.9},{"t":"2026-10-25T18:00:00Z","v":29.9},{"t":"2026-10-25T18:15:00Z","v":32.6},{"t":"2026-10-25T18:30:00Z","v":31.8},{"t":"2026-10-25T18:45:00Z","v":32.6},{"t":"2026-10-25T19:00:00Z","v":16.7},{"t":"2026-10-25T19:15:00Z","v":15.7},{"t":"2026-10-25T19:30:00Z","v":16.2},{"t":"2026-10-25T19:45:00Z","v":15.8},{"t":"2026-10-25T20:00:00Z","v":15.8},{"t":"2026-10-25T20:15:00Z","v":14.4},{"t":"2026-10-25T20:30:00Z","v":16.5},{"t":"2026-10-25T20:45:00Z","v":15.7},{"t":"2026-10-25T21:00:00Z","v":16.7},{"t":"2026-10-25T21:15:00Z","v":13.8},{"t":"2026-10-25T21:30:00Z","v":16.7},{"t":"2026-10-25T21:45:00Z","v":14.2},{"t":"2026-10-25T22:00:00Z","v":7.2},{"t":"2026-10-25T22:15:00Z","v":6.5},{"t":"2026-10-25T22:30:00Z","v":7.1},{"t":"2026-10-25T22:45:00Z","v":5.9},{"t":"2026-10-25T23:00:00Z","v":3.6},{"t":"2026-10-25T23:15:00Z","v":4.1},{"t":"2026-10-25T23:30:00Z","v":3.9},{"t":"2026-10-25T23:45:00Z","v":3.7},{"t":"2026-10-26T00:00:00Z","v":3.4},{"t":"2026-10-26T00:15:00Z","v":3.5},{"t":"2026-10-26T00:30:00Z","v":4.0},{"t":"2026-10-26T00:45:00Z","v":3.7},{"t":"2026-10-26T01:00:00Z","v":3.9},{"t":"2026-10-26T01:15:00Z","v":3.7},{"t":"2026-10-26T01:30:00Z","v":4.0},{"t":"2026-10-26T01:45:00Z","v":3.9},{"t":"2026-10-26T02:00:00Z","v":3.5},{"t":"2026-10-26T02:15:00Z"Line truncated