feat(auth): add persistent cooldown state management with file-backed store

- Introduced `CooldownStateStore` interface for managing independent cooldown state persistence.
- Implemented `FileCooldownStateStore` for storing cooldown states as per-auth `.cds` files with atomic writes and stale file cleanup.
- Enhanced `Manager` to support restoring state from `CooldownStateStore` and persisting state changes during auth updates.
- Updated tests to validate cooldown state saving, loading, concurrency handling, and error scenarios.

Closes: router-for-me#3368

Author: luispater

config.example.yaml

@@ -119,6 +119,10 @@ max-retry-interval: 30
 # When true, disable auth/model cooldown scheduling globally (prevents blackout windows after failure states).
 disable-cooling: false
 
+# When true, persist per-auth cooldown status as .cds files next to auth files.
+# Default is false; when false, cooldown status is kept in memory only.
+save-cooldown-status: false
+
 # Cooldown duration in seconds for transient upstream errors (408/500/502/503/504).
 # Set to 0 to keep the legacy 60-second cooldown; set to -1 to disable transient error cooldowns.
 transient-error-cooldown-seconds: 0

internal/config/config.go

@@ -80,6 +80,9 @@ type Config struct {
 	// DisableCooling disables quota cooldown scheduling when true.
 	DisableCooling bool `yaml:"disable-cooling" json:"disable-cooling"`
 
+	// SaveCooldownStatus persists runtime cooldown status next to auth files when true.
+	SaveCooldownStatus bool `yaml:"save-cooldown-status" json:"save-cooldown-status"`
+
 	// TransientErrorCooldownSeconds controls cooldowns for transient upstream errors.
 	// 0 keeps the legacy default cooldown. Negative values disable these cooldowns.
 	TransientErrorCooldownSeconds int `yaml:"transient-error-cooldown-seconds" json:"transient-error-cooldown-seconds"`
@@ -688,6 +691,7 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 	cfg.UsageStatisticsEnabled = false
 	cfg.RedisUsageQueueRetentionSeconds = 60
 	cfg.DisableCooling = false
+	cfg.SaveCooldownStatus = false
 	cfg.TransientErrorCooldownSeconds = 0
 	cfg.DisableImageGeneration = DisableImageGenerationOff
 	cfg.Pprof.Enable = false

internal/config/parse.go

@@ -25,6 +25,7 @@ func ParseConfigBytes(data []byte) (*Config, error) {
 	cfg.UsageStatisticsEnabled = false
 	cfg.RedisUsageQueueRetentionSeconds = 60
 	cfg.DisableCooling = false
+	cfg.SaveCooldownStatus = false
 	cfg.TransientErrorCooldownSeconds = 0
 	cfg.DisableImageGeneration = DisableImageGenerationOff
 	cfg.Pprof.Enable = false

internal/watcher/diff/config_diff.go

@@ -45,6 +45,9 @@ func BuildConfigChangeDetails(oldCfg, newCfg *config.Config) []string {
 	if oldCfg.DisableCooling != newCfg.DisableCooling {
 		changes = append(changes, fmt.Sprintf("disable-cooling: %t -> %t", oldCfg.DisableCooling, newCfg.DisableCooling))
 	}
+	if oldCfg.SaveCooldownStatus != newCfg.SaveCooldownStatus {
+		changes = append(changes, fmt.Sprintf("save-cooldown-status: %t -> %t", oldCfg.SaveCooldownStatus, newCfg.SaveCooldownStatus))
+	}
 	if oldCfg.TransientErrorCooldownSeconds != newCfg.TransientErrorCooldownSeconds {
 		changes = append(changes, fmt.Sprintf("transient-error-cooldown-seconds: %d -> %d", oldCfg.TransientErrorCooldownSeconds, newCfg.TransientErrorCooldownSeconds))
 	}

internal/watcher/diff/config_diff_test.go

@@ -193,6 +193,7 @@ func TestBuildConfigChangeDetails_FlagsAndKeys(t *testing.T) {
 		LoggingToFile:                 false,
 		UsageStatisticsEnabled:        false,
 		DisableCooling:                false,
+		SaveCooldownStatus:            false,
 		TransientErrorCooldownSeconds: 0,
 		RequestRetry:                  1,
 		MaxRetryCredentials:           1,
@@ -217,6 +218,7 @@ func TestBuildConfigChangeDetails_FlagsAndKeys(t *testing.T) {
 		LoggingToFile:                 true,
 		UsageStatisticsEnabled:        true,
 		DisableCooling:                true,
+		SaveCooldownStatus:            true,
 		TransientErrorCooldownSeconds: -1,
 		RequestRetry:                  2,
 		MaxRetryCredentials:           3,
@@ -252,6 +254,7 @@ func TestBuildConfigChangeDetails_FlagsAndKeys(t *testing.T) {
 	expectContains(t, details, "logging-to-file: false -> true")
 	expectContains(t, details, "usage-statistics-enabled: false -> true")
 	expectContains(t, details, "disable-cooling: false -> true")
+	expectContains(t, details, "save-cooldown-status: false -> true")
 	expectContains(t, details, "transient-error-cooldown-seconds: 0 -> -1")
 	expectContains(t, details, "disable-image-generation: false -> true")
 	expectContains(t, details, "request-log: false -> true")
@@ -282,6 +285,7 @@ func TestBuildConfigChangeDetails_AllBranches(t *testing.T) {
 		LoggingToFile:                 false,
 		UsageStatisticsEnabled:        false,
 		DisableCooling:                false,
+		SaveCooldownStatus:            false,
 		TransientErrorCooldownSeconds: 0,
 		RequestRetry:                  1,
 		MaxRetryCredentials:           1,
@@ -330,6 +334,7 @@ func TestBuildConfigChangeDetails_AllBranches(t *testing.T) {
 		LoggingToFile:                 true,
 		UsageStatisticsEnabled:        true,
 		DisableCooling:                true,
+		SaveCooldownStatus:            true,
 		TransientErrorCooldownSeconds: -1,
 		RequestRetry:                  2,
 		MaxRetryCredentials:           3,
@@ -385,6 +390,7 @@ func TestBuildConfigChangeDetails_AllBranches(t *testing.T) {
 	expectContains(t, changes, "logging-to-file: false -> true")
 	expectContains(t, changes, "usage-statistics-enabled: false -> true")
 	expectContains(t, changes, "disable-cooling: false -> true")
+	expectContains(t, changes, "save-cooldown-status: false -> true")
 	expectContains(t, changes, "transient-error-cooldown-seconds: 0 -> -1")
 	expectContains(t, changes, "disable-image-generation: false -> true")
 	expectContains(t, changes, "request-retry: 1 -> 2")