From b10ae8c1317fa27d11bca6fc4f06f53dc3a4f24f Mon Sep 17 00:00:00 2001 From: hannesb90 Date: Tue, 10 Nov 2026 10:42:23 +0100 Subject: [PATCH] refactor(drivercontrol): move operator holds out of the API The per-driver lock, hold, expiry and default path move unchanged from internal/api into internal/drivercontrol, so a planned value can later go through the same lock and expiry as an operator's (ADR 0012). The API keeps its routes, responses and SendDriverDefault; the registry lifecycle hook now clears holds through the package. As asked on #1994, the unused thermal policy draft goes with it: DecideIntent, DecisionInput, Intent, TemperatureBand, MarginalPrice and the synthetic_price strategy. The declaration vocabulary stays. Co-Authored-By: Claude Opus 5.5 Signed-off-by: hannesb90 --- .changeset/driver-control-holds-package.md | 7 + go/internal/api/api.go | 23 +- go/internal/api/api_driver_control.go | 318 +++--------------- go/internal/api/api_driver_control_test.go | 104 +++--- go/internal/api/api_driver_thermal_test.go | 2 +- go/internal/api/api_drivers_debug.go | 7 +- go/internal/drivercontrol/holds.go | 360 +++++++++++++++++++++ go/internal/drivercontrol/holds_test.go | 213 ++++++++++++ go/internal/drivers/catalog_thermal.go | 3 +- go/internal/thermal/model.go | 187 +---------- go/internal/thermal/model_test.go | 146 +-------- 11 files changed, 709 insertions(+), 661 deletions(-) create mode 100644 .changeset/driver-control-holds-package.md create mode 100644 go/internal/drivercontrol/holds.go create mode 100644 go/internal/drivercontrol/holds_test.go diff --git a/.changeset/driver-control-holds-package.md b/.changeset/driver-control-holds-package.md new file mode 100644 index 000000000..36c2afced --- /dev/null +++ b/.changeset/driver-control-holds-package.md @@ -0,0 +1,7 @@ +--- +"ftw": patch +--- + +Internal: operator driver-control holds moved from the API into their own +package so a later planner can share the same lock and expiry, and the unused +thermal policy draft (`DecideIntent`) is removed. No behaviour change. diff --git a/go/internal/api/api.go b/go/internal/api/api.go index d6de34afb..90b2a8925 100644 --- a/go/internal/api/api.go +++ b/go/internal/api/api.go @@ -39,6 +39,7 @@ import ( "github.com/srcfl/ftw/go/internal/configreload" "github.com/srcfl/ftw/go/internal/control" "github.com/srcfl/ftw/go/internal/coverage" + "github.com/srcfl/ftw/go/internal/drivercontrol" "github.com/srcfl/ftw/go/internal/driverrepo" "github.com/srcfl/ftw/go/internal/drivers" "github.com/srcfl/ftw/go/internal/energyreport" @@ -296,11 +297,9 @@ type Server struct { savingsCacheMu sync.Mutex savingsCache map[string]daySavings - // controlStates serializes command dispatch, default dispatch, and hold - // transitions per driver. Process-lifetime only, deliberately: a restart - // should leave no device held by a setting nobody remembers making. - controlStateMu sync.Mutex - controlStates map[string]*controlDriverState + // controlHolds serializes command dispatch, default dispatch, and hold + // transitions per driver. Process-lifetime only; see drivercontrol. + controlHolds *drivercontrol.Holds // beforeDriverControlSend is a package-test seam for reproducing a // lifecycle change between request validation and registry dispatch. It is @@ -340,13 +339,13 @@ func New(deps *Deps) *Server { deps.WebDir = "web" } s := &Server{ - deps: deps, - mux: http.NewServeMux(), - dailyCache: make(map[string]state.DayEnergy), - controlStates: make(map[string]*controlDriverState), - drafts: newDriverDrafts(), - marks: make(map[string]routeMark), + deps: deps, + mux: http.NewServeMux(), + dailyCache: make(map[string]state.DayEnergy), + drafts: newDriverDrafts(), + marks: make(map[string]routeMark), } + s.controlHolds = drivercontrol.New(s.controlRegistry) s.setup = onboarding.NewWithSecrets(deps.State, s.preserveSetupSecrets, filepath.Dir(deps.ConfigPath)) if deps.SaveConfigWithValues == nil && deps.State != nil { deps.SaveConfigWithValues = func(path string, cfg *config.Config, values map[string]string, reviewedJSON []byte, beforeSave func() error) error { @@ -356,7 +355,7 @@ func New(deps *Deps) *Server { if deps.Registry != nil { // Registry removal is the lifecycle boundary for a driver generation. // Clear the API hold before a replacement instance can be added. - deps.Registry.SetLifecycleHook(s.clearDriverControl) + deps.Registry.SetLifecycleHook(s.controlHolds.Clear) } s.routes() // A draft's timer died with the previous process, so anything left behind diff --git a/go/internal/api/api_driver_control.go b/go/internal/api/api_driver_control.go index c6db6952e..82006752f 100644 --- a/go/internal/api/api_driver_control.go +++ b/go/internal/api/api_driver_control.go @@ -20,13 +20,12 @@ import ( "encoding/json" "errors" "fmt" - "log/slog" "math" "net/http" "slices" - "sync" "time" + "github.com/srcfl/ftw/go/internal/drivercontrol" "github.com/srcfl/ftw/go/internal/drivers" ) @@ -37,26 +36,8 @@ import ( const ( maxControlHoldSeconds = 24 * 60 * 60 defaultControlHoldSeconds = 4 * 60 * 60 - controlDefaultTimeout = 10 * time.Second ) -type controlDriverState struct { - mu sync.Mutex - hold *controlHold -} - -// controlHold is one active operator setting. The timer is what releases it; -// the fields are what the UI shows meanwhile. -type controlHold struct { - Control string `json:"control"` - Value any `json:"value,omitempty"` - ExpiresAt int64 `json:"expires_at_ms"` - Generation uint64 `json:"-"` - - armedAt time.Time - timer *time.Timer -} - type controlRequest struct { Control string `json:"control"` Value json.RawMessage `json:"value"` @@ -143,53 +124,49 @@ func (s *Server) handleDriverControl(w http.ResponseWriter, r *http.Request) { s.beforeDriverControlSend() } - // Keep command dispatch and hold transitions under one per-driver lock. - // Registry.SendWithGeneration selects the concrete running instance and - // returns its generation, so expiry can never pair a new command with an - // old status snapshot. The state lookup and lock are also one lifecycle - // transaction: clearDriverControlState takes the same locks in the same - // order, so it cannot remove the map entry between these operations. - state := s.lockControlState(name, s.beforeDriverControlStateLock) - defer state.mu.Unlock() - // The lock is held across the device call, so the call gets a deadline: - // a request context has none, and hold expiry waits on this lock. - sendCtx, cancel := context.WithTimeout(r.Context(), controlDefaultTimeout) - defer cancel() - generation, err := s.deps.Registry.SendWithGeneration(sendCtx, name, body) - if err != nil { - s.clearControlHoldLocked(state) - if errors.Is(err, drivers.ErrObserveOnly) { - writeJSON(w, http.StatusForbidden, map[string]any{ - "error": err.Error(), - "observe_only": true, - }) - return - } - if errors.Is(err, drivers.ErrControlBlocked) { - status, _ := s.deps.Registry.ControlStatus(name) - writeJSON(w, http.StatusConflict, map[string]any{ - "error": err.Error(), - "control_blocked": true, - "default_confirmed": false, - "recovery_pending": status.RecoveryPending, + // drivercontrol.Holds.Send keeps dispatch and the hold transition under + // one per-driver lock and binds the hold to the generation that took the + // command. The response is written inside done, still under that lock, so + // the status read that explains an error is the one that caused it. + s.controlHolds.Send(r.Context(), name, control.ID, applied, body, + time.Duration(seconds)*time.Second, s.beforeDriverControlStateLock, + func(hold drivercontrol.Hold, err error) { + if err != nil { + s.writeControlSendError(w, name, err) + return + } + writeJSON(w, 200, map[string]any{ + "control": control.ID, + "applied": applied, + "evidence": control.Evidence, + "expires_at_ms": hold.ExpiresAt, }) - return - } - if _, running := s.deps.Registry.ControlStatus(name); !running { - writeJSON(w, http.StatusNotFound, map[string]string{"error": "driver not running"}) - return - } - writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()}) + }) +} + +func (s *Server) writeControlSendError(w http.ResponseWriter, name string, err error) { + if errors.Is(err, drivers.ErrObserveOnly) { + writeJSON(w, http.StatusForbidden, map[string]any{ + "error": err.Error(), + "observe_only": true, + }) return } - hold := s.armControlHoldLocked(name, state, control.ID, applied, generation, time.Duration(seconds)*time.Second) - - writeJSON(w, 200, map[string]any{ - "control": control.ID, - "applied": applied, - "evidence": control.Evidence, - "expires_at_ms": hold.ExpiresAt, - }) + if errors.Is(err, drivers.ErrControlBlocked) { + status, _ := s.deps.Registry.ControlStatus(name) + writeJSON(w, http.StatusConflict, map[string]any{ + "error": err.Error(), + "control_blocked": true, + "default_confirmed": false, + "recovery_pending": status.RecoveryPending, + }) + return + } + if _, running := s.deps.Registry.ControlStatus(name); !running { + writeJSON(w, http.StatusNotFound, map[string]string{"error": "driver not running"}) + return + } + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()}) } // DELETE /api/drivers/{name}/control — end the hold now. @@ -264,215 +241,18 @@ func clampToDeclared(value float64, in drivers.CatalogControlInput) float64 { return value } -// armControlHold replaces any existing hold for the driver. One driver holds -// one control at a time: two overlapping holds on the same device would each -// expire into a default that undoes the other. -func (s *Server) controlState(name string) *controlDriverState { - s.controlStateMu.Lock() - defer s.controlStateMu.Unlock() - return s.controlStateLocked(name) -} - -func (s *Server) controlStateLocked(name string) *controlDriverState { - if s.controlStates == nil { - s.controlStates = make(map[string]*controlDriverState) - } - state := s.controlStates[name] - if state == nil { - state = &controlDriverState{} - s.controlStates[name] = state - } - return state -} - -// lockControlState serializes a state map lookup with acquisition of that -// driver's mutex. Lifecycle invalidation uses controlStateMu -> state.mu as -// well, so a request can either own the state before removal starts or see a -// removed state after removal finishes; it cannot keep a pointer that was -// deleted in between. -func (s *Server) lockControlState(name string, beforeStateLock func()) *controlDriverState { - s.controlStateMu.Lock() - state := s.controlStateLocked(name) - if beforeStateLock != nil { - beforeStateLock() - } - state.mu.Lock() - s.controlStateMu.Unlock() - return state -} - -// tryLockExistingControlState locks a state that already exists without -// creating one for a driver that may have been removed concurrently, and -// without waiting: locked is false when another request holds the state. -// Lifecycle invalidation uses the same controlStateMu -> state.mu order. -func (s *Server) tryLockExistingControlState(name string) (state *controlDriverState, locked bool) { - s.controlStateMu.Lock() - defer s.controlStateMu.Unlock() - state = s.controlStates[name] - if state == nil { - return nil, false - } - return state, state.mu.TryLock() -} - -func (s *Server) armControlHoldLocked(name string, state *controlDriverState, control string, value any, generation uint64, d time.Duration) *controlHold { - s.clearControlHoldLocked(state) - now := time.Now() - hold := &controlHold{ - Control: control, - Value: value, - ExpiresAt: now.Add(d).UnixMilli(), - Generation: generation, - armedAt: now, - } - hold.timer = time.AfterFunc(d, func() { - if err := s.expireControlHold(name, state, hold); err != nil { - slog.Error("control hold expiry default failed; registry recovery gate remains active", "driver", name, "err", err) - } - }) - state.hold = hold - return hold -} - -func (s *Server) clearControlHoldLocked(state *controlDriverState) { - if state.hold != nil && state.hold.timer != nil { - state.hold.timer.Stop() - } - state.hold = nil -} - -// expireControlHold hands the device back to itself. It checks identity -// first: a hold that was replaced or released already had its timer stopped, -// but a timer that had begun firing cannot be stopped, and defaulting a -// driver that an operator has just set again is the one wrong answer here. -func (s *Server) expireControlHold(name string, state *controlDriverState, fired *controlHold) error { - state.mu.Lock() - defer state.mu.Unlock() - if state.hold != fired { - return nil - } +// controlRegistry is what the holds see of the registry. A nil +// *drivers.Registry must stay a nil interface, or the holds would call it. +func (s *Server) controlRegistry() drivercontrol.Registry { if s.deps == nil || s.deps.Registry == nil { - s.clearControlHoldLocked(state) - return errors.New("driver registry not available") - } - status, ok := s.deps.Registry.ControlStatus(name) - if !ok || status.Generation != fired.Generation { - // A stopped generation must never default a replacement instance. - s.clearControlHoldLocked(state) return nil } - s.clearControlHoldLocked(state) - ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) - defer cancel() - return s.sendDefaultLocked(ctx, name) + return s.deps.Registry } -// SendDriverDefault is the shared safety path for watchdogs and API release. -// It clears the operator hold while holding the same per-driver lock used by -// command dispatch, then sends the driver's own default with a bounded -// context. A caller without a deadline gets the 10-second safety deadline. -// -// The control tick calls this, so it never waits for an operator command in -// flight. When one holds the lock, the default goes first: SendDefault cancels -// that command and refuses new ones until the default is confirmed. The hold -// is cleared once the lock is free, but only a hold armed before the default -// returned. A later one belongs to a command sent after the default and keeps -// its own expiry. +// SendDriverDefault is the shared safety path for watchdogs and API release: +// it clears any hold under the per-driver lock and sends the driver's own +// default. See drivercontrol.Holds.SendDefault. func (s *Server) SendDriverDefault(ctx context.Context, name string) error { - if s.deps == nil || s.deps.Registry == nil { - return errors.New("driver registry not available") - } - if _, ok := s.deps.Registry.ControlStatus(name); !ok { - return fmt.Errorf("driver %q not found", name) - } - if s.beforeDriverDefaultStateLock != nil { - s.beforeDriverDefaultStateLock() - } - state, locked := s.tryLockExistingControlState(name) - if locked { - defer state.mu.Unlock() - s.clearControlHoldLocked(state) - return s.sendDefaultLocked(ctx, name) - } - err := s.sendDefaultLocked(ctx, name) - if state != nil { - defaulted := time.Now() - go func() { - state.mu.Lock() - defer state.mu.Unlock() - if state.hold != nil && !state.hold.armedAt.After(defaulted) { - s.clearControlHoldLocked(state) - } - }() - } - return err -} - -func (s *Server) sendDefaultLocked(ctx context.Context, name string) error { - if s.deps == nil || s.deps.Registry == nil { - return errors.New("driver registry not available") - } - if ctx == nil { - ctx = context.Background() - } - if _, ok := ctx.Deadline(); !ok { - var cancel context.CancelFunc - ctx, cancel = context.WithTimeout(ctx, controlDefaultTimeout) - defer cancel() - } - return s.deps.Registry.SendDefault(ctx, name) -} - -func (s *Server) activeControlHold(name string) *controlHold { - state := s.peekControlState(name) - if state == nil { - return nil - } - state.mu.Lock() - defer state.mu.Unlock() - if state.hold == nil { - return nil - } - if s.deps == nil || s.deps.Registry == nil { - s.clearControlHoldLocked(state) - return nil - } - status, ok := s.deps.Registry.ControlStatus(name) - if !ok || status.Generation != state.hold.Generation { - s.clearControlHoldLocked(state) - return nil - } - hold := *state.hold - hold.timer = nil - return &hold -} - -func (s *Server) peekControlState(name string) *controlDriverState { - s.controlStateMu.Lock() - state := s.controlStates[name] - s.controlStateMu.Unlock() - return state -} - -// clearDriverControl is called by Registry before a driver generation is -// removed. It stops the old timer and drops the map entry so a re-added driver -// cannot inherit an operator hold from the previous instance. -func (s *Server) clearDriverControl(name string) { - s.clearDriverControlState(name, nil) -} - -func (s *Server) clearDriverControlState(name string, expected *controlDriverState) { - s.controlStateMu.Lock() - defer s.controlStateMu.Unlock() - state := s.controlStates[name] - if expected != nil && state != expected { - return - } - if state == nil { - return - } - state.mu.Lock() - s.clearControlHoldLocked(state) - delete(s.controlStates, name) - state.mu.Unlock() + return s.controlHolds.SendDefault(ctx, name, s.beforeDriverDefaultStateLock) } diff --git a/go/internal/api/api_driver_control_test.go b/go/internal/api/api_driver_control_test.go index 45ec4194b..e96d26547 100644 --- a/go/internal/api/api_driver_control_test.go +++ b/go/internal/api/api_driver_control_test.go @@ -364,7 +364,7 @@ func TestDriverControlPreservesDeclaredBooleanAndStringValues(t *testing.T) { t.Fatalf("boolean POST = %d, body %s", rec.Code, rec.Body.String()) } waitMetric(t, tel, "heat", "applied", 1) - if hold := srv.activeControlHold("heat"); hold == nil || hold.Value != true { + if hold := srv.controlHolds.Active("heat"); hold == nil || hold.Value != true { t.Fatalf("boolean hold = %+v, want true", hold) } @@ -373,7 +373,7 @@ func TestDriverControlPreservesDeclaredBooleanAndStringValues(t *testing.T) { t.Fatalf("string POST = %d, body %s", rec.Code, rec.Body.String()) } waitMetric(t, tel, "heat", "applied", 3) - if hold := srv.activeControlHold("heat"); hold == nil || hold.Value != "eco" { + if hold := srv.controlHolds.Active("heat"); hold == nil || hold.Value != "eco" { t.Fatalf("string hold = %+v, want eco", hold) } } @@ -409,7 +409,7 @@ func TestDriverControlHoldIsVisibleAndReleasable(t *testing.T) { // Releasing calls the driver's own default mode, not a value this // package invented. waitMetric(t, tel, "heat", "defaulted", 1) - if hold := srv.activeControlHold("heat"); hold != nil { + if hold := srv.controlHolds.Active("heat"); hold != nil { t.Errorf("hold survived release: %+v", hold) } } @@ -425,7 +425,7 @@ func TestDriverControlHoldExpiresIntoDefault(t *testing.T) { } waitMetric(t, tel, "heat", "applied", 2) waitMetric(t, tel, "heat", "defaulted", 1) - if hold := srv.activeControlHold("heat"); hold != nil { + if hold := srv.controlHolds.Active("heat"); hold != nil { t.Errorf("hold survived expiry: %+v", hold) } } @@ -485,7 +485,7 @@ func TestDriverControlBindsHoldToRestartedGeneration(t *testing.T) { t.Fatalf("POST after restart race = %d, body %s", rec.Code, rec.Body.String()) } waitMetric(t, tel, "heat", "applied", 2) - hold := srv.activeControlHold("heat") + hold := srv.controlHolds.Active("heat") if hold == nil { t.Fatal("control request did not create a hold") } @@ -493,19 +493,17 @@ func TestDriverControlBindsHoldToRestartedGeneration(t *testing.T) { t.Fatalf("hold generation = %d, want replacement generation %d", hold.Generation, newStatus.Generation) } - state := srv.peekControlState("heat") + state := srv.controlHolds.Peek("heat") if state == nil { t.Fatal("control state disappeared before expiry") } - state.mu.Lock() - fired := state.hold - state.mu.Unlock() - if err := srv.expireControlHold("heat", state, fired); err != nil { + fired := state.CurrentHold() + if err := srv.controlHolds.Expire("heat", state, fired); err != nil { t.Fatalf("expiry after generation-bound command = %v", err) } waitMetric(t, tel, "heat", "defaulted", 1) waitMetric(t, tel, "heat", "applied", 0) - if got := srv.activeControlHold("heat"); got != nil { + if got := srv.controlHolds.Active("heat"); got != nil { t.Fatalf("hold survived successful expiry: %+v", got) } } @@ -568,7 +566,7 @@ func TestDriverControlLookupRaceCannotOrphanStateOrTimer(t *testing.T) { lifecycleDone := make(chan error, 1) go func() { lifecycleDone <- test.lifecycle(srv, cfg) }() mapProbeDone := make(chan bool, 1) - go func() { mapProbeDone <- srv.peekControlState("heat") == nil }() + go func() { mapProbeDone <- srv.controlHolds.Peek("heat") == nil }() select { case removed := <-mapProbeDone: if removed { @@ -596,7 +594,7 @@ func TestDriverControlLookupRaceCannotOrphanStateOrTimer(t *testing.T) { t.Fatal("lifecycle deadlocked after the request released state.mu") } - if got := srv.activeControlHold("heat"); got != nil { + if got := srv.controlHolds.Active("heat"); got != nil { t.Fatalf("%s left an orphaned hold: %+v", test.name, got) } if got := driverDetail(t, srv, "heat"); got.Hold != nil { @@ -637,21 +635,19 @@ func TestDriverControlExpiryDefaultFailureBlocksUntilRecovery(t *testing.T) { `{"control":"set_offset","value":2,"duration_s":600}`); rec.Code != http.StatusOK { t.Fatalf("POST = %d, body %s", rec.Code, rec.Body.String()) } - state := srv.peekControlState("heat") + state := srv.controlHolds.Peek("heat") if state == nil { t.Fatal("missing control state") } - state.mu.Lock() - hold := state.hold - state.mu.Unlock() + hold := state.CurrentHold() if hold == nil { t.Fatal("missing control hold") } - if err := srv.expireControlHold("heat", state, hold); err == nil { + if err := srv.controlHolds.Expire("heat", state, hold); err == nil { t.Fatal("expiry hid a failed default") } - if got := srv.activeControlHold("heat"); got != nil { + if got := srv.controlHolds.Active("heat"); got != nil { t.Fatalf("failed expiry left hold active: %+v", got) } status, ok := srv.deps.Registry.ControlStatus("heat") @@ -735,7 +731,7 @@ func TestDriverControlAmbiguousCommandRestoresDefault(t *testing.T) { t.Fatalf("ambiguous POST = %d, body %s", rec.Code, rec.Body.String()) } waitMetric(t, tel, "heat", "defaulted", 1) - if hold := srv.activeControlHold("heat"); hold != nil { + if hold := srv.controlHolds.Active("heat"); hold != nil { t.Fatalf("ambiguous command left hold active: %+v", hold) } waitMetric(t, tel, "heat", "applied", 0) @@ -751,10 +747,10 @@ func TestDriverControlDefaultPathClearsHold(t *testing.T) { if err := srv.SendDriverDefault(context.Background(), "heat"); err != nil { t.Fatalf("SendDriverDefault = %v", err) } - if hold := srv.activeControlHold("heat"); hold != nil { + if hold := srv.controlHolds.Active("heat"); hold != nil { t.Fatalf("default path left hold active: %+v", hold) } - if state := srv.peekControlState("heat"); state == nil { + if state := srv.controlHolds.Peek("heat"); state == nil { t.Fatal("default path removed the existing control state") } waitMetric(t, tel, "heat", "defaulted", 1) @@ -834,7 +830,7 @@ func TestSendDriverDefaultDoesNotWaitForAnOperatorCommand(t *testing.T) { case <-time.After(3 * time.Second): t.Fatal("operator command did not return after the default cancelled it") } - if hold := srv.activeControlHold("heat"); hold != nil { + if hold := srv.controlHolds.Active("heat"); hold != nil { t.Fatalf("hold survived the safety default: %+v", hold) } } @@ -857,31 +853,31 @@ func TestSendDriverDefaultClearsOnlyHoldsArmedBeforeIt(t *testing.T) { if !ok { t.Fatal("driver not running") } - state := srv.controlState("heat") - state.mu.Lock() // an operator request in flight + state := srv.controlHolds.State("heat") + state.Lock() // an operator request in flight if tc.armBefore { - srv.armControlHoldLocked("heat", state, "set_offset", 1.0, status.Generation, time.Hour) + srv.controlHolds.ArmLocked("heat", state, "set_offset", 1.0, status.Generation, time.Hour) } done := make(chan error, 1) go func() { done <- srv.SendDriverDefault(context.Background(), "heat") }() select { case err := <-done: if err != nil { - state.mu.Unlock() + state.Unlock() t.Fatalf("SendDriverDefault = %v", err) } case <-time.After(time.Second): - state.mu.Unlock() + state.Unlock() t.Fatal("SendDriverDefault waited for the operator request") } if !tc.armBefore { - srv.armControlHoldLocked("heat", state, "set_offset", 2.0, status.Generation, time.Hour) + srv.controlHolds.ArmLocked("heat", state, "set_offset", 2.0, status.Generation, time.Hour) } - state.mu.Unlock() + state.Unlock() if tc.wantCleared { deadline := time.Now().Add(time.Second) - for srv.activeControlHold("heat") != nil { + for srv.controlHolds.Active("heat") != nil { if time.Now().After(deadline) { t.Fatal("hold armed before the default survived it") } @@ -891,7 +887,7 @@ func TestSendDriverDefaultClearsOnlyHoldsArmedBeforeIt(t *testing.T) { } // Give the deferred clear time to take the lock and decide. time.Sleep(200 * time.Millisecond) - if srv.activeControlHold("heat") == nil { + if srv.controlHolds.Active("heat") == nil { t.Fatal("default cleared a hold armed after it; that command would never expire") } }) @@ -900,7 +896,7 @@ func TestSendDriverDefaultClearsOnlyHoldsArmedBeforeIt(t *testing.T) { func TestSendDriverDefaultDoesNotRecreateStateAfterRemove(t *testing.T) { srv, _ := controlServer(t) - srv.controlState("heat") + srv.controlHolds.State("heat") paused := make(chan struct{}) resume := make(chan struct{}) @@ -930,7 +926,7 @@ func TestSendDriverDefaultDoesNotRecreateStateAfterRemove(t *testing.T) { close(resume) t.Fatal("RemoveProbe deadlocked behind SendDriverDefault") } - if state := srv.peekControlState("heat"); state != nil { + if state := srv.controlHolds.Peek("heat"); state != nil { t.Fatalf("removed driver still has control state before default resumes: %p", state) } close(resume) @@ -943,14 +939,14 @@ func TestSendDriverDefaultDoesNotRecreateStateAfterRemove(t *testing.T) { case <-time.After(time.Second): t.Fatal("SendDriverDefault did not finish after lifecycle removal") } - if state := srv.peekControlState("heat"); state != nil { + if state := srv.controlHolds.Peek("heat"); state != nil { t.Fatalf("default path recreated removed control state: %p", state) } } func TestSendDriverDefaultDoesNotAccumulateRemovedStates(t *testing.T) { srv, _ := controlServer(t) - srv.controlState("heat") + srv.controlHolds.State("heat") base := srv.deps.Cfg.Drivers[0] for i := 0; i < 64; i++ { @@ -960,7 +956,7 @@ func TestSendDriverDefaultDoesNotAccumulateRemovedStates(t *testing.T) { if err := srv.deps.Registry.Add(context.Background(), cfg); err != nil { t.Fatalf("add %s: %v", name, err) } - srv.controlState(name) + srv.controlHolds.State(name) paused := make(chan struct{}) resume := make(chan struct{}) @@ -989,14 +985,12 @@ func TestSendDriverDefaultDoesNotAccumulateRemovedStates(t *testing.T) { t.Fatalf("SendDriverDefault(%s) did not finish", name) } srv.beforeDriverDefaultStateLock = nil - if state := srv.peekControlState(name); state != nil { + if state := srv.controlHolds.Peek(name); state != nil { t.Fatalf("removed driver %s left a control state", name) } } - srv.controlStateMu.Lock() - defer srv.controlStateMu.Unlock() - if got := len(srv.controlStates); got != 1 { + if got := srv.controlHolds.Len(); got != 1 { t.Fatalf("control state map has %d entries after removed names, want only heat", got) } } @@ -1011,17 +1005,15 @@ func TestDriverControlSerializesExpiryAndReplacement(t *testing.T) { `{"control":"set_offset","value":1,"duration_s":600}`); rec.Code != http.StatusOK { t.Fatalf("POST = %d, body %s", rec.Code, rec.Body.String()) } - state := srv.controlState("heat") - state.mu.Lock() - hold := state.hold - state.mu.Unlock() + state := srv.controlHolds.State("heat") + hold := state.CurrentHold() if hold == nil { t.Fatal("missing hold") } done := make(chan struct{}) go func() { - srv.expireControlHold("heat", state, hold) + srv.controlHolds.Expire("heat", state, hold) close(done) }() waitMetric(t, tel, "heat", "default_started", 1) @@ -1124,13 +1116,11 @@ func TestDriverControlClearsHoldAcrossLifecycle(t *testing.T) { t.Fatalf("initial POST = %d, body %s", rec.Code, rec.Body.String()) } waitMetric(t, tel, "heat", "applied", 2) - oldState := srv.peekControlState("heat") + oldState := srv.controlHolds.Peek("heat") if oldState == nil { t.Fatal("initial control state is missing") } - oldState.mu.Lock() - oldHold := oldState.hold - oldState.mu.Unlock() + oldHold := oldState.CurrentHold() if oldHold == nil { t.Fatal("initial control hold is missing") } @@ -1138,10 +1128,10 @@ func TestDriverControlClearsHoldAcrossLifecycle(t *testing.T) { if err := srv.deps.Registry.Restart(context.Background(), cfg); err != nil { t.Fatalf("restart = %v", err) } - if got := srv.activeControlHold("heat"); got != nil { + if got := srv.controlHolds.Active("heat"); got != nil { t.Fatalf("hold survived restart: %+v", got) } - if got := srv.peekControlState("heat"); got != nil { + if got := srv.controlHolds.Peek("heat"); got != nil { t.Fatal("control state map entry survived restart") } if got := driverDetail(t, srv, "heat"); got.Hold != nil { @@ -1156,7 +1146,7 @@ func TestDriverControlClearsHoldAcrossLifecycle(t *testing.T) { waitMetric(t, tel, "heat", "applied", -2) // Simulate a timer callback that was already in flight when the old // generation was removed. It must not default the new instance. - srv.expireControlHold("heat", oldState, oldHold) + srv.controlHolds.Expire("heat", oldState, oldHold) time.Sleep(250 * time.Millisecond) if got, _, ok := tel.LatestMetric("heat", "defaulted"); !ok || got != 0 { t.Fatalf("old timer changed the replacement: defaulted=%v/%v", got, ok) @@ -1168,7 +1158,7 @@ func TestDriverControlClearsHoldAcrossLifecycle(t *testing.T) { disabled := cfg disabled.Disabled = true srv.deps.Registry.Reload(context.Background(), []config.Driver{disabled}, false) - if got := srv.peekControlState("heat"); got != nil { + if got := srv.controlHolds.Peek("heat"); got != nil { t.Fatal("control state map entry survived disable") } if got := driverDetail(t, srv, "heat"); got.Hold != nil { @@ -1176,7 +1166,7 @@ func TestDriverControlClearsHoldAcrossLifecycle(t *testing.T) { } srv.deps.Registry.Reload(context.Background(), []config.Driver{cfg}, false) - if got := srv.peekControlState("heat"); got != nil { + if got := srv.controlHolds.Peek("heat"); got != nil { t.Fatal("control state map entry survived re-add") } if got := driverDetail(t, srv, "heat"); got.Hold != nil { @@ -1194,9 +1184,7 @@ func TestDriverDetailUnknownNamesDoNotCreateControlState(t *testing.T) { t.Fatalf("GET %s = %d, body %s", name, rec.Code, rec.Body.String()) } } - srv.controlStateMu.Lock() - defer srv.controlStateMu.Unlock() - if got := len(srv.controlStates); got != 0 { + if got := srv.controlHolds.Len(); got != 0 { t.Fatalf("unknown GETs created %d control states", got) } } diff --git a/go/internal/api/api_driver_thermal_test.go b/go/internal/api/api_driver_thermal_test.go index d9e9b2707..9fd5bfb35 100644 --- a/go/internal/api/api_driver_thermal_test.go +++ b/go/internal/api/api_driver_thermal_test.go @@ -59,7 +59,7 @@ func TestDriverControlRefusesValueOutsideDeclaredOptions(t *testing.T) { if rec.Code != http.StatusBadRequest { t.Fatalf("undeclared option = %d, want 400 (body %s)", rec.Code, rec.Body.String()) } - if hold := srv.activeControlHold("heat"); hold != nil { + if hold := srv.controlHolds.Active("heat"); hold != nil { t.Fatalf("hold = %+v after a refused value, want none", hold) } // Give the driver a few polls; a refused value must not have been sent. diff --git a/go/internal/api/api_drivers_debug.go b/go/internal/api/api_drivers_debug.go index 5f5608bc0..ab79148c9 100644 --- a/go/internal/api/api_drivers_debug.go +++ b/go/internal/api/api_drivers_debug.go @@ -26,6 +26,7 @@ import ( "time" "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivercontrol" "github.com/srcfl/ftw/go/internal/drivers" "github.com/srcfl/ftw/go/internal/telemetry" ) @@ -46,7 +47,7 @@ type driverDetailResp struct { // temperature. Absent for every driver that declares none. Sensors []drivers.CatalogSensor `json:"sensors,omitempty"` // Hold is the operator setting in force, if any, and when it ends. - Hold *controlHold `json:"hold,omitempty"` + Hold *drivercontrol.Hold `json:"hold,omitempty"` // ControlState says whether Core has confirmed autonomous default mode. // It must not call a failed default safe or settled. ControlState driverControlStateResp `json:"control_state"` @@ -128,12 +129,12 @@ func (s *Server) handleDriverDetail(w http.ResponseWriter, r *http.Request) { resp.Controls = entry.Controls resp.Sensors = entry.Sensors } - resp.Hold = s.activeControlHold(name) + resp.Hold = s.controlHolds.Active(name) resp.ControlState = s.driverControlState(name, resp.Hold) writeJSON(w, 200, resp) } -func (s *Server) driverControlState(name string, hold *controlHold) driverControlStateResp { +func (s *Server) driverControlState(name string, hold *drivercontrol.Hold) driverControlStateResp { if s.deps == nil || s.deps.Registry == nil { return driverControlStateResp{State: "unknown"} } diff --git a/go/internal/drivercontrol/holds.go b/go/internal/drivercontrol/holds.go new file mode 100644 index 000000000..c4c572719 --- /dev/null +++ b/go/internal/drivercontrol/holds.go @@ -0,0 +1,360 @@ +// Package drivercontrol owns what is held on a driver: one bounded value at a +// time, sent and released under one per-driver lock, and handed back to the +// device's own default when it ends. +// +// It moved here from the API package unchanged so that more than one caller +// can share it. An operator's hold and, later, a planned value must go +// through the same lock and the same expiry, or each would expire into a +// default that undoes the other (docs/adr/0012). +// +// Holds are process-lifetime only, deliberately: a restart should leave no +// device held by a setting nobody remembers making. +package drivercontrol + +import ( + "context" + "errors" + "fmt" + "log/slog" + "sync" + "time" + + "github.com/srcfl/ftw/go/internal/drivers" +) + +// DefaultTimeout bounds a default sent without a caller deadline, and a +// command sent while the per-driver lock is held. +const DefaultTimeout = 10 * time.Second + +// Registry is the part of drivers.Registry holds need. +type Registry interface { + SendWithGeneration(ctx context.Context, name string, payload []byte) (uint64, error) + ControlStatus(name string) (drivers.DriverControlStatus, bool) + SendDefault(ctx context.Context, name string) error +} + +// Hold is one active setting. The timer is what releases it; the fields are +// what the UI shows meanwhile. +type Hold struct { + Control string `json:"control"` + Value any `json:"value,omitempty"` + ExpiresAt int64 `json:"expires_at_ms"` + Generation uint64 `json:"-"` + + armedAt time.Time + timer *time.Timer +} + +// State serializes command dispatch, default dispatch and hold transitions +// for one driver. +type State struct { + mu sync.Mutex + hold *Hold +} + +// Lock takes the per-driver lock. Exported for tests that stand in for a +// command in flight; production callers use Holds' methods. +func (st *State) Lock() { st.mu.Lock() } + +// Unlock releases the per-driver lock. +func (st *State) Unlock() { st.mu.Unlock() } + +// CurrentHold returns the held setting itself, not a copy, or nil. Its +// identity is what Expire compares. +func (st *State) CurrentHold() *Hold { + st.mu.Lock() + defer st.mu.Unlock() + return st.hold +} + +// Holds is every driver's State. +type Holds struct { + registry func() Registry + + mu sync.Mutex + states map[string]*State +} + +// New returns empty holds. registry is read at each use, so a caller whose +// registry is absent gets the same answers it did before this package +// existed. +func New(registry func() Registry) *Holds { + return &Holds{registry: registry, states: make(map[string]*State)} +} + +func (h *Holds) reg() Registry { + if h.registry == nil { + return nil + } + return h.registry() +} + +// Send dispatches body to the driver and holds controlID at value for d. +// The send and the hold transition happen under one per-driver lock, and the +// device call has a deadline because hold expiry waits on that lock. On error +// any existing hold is cleared and nothing is armed. +// +// done runs with the outcome while the lock is still held, so a caller that +// reads registry status to explain an error sees it before any lifecycle +// change waiting on this driver can proceed. +// +// beforeStateLock is a test seam, run after the state lookup and before the +// per-driver lock; nil in production. +func (h *Holds) Send(ctx context.Context, name, controlID string, value any, body []byte, d time.Duration, beforeStateLock func(), done func(Hold, error)) { + reg := h.reg() + if reg == nil { + done(Hold{}, errors.New("driver registry not available")) + return + } + // Keep command dispatch and hold transitions under one per-driver lock. + // Registry.SendWithGeneration selects the concrete running instance and + // returns its generation, so expiry can never pair a new command with an + // old status snapshot. The state lookup and lock are also one lifecycle + // transaction: clearState takes the same locks in the same order, so it + // cannot remove the map entry between these operations. + state := h.lock(name, beforeStateLock) + defer state.mu.Unlock() + sendCtx, cancel := context.WithTimeout(ctx, DefaultTimeout) + defer cancel() + generation, err := reg.SendWithGeneration(sendCtx, name, body) + if err != nil { + h.clearLocked(state) + done(Hold{}, err) + return + } + hold := h.ArmLocked(name, state, controlID, value, generation, d) + out := *hold + out.timer = nil + done(out, nil) +} + +// State returns the driver's state, creating it. +func (h *Holds) State(name string) *State { + h.mu.Lock() + defer h.mu.Unlock() + return h.stateLocked(name) +} + +func (h *Holds) stateLocked(name string) *State { + if h.states == nil { + h.states = make(map[string]*State) + } + state := h.states[name] + if state == nil { + state = &State{} + h.states[name] = state + } + return state +} + +// lock serializes a state map lookup with acquisition of that driver's +// mutex. Lifecycle invalidation uses h.mu -> state.mu as well, so a request +// can either own the state before removal starts or see a removed state +// after removal finishes; it cannot keep a pointer that was deleted in +// between. +func (h *Holds) lock(name string, beforeStateLock func()) *State { + h.mu.Lock() + state := h.stateLocked(name) + if beforeStateLock != nil { + beforeStateLock() + } + state.mu.Lock() + h.mu.Unlock() + return state +} + +// tryLockExisting locks a state that already exists without creating one +// for a driver that may have been removed concurrently, and without waiting: +// locked is false when another request holds the state. Lifecycle +// invalidation uses the same h.mu -> state.mu order. +func (h *Holds) tryLockExisting(name string) (state *State, locked bool) { + h.mu.Lock() + defer h.mu.Unlock() + state = h.states[name] + if state == nil { + return nil, false + } + return state, state.mu.TryLock() +} + +// ArmLocked replaces any existing hold for the driver; the caller holds +// state's lock. One driver holds one control at a time: two overlapping +// holds on the same device would each expire into a default that undoes the +// other. +func (h *Holds) ArmLocked(name string, state *State, control string, value any, generation uint64, d time.Duration) *Hold { + h.clearLocked(state) + now := time.Now() + hold := &Hold{ + Control: control, + Value: value, + ExpiresAt: now.Add(d).UnixMilli(), + Generation: generation, + armedAt: now, + } + hold.timer = time.AfterFunc(d, func() { + if err := h.Expire(name, state, hold); err != nil { + slog.Error("control hold expiry default failed; registry recovery gate remains active", "driver", name, "err", err) + } + }) + state.hold = hold + return hold +} + +func (h *Holds) clearLocked(state *State) { + if state.hold != nil && state.hold.timer != nil { + state.hold.timer.Stop() + } + state.hold = nil +} + +// Expire hands the device back to itself. It checks identity first: a hold +// that was replaced or released already had its timer stopped, but a timer +// that had begun firing cannot be stopped, and defaulting a driver that an +// operator has just set again is the one wrong answer here. +func (h *Holds) Expire(name string, state *State, fired *Hold) error { + state.mu.Lock() + defer state.mu.Unlock() + if state.hold != fired { + return nil + } + reg := h.reg() + if reg == nil { + h.clearLocked(state) + return errors.New("driver registry not available") + } + status, ok := reg.ControlStatus(name) + if !ok || status.Generation != fired.Generation { + // A stopped generation must never default a replacement instance. + h.clearLocked(state) + return nil + } + h.clearLocked(state) + ctx, cancel := context.WithTimeout(context.Background(), DefaultTimeout) + defer cancel() + return h.sendDefaultLocked(ctx, name) +} + +// SendDefault is the shared safety path for watchdogs and release. It clears +// the hold while holding the same per-driver lock used by command dispatch, +// then sends the driver's own default with a bounded context. A caller +// without a deadline gets the 10-second safety deadline. +// +// The control tick calls this, so it never waits for a command in flight. +// When one holds the lock, the default goes first: SendDefault cancels that +// command and refuses new ones until the default is confirmed. The hold is +// cleared once the lock is free, but only a hold armed before the default +// returned. A later one belongs to a command sent after the default and +// keeps its own expiry. +// +// beforeDefaultStateLock is a test seam; nil in production. +func (h *Holds) SendDefault(ctx context.Context, name string, beforeDefaultStateLock func()) error { + reg := h.reg() + if reg == nil { + return errors.New("driver registry not available") + } + if _, ok := reg.ControlStatus(name); !ok { + return fmt.Errorf("driver %q not found", name) + } + if beforeDefaultStateLock != nil { + beforeDefaultStateLock() + } + state, locked := h.tryLockExisting(name) + if locked { + defer state.mu.Unlock() + h.clearLocked(state) + return h.sendDefaultLocked(ctx, name) + } + err := h.sendDefaultLocked(ctx, name) + if state != nil { + defaulted := time.Now() + go func() { + state.mu.Lock() + defer state.mu.Unlock() + if state.hold != nil && !state.hold.armedAt.After(defaulted) { + h.clearLocked(state) + } + }() + } + return err +} + +func (h *Holds) sendDefaultLocked(ctx context.Context, name string) error { + reg := h.reg() + if reg == nil { + return errors.New("driver registry not available") + } + if ctx == nil { + ctx = context.Background() + } + if _, ok := ctx.Deadline(); !ok { + var cancel context.CancelFunc + ctx, cancel = context.WithTimeout(ctx, DefaultTimeout) + defer cancel() + } + return reg.SendDefault(ctx, name) +} + +// Active returns a copy of the driver's hold, or nil. A hold bound to a +// generation that is no longer running is cleared, not returned. +func (h *Holds) Active(name string) *Hold { + state := h.Peek(name) + if state == nil { + return nil + } + state.mu.Lock() + defer state.mu.Unlock() + if state.hold == nil { + return nil + } + reg := h.reg() + if reg == nil { + h.clearLocked(state) + return nil + } + status, ok := reg.ControlStatus(name) + if !ok || status.Generation != state.hold.Generation { + h.clearLocked(state) + return nil + } + hold := *state.hold + hold.timer = nil + return &hold +} + +// Peek returns the driver's state without creating one. +func (h *Holds) Peek(name string) *State { + h.mu.Lock() + state := h.states[name] + h.mu.Unlock() + return state +} + +// Len is how many drivers have state. For tests of lifecycle cleanup. +func (h *Holds) Len() int { + h.mu.Lock() + defer h.mu.Unlock() + return len(h.states) +} + +// Clear is called by the registry before a driver generation is removed. It +// stops the old timer and drops the map entry so a re-added driver cannot +// inherit a hold from the previous instance. +func (h *Holds) Clear(name string) { + h.clearState(name, nil) +} + +func (h *Holds) clearState(name string, expected *State) { + h.mu.Lock() + defer h.mu.Unlock() + state := h.states[name] + if expected != nil && state != expected { + return + } + if state == nil { + return + } + state.mu.Lock() + h.clearLocked(state) + delete(h.states, name) + state.mu.Unlock() +} diff --git a/go/internal/drivercontrol/holds_test.go b/go/internal/drivercontrol/holds_test.go new file mode 100644 index 000000000..4c6654911 --- /dev/null +++ b/go/internal/drivercontrol/holds_test.go @@ -0,0 +1,213 @@ +package drivercontrol + +import ( + "context" + "errors" + "sync" + "testing" + "time" + + "github.com/srcfl/ftw/go/internal/drivers" +) + +type fakeRegistry struct { + mu sync.Mutex + generation uint64 + running bool + sendErr error + sent int + defaults int +} + +func (f *fakeRegistry) SendWithGeneration(_ context.Context, _ string, _ []byte) (uint64, error) { + f.mu.Lock() + defer f.mu.Unlock() + if f.sendErr != nil { + return 0, f.sendErr + } + f.sent++ + return f.generation, nil +} + +func (f *fakeRegistry) ControlStatus(string) (drivers.DriverControlStatus, bool) { + f.mu.Lock() + defer f.mu.Unlock() + return drivers.DriverControlStatus{Generation: f.generation}, f.running +} + +func (f *fakeRegistry) SendDefault(context.Context, string) error { + f.mu.Lock() + defer f.mu.Unlock() + f.defaults++ + return nil +} + +func (f *fakeRegistry) counts() (sent, defaults int) { + f.mu.Lock() + defer f.mu.Unlock() + return f.sent, f.defaults +} + +func newHolds(reg *fakeRegistry) *Holds { + return New(func() Registry { return reg }) +} + +func send(t *testing.T, h *Holds, value any, d time.Duration) (Hold, error) { + t.Helper() + var hold Hold + var err error + h.Send(context.Background(), "heat", "set_offset", value, []byte(`{}`), d, nil, func(got Hold, e error) { + hold, err = got, e + }) + return hold, err +} + +func TestSendArmsAHoldBoundToTheGeneration(t *testing.T) { + reg := &fakeRegistry{generation: 7, running: true} + h := newHolds(reg) + hold, err := send(t, h, 2.0, time.Hour) + if err != nil { + t.Fatal(err) + } + if hold.Generation != 7 || hold.Control != "set_offset" || hold.Value != 2.0 { + t.Fatalf("hold = %+v", hold) + } + if got := h.Active("heat"); got == nil || got.Generation != 7 { + t.Fatalf("Active = %+v", got) + } +} + +func TestFailedSendClearsTheOldHold(t *testing.T) { + reg := &fakeRegistry{generation: 1, running: true} + h := newHolds(reg) + if _, err := send(t, h, 1.0, time.Hour); err != nil { + t.Fatal(err) + } + reg.mu.Lock() + reg.sendErr = errors.New("device gone") + reg.mu.Unlock() + if _, err := send(t, h, 2.0, time.Hour); err == nil { + t.Fatal("send error hidden") + } + if got := h.Active("heat"); got != nil { + t.Fatalf("failed send left hold %+v", got) + } +} + +func TestExpirySendsTheDefault(t *testing.T) { + reg := &fakeRegistry{generation: 1, running: true} + h := newHolds(reg) + if _, err := send(t, h, 1.0, 20*time.Millisecond); err != nil { + t.Fatal(err) + } + deadline := time.Now().Add(2 * time.Second) + for time.Now().Before(deadline) { + if _, d := reg.counts(); d == 1 { + break + } + time.Sleep(5 * time.Millisecond) + } + if _, d := reg.counts(); d != 1 { + t.Fatalf("defaults after expiry = %d, want 1", d) + } + if got := h.Active("heat"); got != nil { + t.Fatalf("hold survived expiry: %+v", got) + } +} + +// A stopped generation must never default its replacement. +func TestExpiryOfAnOldGenerationSendsNoDefault(t *testing.T) { + reg := &fakeRegistry{generation: 1, running: true} + h := newHolds(reg) + if _, err := send(t, h, 1.0, time.Hour); err != nil { + t.Fatal(err) + } + state := h.Peek("heat") + fired := state.CurrentHold() + reg.mu.Lock() + reg.generation = 2 + reg.mu.Unlock() + if err := h.Expire("heat", state, fired); err != nil { + t.Fatal(err) + } + if _, d := reg.counts(); d != 0 { + t.Fatalf("old generation sent %d defaults", d) + } +} + +// A replaced hold's timer must not default the new one. +func TestExpiryOfAReplacedHoldIsANoOp(t *testing.T) { + reg := &fakeRegistry{generation: 1, running: true} + h := newHolds(reg) + if _, err := send(t, h, 1.0, time.Hour); err != nil { + t.Fatal(err) + } + state := h.Peek("heat") + old := state.CurrentHold() + if _, err := send(t, h, 2.0, time.Hour); err != nil { + t.Fatal(err) + } + if err := h.Expire("heat", state, old); err != nil { + t.Fatal(err) + } + if _, d := reg.counts(); d != 0 { + t.Fatalf("replaced hold sent %d defaults", d) + } + if got := h.Active("heat"); got == nil || got.Value != 2.0 { + t.Fatalf("Active = %+v, want the replacement", got) + } +} + +func TestSendDefaultClearsTheHold(t *testing.T) { + reg := &fakeRegistry{generation: 1, running: true} + h := newHolds(reg) + if _, err := send(t, h, 1.0, time.Hour); err != nil { + t.Fatal(err) + } + if err := h.SendDefault(context.Background(), "heat", nil); err != nil { + t.Fatal(err) + } + if _, d := reg.counts(); d != 1 { + t.Fatalf("defaults = %d, want 1", d) + } + if got := h.Active("heat"); got != nil { + t.Fatalf("hold survived default: %+v", got) + } +} + +func TestSendDefaultForAnUnknownDriverFails(t *testing.T) { + h := newHolds(&fakeRegistry{}) + if err := h.SendDefault(context.Background(), "heat", nil); err == nil { + t.Fatal("default to a driver that is not running succeeded") + } +} + +func TestClearDropsStateAndTimer(t *testing.T) { + reg := &fakeRegistry{generation: 1, running: true} + h := newHolds(reg) + if _, err := send(t, h, 1.0, 20*time.Millisecond); err != nil { + t.Fatal(err) + } + h.Clear("heat") + if h.Len() != 0 || h.Peek("heat") != nil { + t.Fatalf("Clear left state: len=%d", h.Len()) + } + time.Sleep(60 * time.Millisecond) + if _, d := reg.counts(); d != 0 { + t.Fatalf("cleared hold's timer sent %d defaults", d) + } +} + +// Without a registry nothing is sent and nothing is held. +func TestNoRegistry(t *testing.T) { + h := New(func() Registry { return nil }) + if _, err := send(t, h, 1.0, time.Hour); err == nil { + t.Fatal("send without a registry succeeded") + } + if err := h.SendDefault(context.Background(), "heat", nil); err == nil { + t.Fatal("default without a registry succeeded") + } + if h.Active("heat") != nil { + t.Fatal("hold without a registry") + } +} diff --git a/go/internal/drivers/catalog_thermal.go b/go/internal/drivers/catalog_thermal.go index 815afaff6..2487f9d6a 100644 --- a/go/internal/drivers/catalog_thermal.go +++ b/go/internal/drivers/catalog_thermal.go @@ -42,8 +42,7 @@ type CatalogSensor struct { Zone string `json:"zone,omitempty"` } -// The strategies a control may declare. synthetic_price is a signal Core -// would publish, not a lever a driver offers, so it is not one of them. +// The strategies a control may declare, and the input type each needs. var controlStrategyInput = map[thermal.InfluenceStrategy]string{ thermal.InfluenceCurveOffset: "number", thermal.InfluenceSetpoint: "number", diff --git a/go/internal/thermal/model.go b/go/internal/thermal/model.go index b5eb71cde..223e76a75 100644 --- a/go/internal/thermal/model.go +++ b/go/internal/thermal/model.go @@ -1,9 +1,9 @@ -// Package thermal defines the site-level contract for heat pumps, cooling, -// domestic hot water, and thermal buffers. +// Package thermal is the vocabulary heat controls are declared in: which heat +// store an asset is, and which lever a driver offers on it. It holds no +// policy. What a planner proposes and what Core accepts are in +// docs/adr/0012-heat-control.md. package thermal -import "math" - // AssetKind identifies which thermal store an asset represents. type AssetKind string @@ -18,10 +18,9 @@ const ( type InfluenceStrategy string const ( - InfluenceSyntheticPrice InfluenceStrategy = "synthetic_price" - InfluenceCurveOffset InfluenceStrategy = "curve_offset" - InfluenceSetpoint InfluenceStrategy = "setpoint" - InfluenceDiscreteMode InfluenceStrategy = "discrete_mode" + InfluenceCurveOffset InfluenceStrategy = "curve_offset" + InfluenceSetpoint InfluenceStrategy = "setpoint" + InfluenceDiscreteMode InfluenceStrategy = "discrete_mode" // InfluenceOnOff is a device whose only lever is start and stop. InfluenceOnOff InfluenceStrategy = "on_off" ) @@ -34,175 +33,3 @@ func ValidAssetKind(k AssetKind) bool { } return false } - -// IntentKind is planner intent before the driver maps it to vendor commands. -type IntentKind string - -const ( - IntentNeutral IntentKind = "neutral" - IntentPrecondition IntentKind = "precondition" - IntentShed IntentKind = "shed" - IntentProtectComfort IntentKind = "protect_comfort" - IntentBoostDHW IntentKind = "boost_dhw" -) - -// TemperatureBand is a hard min/max envelope with an optional normal target. -type TemperatureBand struct { - MinC float64 - NormalC float64 - MaxC float64 -} - -// Contains reports whether temp is within the hard envelope. -func (b TemperatureBand) Contains(tempC float64) bool { - return finite(tempC) && tempC >= b.MinC && tempC <= b.MaxC -} - -// WarmHeadroomC returns degrees available before hitting the max bound. -func (b TemperatureBand) WarmHeadroomC(tempC float64) float64 { - if !finite(tempC) || tempC >= b.MaxC { - return 0 - } - return b.MaxC - tempC -} - -// ShedHeadroomC returns degrees available before hitting the min bound. -func (b TemperatureBand) ShedHeadroomC(tempC float64) float64 { - if !finite(tempC) || tempC <= b.MinC { - return 0 - } - return tempC - b.MinC -} - -// MarginalPrice is the site-level cost signal for the next thermal kWh. -type MarginalPrice struct { - // ImportOreKWh is consumer cost when the marginal kWh comes from grid import. - ImportOreKWh float64 - // ExportOreKWh is opportunity cost when PV surplus would otherwise export. - ExportOreKWh float64 - // PVSurplusW > 0 means the marginal thermal load can be supplied from PV - // that would otherwise cross the site meter as export. - PVSurplusW float64 - // ImportPressureOreKWh penalizes thermal load during fuse/import pressure. - ImportPressureOreKWh float64 - // BatteryOpportunityOreKWh penalizes spending energy the battery needs later. - BatteryOpportunityOreKWh float64 - // ThermalUrgencyCreditOreKWh rewards filling thermal storage before a - // forecast comfort or DHW shortfall. - ThermalUrgencyCreditOreKWh float64 -} - -// SyntheticOreKWh returns the price to publish to smart native controllers. -func (p MarginalPrice) SyntheticOreKWh() float64 { - base := p.ImportOreKWh - if p.PVSurplusW > 0 && finite(p.ExportOreKWh) { - base = p.ExportOreKWh - } - out := base + p.ImportPressureOreKWh + p.BatteryOpportunityOreKWh - p.ThermalUrgencyCreditOreKWh - if !finite(out) { - return 0 - } - return out -} - -// DecisionInput is the minimum state needed for the first policy controller. -type DecisionInput struct { - Kind AssetKind - - SpaceTempC *float64 - SpaceBand TemperatureBand - - DHWTempC *float64 - DHWBand TemperatureBand - - Price MarginalPrice - - // CheapBelowOreKWh and ExpensiveAboveOreKWh are optional thresholds. - // nil means "unset" — a *float64 so that an explicit 0 öre/kWh - // threshold (precondition/boost only when energy is free or - // negative-priced) is distinguishable from "not configured". Swedish - // spot prices go negative regularly, so 0 is a legitimate threshold. - CheapBelowOreKWh *float64 - ExpensiveAboveOreKWh *float64 - PVPreconditionW float64 - AllowDHWBoost bool -} - -// Intent is a strategy-neutral instruction from planner to driver. -type Intent struct { - Kind IntentKind - SyntheticOreKWh float64 - PreconditionHeadroomC float64 - ShedHeadroomC float64 - DHWWarmHeadroomC float64 - Reason string -} - -// DecideIntent implements the conservative first-pass thermal policy. MPC can -// later replace the decision engine while keeping this same driver contract. -func DecideIntent(in DecisionInput) Intent { - price := in.Price.SyntheticOreKWh() - intent := Intent{ - Kind: IntentNeutral, - SyntheticOreKWh: price, - Reason: "neutral", - } - - if in.SpaceTempC != nil { - temp := *in.SpaceTempC - intent.PreconditionHeadroomC, intent.ShedHeadroomC = spaceHeadroom(in.Kind, in.SpaceBand, temp) - if finite(temp) && temp < in.SpaceBand.MinC { - intent.Kind = IntentProtectComfort - intent.Reason = "space temperature below minimum" - return intent - } - if finite(temp) && temp > in.SpaceBand.MaxC && in.Kind == AssetCooling { - intent.Kind = IntentProtectComfort - intent.Reason = "space temperature above maximum" - return intent - } - } - - if in.DHWTempC != nil { - temp := *in.DHWTempC - intent.DHWWarmHeadroomC = in.DHWBand.WarmHeadroomC(temp) - if finite(temp) && temp < in.DHWBand.MinC { - intent.Kind = IntentProtectComfort - intent.Reason = "dhw temperature below minimum" - return intent - } - } - - cheap := in.CheapBelowOreKWh != nil && price <= *in.CheapBelowOreKWh - expensive := in.ExpensiveAboveOreKWh != nil && price >= *in.ExpensiveAboveOreKWh - pvSurplus := in.PVPreconditionW > 0 && in.Price.PVSurplusW >= in.PVPreconditionW - - if in.AllowDHWBoost && (cheap || pvSurplus) && intent.DHWWarmHeadroomC > 0 { - intent.Kind = IntentBoostDHW - intent.Reason = "dhw headroom and cheap energy" - return intent - } - if (cheap || pvSurplus) && intent.PreconditionHeadroomC > 0 { - intent.Kind = IntentPrecondition - intent.Reason = "thermal headroom and cheap energy" - return intent - } - if expensive && intent.ShedHeadroomC > 0 { - intent.Kind = IntentShed - intent.Reason = "expensive energy and shed headroom" - return intent - } - - return intent -} - -func spaceHeadroom(kind AssetKind, band TemperatureBand, tempC float64) (preconditionC, shedC float64) { - if kind == AssetCooling { - return band.ShedHeadroomC(tempC), band.WarmHeadroomC(tempC) - } - return band.WarmHeadroomC(tempC), band.ShedHeadroomC(tempC) -} - -func finite(v float64) bool { - return !math.IsNaN(v) && !math.IsInf(v, 0) -} diff --git a/go/internal/thermal/model_test.go b/go/internal/thermal/model_test.go index a0d38d610..34293ff3a 100644 --- a/go/internal/thermal/model_test.go +++ b/go/internal/thermal/model_test.go @@ -2,141 +2,15 @@ package thermal import "testing" -func ptr(v float64) *float64 { return &v } - -func TestSyntheticPriceUsesExportValueWhenPVSurplus(t *testing.T) { - price := MarginalPrice{ - ImportOreKWh: 180, - ExportOreKWh: 40, - PVSurplusW: 2500, - ImportPressureOreKWh: 10, - BatteryOpportunityOreKWh: 5, - ThermalUrgencyCreditOreKWh: 20, - } - - got := price.SyntheticOreKWh() - want := 35.0 - if got != want { - t.Fatalf("SyntheticOreKWh() = %.1f, want %.1f", got, want) - } -} - -func TestDecideIntentProtectsComfortBeforePrice(t *testing.T) { - space := 19.4 - intent := DecideIntent(DecisionInput{ - Kind: AssetSpaceHeat, - SpaceTempC: &space, - SpaceBand: TemperatureBand{MinC: 20, NormalC: 21, MaxC: 22.5}, - Price: MarginalPrice{ - ImportOreKWh: 300, - }, - ExpensiveAboveOreKWh: ptr(200), - }) - - if intent.Kind != IntentProtectComfort { - t.Fatalf("intent = %q, want %q", intent.Kind, IntentProtectComfort) - } -} - -func TestDecideIntentBoostsDHWBeforeSpacePreheat(t *testing.T) { - space := 21.0 - dhw := 48.0 - intent := DecideIntent(DecisionInput{ - Kind: AssetSpaceHeat, - SpaceTempC: &space, - SpaceBand: TemperatureBand{MinC: 20, NormalC: 21, MaxC: 22.5}, - DHWTempC: &dhw, - DHWBand: TemperatureBand{MinC: 45, NormalC: 50, MaxC: 58}, - AllowDHWBoost: true, - Price: MarginalPrice{ - ImportOreKWh: 40, - }, - CheapBelowOreKWh: ptr(60), - }) - - if intent.Kind != IntentBoostDHW { - t.Fatalf("intent = %q, want %q", intent.Kind, IntentBoostDHW) - } -} - -func TestDecideIntentShedsWhenExpensiveAndComfortAllows(t *testing.T) { - space := 21.5 - intent := DecideIntent(DecisionInput{ - Kind: AssetSpaceHeat, - SpaceTempC: &space, - SpaceBand: TemperatureBand{MinC: 20, NormalC: 21, MaxC: 22.5}, - Price: MarginalPrice{ - ImportOreKWh: 260, - }, - ExpensiveAboveOreKWh: ptr(200), - }) - - if intent.Kind != IntentShed { - t.Fatalf("intent = %q, want %q", intent.Kind, IntentShed) - } -} - -func TestDecideIntentPreconditionsOnPVSurplus(t *testing.T) { - space := 21.0 - intent := DecideIntent(DecisionInput{ - Kind: AssetSpaceHeat, - SpaceTempC: &space, - SpaceBand: TemperatureBand{MinC: 20, NormalC: 21, MaxC: 22.5}, - PVPreconditionW: 1000, - Price: MarginalPrice{ - ImportOreKWh: 180, - ExportOreKWh: 35, - PVSurplusW: 1600, - }, - }) - - if intent.Kind != IntentPrecondition { - t.Fatalf("intent = %q, want %q", intent.Kind, IntentPrecondition) - } -} - -// A CheapBelowOreKWh threshold of exactly 0 means "precondition only when -// energy is free or negative-priced". Because Swedish spot prices go negative -// regularly, 0 is a legitimate threshold and must not be treated as "unset". -func TestDecideIntentPreconditionsAtZeroThresholdOnNegativePrice(t *testing.T) { - space := 21.0 - intent := DecideIntent(DecisionInput{ - Kind: AssetSpaceHeat, - SpaceTempC: &space, - SpaceBand: TemperatureBand{MinC: 20, NormalC: 21, MaxC: 22.5}, - Price: MarginalPrice{ - ImportOreKWh: -50, - }, - CheapBelowOreKWh: ptr(0), - }) - - if intent.Kind != IntentPrecondition { - t.Fatalf("intent = %q, want %q", intent.Kind, IntentPrecondition) - } -} - -func TestDecideIntentCoolingUsesInverseTemperatureHeadroom(t *testing.T) { - space := 23.0 - intent := DecideIntent(DecisionInput{ - Kind: AssetCooling, - SpaceTempC: &space, - SpaceBand: TemperatureBand{MinC: 21, NormalC: 23, MaxC: 25}, - PVPreconditionW: 1000, - ExpensiveAboveOreKWh: ptr(200), - Price: MarginalPrice{ - ImportOreKWh: 260, - ExportOreKWh: 30, - PVSurplusW: 1200, - }, - }) - - if intent.Kind != IntentPrecondition { - t.Fatalf("intent = %q, want %q", intent.Kind, IntentPrecondition) - } - if intent.PreconditionHeadroomC != 2 { - t.Fatalf("precondition headroom = %.1f, want 2.0", intent.PreconditionHeadroomC) - } - if intent.ShedHeadroomC != 2 { - t.Fatalf("shed headroom = %.1f, want 2.0", intent.ShedHeadroomC) +func TestValidAssetKind(t *testing.T) { + for _, k := range []AssetKind{AssetSpaceHeat, AssetCooling, AssetDHW, AssetBuffer} { + if !ValidAssetKind(k) { + t.Errorf("ValidAssetKind(%q) = false", k) + } + } + for _, k := range []AssetKind{"", "sauna", "Space_Heat"} { + if ValidAssetKind(k) { + t.Errorf("ValidAssetKind(%q) = true", k) + } } }