feat: runtime bootstrap snapshot cache with backoff

This commit is contained in:
Noel Sabia committed 2026-11-14 06:08:53 +01:00
1 parent 08f60a14d1
commit aa6bb23e24
19 files changed
+1400 -384

No files matched your search

+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 {