feat(ratelimit): persist request and token windows across restart

.env.template

@@ -377,11 +377,13 @@
 # Rate Limits
 # =============================================================================
 # Cap requests, tokens, and in-flight concurrency per user_path subtree.
-# Breaches return 429 with Retry-After and x-ratelimit-* headers. Counters are
-# in-memory per gateway instance and reset on restart; token limits (tpm/tph/
-# tpd) additionally require USAGE_ENABLED=true. Enabled by default; with no
-# configured rules the check is a no-op.
+# Breaches return 429 with Retry-After and x-ratelimit-* headers. Request and
+# token windows are snapshotted to the configured store (default every 1s) so
+# they survive restart and --reload. Concurrency gauges stay in-memory.
+# Token limits (tpm/tph/tpd) additionally require USAGE_ENABLED=true. Enabled
+# by default; with no configured rules the check is a no-op.
 # RATE_LIMITS_ENABLED=true
+# RATE_LIMITS_FLUSH_INTERVAL=1
 
 # Declare rules per user path with SET_RATE_LIMIT_<PATH> (double underscores
 # separate path segments, like SET_BUDGET_*). Names: rpm/tpm (per minute),

CLAUDE.md

@@ -111,7 +111,7 @@ Full reference: `.env.template` and `config/config.yaml`
   - `GOMODEL_MASTER_KEY` (empty = unsafe mode). Managed API keys (dashboard API Keys page / `POST /admin/auth-keys`) carry a per-key `dashboard_access` flag (default false, changeable via `PUT /admin/auth-keys/{id}/dashboard-access`): only the master key and flagged keys can call the admin REST API endpoints under `/admin/*` (others get 403 `dashboard_access_denied`); the dashboard UI shell and static assets (`/admin/dashboard`, `/admin/static/*`) skip auth entirely — only the admin data they load is gated; model endpoints and `GET /v1/usage` stay open to every key, and the no-master-key lockout-recovery path (auth skipped on `/admin/*`) is unaffected.
   - `BODY_SIZE_LIMIT` ("10M")
   - `USER_PATH_HEADER` (`X-GoModel-User-Path`: Header used to read/write request `user_path` values)
-  - `PID_FILE` / `server.pid_file` (`data/gomodel.pid` next to a `./data` directory, otherwise the OS per-user data dir — same resolution as `SQLITE_PATH`): where the running gateway records its process id. `gomodel --reload` reads it and signals that process (SIGHUP; `kill -HUP` works too) to reload configuration without a restart, like `nginx -s reload`. The reload re-reads `.env` (exported variables still win over the file; variables removed from the file are unset) and the whole config, then rebuilds the application — so every setting reloads, not a curated subset. The replacement is built before the running one is stopped, so a broken config keeps the current one serving; the listening socket is held across generations, so no connection is refused mid-reload. `PORT` and `PID_FILE` changes still need a restart (warned about), and in-memory state — rate limit counters, session affinity pins, live log buffers — resets as it would on restart. `server.pid_file: ""` in `config.yaml` disables the pid file and `--reload` (an empty `PID_FILE` env var reads as unset and keeps the default). Not available on Windows (POSIX signals).
+  - `PID_FILE` / `server.pid_file` (`data/gomodel.pid` next to a `./data` directory, otherwise the OS per-user data dir — same resolution as `SQLITE_PATH`): where the running gateway records its process id. `gomodel --reload` reads it and signals that process (SIGHUP; `kill -HUP` works too) to reload configuration without a restart, like `nginx -s reload`. The reload re-reads `.env` (exported variables still win over the file; variables removed from the file are unset) and the whole config, then rebuilds the application — so every setting reloads, not a curated subset. The replacement is built before the running one is stopped, so a broken config keeps the current one serving; the listening socket is held across generations, so no connection is refused mid-reload. `PORT` and `PID_FILE` changes still need a restart (warned about), and in-memory state — session affinity pins, live log buffers — resets as it would on restart (request/token rate-limit windows are snapshotted to storage). `server.pid_file: ""` in `config.yaml` disables the pid file and `--reload` (an empty `PID_FILE` env var reads as unset and keeps the default). Not available on Windows (POSIX signals).
   - `ENABLE_PASSTHROUGH_ROUTES` (true: Enable provider-native passthrough routes under /p/{provider}/...)
   - `ALLOW_PASSTHROUGH_V1_ALIAS` (true: Allow /p/{provider}/v1/... aliases while keeping /p/{provider}/... canonical)
   - `ENABLED_PASSTHROUGH_PROVIDERS` (openai,anthropic,openrouter,kilo,zai,sglang,vllm,deepseek: Comma-separated list of enabled passthrough providers)
@@ -125,7 +125,7 @@ Full reference: `.env.template` and `config/config.yaml`
 - **Audit logging:** `LOGGING_ENABLED` (true), `LOGGING_LOG_BODIES` (true), `LOGGING_LOG_AUDIO_BODIES` (false: refines `LOGGING_LOG_BODIES` for audio endpoints — base64 audio for both `/v1/audio/speech` output and `/v1/audio/transcriptions` upload (≤8 MB each, else `too_large`) + dashboard playback, plus transcription upload metadata; no effect unless `LOGGING_LOG_BODIES` is on, in which case audio-off records a placeholder), `LOGGING_LOG_HEADERS` (true), `LOGGING_RETENTION_DAYS` (30)
 - **Usage tracking:** `USAGE_ENABLED` (true), `ENFORCE_RETURNING_USAGE_DATA` (true), `USAGE_RETENTION_DAYS` (90). Callers can read their own status without admin access via `GET /v1/usage`: usage summary over a date window (`start_date`/`end_date`/`days`, default last 30 days UTC) plus budget and rate-limit statuses, all scoped to the caller's effective user path (managed key binding, else the user-path header).
 - **Budgets:** `BUDGETS_ENABLED` (true; no-op until budgets exist, and force-disabled with a warning when `USAGE_ENABLED=false` since spend is read from usage cost records). Every budget has a scope: `user_path` (subtree — a budget on `/team` covers `/team/app` but not `/team-alpha`) or `label` (matches a request label verbatim, no case folding; labels come from tagging headers and managed-key labels, and a request carrying several labels is charged against every matching label budget). Limits are an `amount` per period (`hourly`/`daily`/`weekly`/`monthly`, or a custom `period_seconds` — named periods reset on the calendar anchors configured under Settings → Budget Resets, only custom seconds are fixed windows). A breach returns 429 (`code: budget_exceeded`) with `Retry-After`; a budget with no recorded usage never blocks, and response cache hits return before enforcement. Managed in the dashboard (Budgets page: scope selector) / `/admin/budgets` (GET/PUT/DELETE + `POST .../reset-one`, `POST .../reset`; requests take `scope`+`subject`, with `user_path` as shorthand for user-path budgets), or as infrastructure-as-code under `budgets.{user_paths,labels}:` in `config.yaml` / `SET_BUDGET_<PATH>` env vars (`period=amount` compact syntax or a JSON limit array; `__` separates path segments). Label budgets are YAML/admin-only — labels are matched verbatim and are not env-name safe. Config-sourced budgets are read-only in the dashboard and manual edits win over config seeds. A user-path budget can also carry `per_child: true` (GoModel Pro, `quota_templates` entitlement): the entry becomes a template giving every *direct* child of the subject its own independent budget rather than one shared subtree budget — `/customers/alice` and `/customers/alice/app` both spend from Alice's, `/customers/bob` from Bob's, and the template path itself matches nothing. Resetting the template starts a new period for every child. Without the entitlement `PER_CHILD_QUOTAS_ENABLED` is off, admin writes return 403 `quota_templates_not_entitled`, and `per_child` in `config.yaml`/`SET_BUDGET_*` aborts startup rather than silently degrading to a shared limit. Enforcement evaluates every matching budget in ONE batched store query (`Store.SumSpend`), so a wide match set costs one scan rather than one per budget.
-- **Rate limits:** `RATE_LIMITS_ENABLED` (true; no-op until rules exist). Every rule has a scope: `user_path` (consumer control; subtree with ONE shared counter per rule — per-key limits = give each key its own path), `provider` (caps one configured provider instance across all consumers/models), or `model` (subject `openai/gpt-4o` pins one provider's model, bare `gpt-4o` covers it on any provider; matching case-insensitive). Limits: `max_requests`/`max_tokens` per period (`minute`/`hour`/`day`/custom `period_seconds`, sliding window) plus `concurrent` (period_seconds 0: `max_requests` = max in-flight; realtime sessions hold a slot for the session, batch submissions don't — and batch skips provider/model rules since batch files can mix models). Enforcement covers every model endpoint; user-path breaches return 429 (`code: rate_limit_exceeded`) with `Retry-After`, successes carry `x-ratelimit-{limit,remaining,reset}-{requests,tokens}` from the most-constrained matching rule; cache hits bypass. Saturated providers/models are instead routed around: virtual-model load balancing prefers targets with capacity (falling back to the first declared target when all are saturated, so the client gets an honest 429 rather than an unavailable-model error; saturation never affects catalog membership or /v1/models listing), a saturated primary route with configured failover rules skips the primary provider and is served by the sweep (which also skips saturated candidates), and only requests with no viable alternative get 429. Token windows are charged to the provider/model that actually executed (from the usage entry), so accounting stays correct under aliasing/failover. Managed in the dashboard (Rate Limits page: scope selector) / `/admin/rate-limits` (GET/PUT/DELETE + `POST .../reset-one`, `POST .../reset`; requests take `scope`+`subject`, with `user_path` as shorthand for user-path rules), or as infrastructure-as-code under `rate_limits.{user_paths,providers,models}:` in `config.yaml` / `SET_RATE_LIMIT_<PATH>` env vars (`rpm/tpm/rph/tph/rpd/tpd/concurrent=N` compact syntax or a JSON rule array; `__` separates path segments) and `SET_PROVIDER_RATE_LIMIT_<NAME>` (same syntax; suffix underscores become hyphens; model rules are YAML/admin-only). Env replaces the whole YAML entry for the same subject; config-sourced rules are read-only in the dashboard and manual edits win over config seeds, like budgets. A user-path rule can also carry `per_child: true` (GoModel Pro, `quota_templates` entitlement), turning the one shared subtree counter into a template with independent counters per *direct* child (descendants share their direct child's); provider and model rules cannot be per-child. Resetting or deleting the template clears every child's request and token window. The same entitlement gate as budgets applies: 403 `quota_templates_not_entitled` on admin writes, startup abort on config. Token limits are post-accounted from usage entries, so they require `USAGE_ENABLED=true` (startup warns otherwise) and one request can overshoot a token window. Counters are in-memory per instance (N replicas ≈ N× limit) and reset on restart — budgets remain the durable cross-instance control.
+- **Rate limits:** `RATE_LIMITS_ENABLED` (true; no-op until rules exist). Every rule has a scope: `user_path` (consumer control; subtree with ONE shared counter per rule — per-key limits = give each key its own path), `provider` (caps one configured provider instance across all consumers/models), or `model` (subject `openai/gpt-4o` pins one provider's model, bare `gpt-4o` covers it on any provider; matching case-insensitive). Limits: `max_requests`/`max_tokens` per period (`minute`/`hour`/`day`/custom `period_seconds`, sliding window) plus `concurrent` (period_seconds 0: `max_requests` = max in-flight; realtime sessions hold a slot for the session, batch submissions don't — and batch skips provider/model rules since batch files can mix models). Enforcement covers every model endpoint; user-path breaches return 429 (`code: rate_limit_exceeded`) with `Retry-After`, successes carry `x-ratelimit-{limit,remaining,reset}-{requests,tokens}` from the most-constrained matching rule; cache hits bypass. Saturated providers/models are instead routed around: virtual-model load balancing prefers targets with capacity (falling back to the first declared target when all are saturated, so the client gets an honest 429 rather than an unavailable-model error; saturation never affects catalog membership or /v1/models listing), a saturated primary route with configured failover rules skips the primary provider and is served by the sweep (which also skips saturated candidates), and only requests with no viable alternative get 429. Token windows are charged to the provider/model that actually executed (from the usage entry), so accounting stays correct under aliasing/failover. Managed in the dashboard (Rate Limits page: scope selector) / `/admin/rate-limits` (GET/PUT/DELETE + `POST .../reset-one`, `POST .../reset`; requests take `scope`+`subject`, with `user_path` as shorthand for user-path rules), or as infrastructure-as-code under `rate_limits.{user_paths,providers,models}:` in `config.yaml` / `SET_RATE_LIMIT_<PATH>` env vars (`rpm/tpm/rph/tph/rpd/tpd/concurrent=N` compact syntax or a JSON rule array; `__` separates path segments) and `SET_PROVIDER_RATE_LIMIT_<NAME>` (same syntax; suffix underscores become hyphens; model rules are YAML/admin-only). Env replaces the whole YAML entry for the same subject; config-sourced rules are read-only in the dashboard and manual edits win over config seeds, like budgets. A user-path rule can also carry `per_child: true` (GoModel Pro, `quota_templates` entitlement), turning the one shared subtree counter into a template with independent counters per *direct* child (descendants share their direct child's); provider and model rules cannot be per-child. Resetting or deleting the template clears every child's request and token window. The same entitlement gate as budgets applies: 403 `quota_templates_not_entitled` on admin writes, startup abort on config. Token limits are post-accounted from usage entries, so they require `USAGE_ENABLED=true` (startup warns otherwise) and one request can overshoot a token window. Request/token windows are snapshotted to the store (`RATE_LIMITS_FLUSH_INTERVAL`, default 1s) so they survive restart and `--reload`; concurrency gauges stay in-memory. N replicas ≈ N× the configured limit — budgets remain the durable cross-instance control.
 - **Dashboard live logs:**
   - `DASHBOARD_LIVE_LOGS_ENABLED` (true): keep enabled for low-latency dashboard previews; set false only when live streams are not needed or memory/socket usage must be minimized. With `LOGGING_LOG_BODIES` also enabled, in-flight streamed responses render chunk-by-chunk in the request log and Interactions drawer (throttled `audit.stream` events, published only while a dashboard is connected; partial bodies are never buffered server-side).
   - `DASHBOARD_LIVE_LOGS_BUFFER_SIZE` (10000): effective size is capped at `DASHBOARD_LIVE_LOGS_REPLAY_LIMIT + 1` (older events can never be replayed); lower it below the replay limit only to shrink memory at the cost of more replay resets. Buffered events are compact previews — request/response bodies are never retained in the buffer (connected dashboards get them live; history hydrates from persisted audit entries).

config/config.example.yaml

@@ -198,6 +198,7 @@ budgets:
 
 rate_limits:
   enabled: true # env: RATE_LIMITS_ENABLED; with no configured rules this has no effect
+  flush_interval: 1 # seconds; env: RATE_LIMITS_FLUSH_INTERVAL; 0 = no periodic snapshot (still load + shutdown flush)
   user_paths:
     # Env equivalent:
     # SET_RATE_LIMIT_USER__PATH__EXAMPLE="rpm=100,tpm=50000,rpd=10000,concurrent=10"

config/config.go

@@ -154,7 +154,8 @@ func buildDefaultConfig() *Config {
 			Enabled: true,
 		},
 		RateLimits: RateLimitsConfig{
-			Enabled: true,
+			Enabled:       true,
+			FlushInterval: 1,
 		},
 		Metrics: MetricsConfig{
 			Endpoint: "/metrics",

config/config_test.go

@@ -65,7 +65,7 @@ func clearAllConfigEnvVars(t *testing.T) {
 		"USAGE_PRICING_RECALCULATION_ENABLED",
 		"USAGE_BUFFER_SIZE", "USAGE_FLUSH_INTERVAL", "USAGE_RETENTION_DAYS",
 		"BUDGETS_ENABLED",
-		"RATE_LIMITS_ENABLED",
+		"RATE_LIMITS_ENABLED", "RATE_LIMITS_FLUSH_INTERVAL",
 		"DASHBOARD_LIVE_LOGS_ENABLED", "DASHBOARD_LIVE_LOGS_BUFFER_SIZE",
 		"DASHBOARD_LIVE_LOGS_REPLAY_LIMIT", "DASHBOARD_LIVE_LOGS_HEARTBEAT_SECONDS",
 		"GUARDRAILS_ENABLED", "ENABLE_GUARDRAILS_FOR_BATCH_PROCESSING",

config/ratelimit.go

@@ -15,6 +15,11 @@ type RateLimitsConfig struct {
 	// Default: true. With no rules configured the check is a no-op.
 	Enabled bool `yaml:"enabled" env:"RATE_LIMITS_ENABLED"`
 
+	// FlushInterval is how often live request/token windows are written to
+	// storage, in seconds. Default 1. 0 disables the periodic loop; Start
+	// still loads and Close of an active generation still writes once.
+	FlushInterval int `yaml:"flush_interval" env:"RATE_LIMITS_FLUSH_INTERVAL"`
+
 	// UserPaths declares rate limit rules by tracked user path.
 	UserPaths []RateLimitUserPathConfig `yaml:"user_paths"`
 
@@ -230,6 +235,9 @@ func validateRateLimitConfig(cfg *RateLimitsConfig) error {
 	if cfg == nil {
 		return nil
 	}
+	if cfg.FlushInterval < 0 {
+		return fmt.Errorf("rate_limits.flush_interval must be >= 0")
+	}
 	if !cfg.Enabled {
 		return nil
 	}

config/ratelimit_test.go

@@ -457,6 +457,9 @@ func TestRateLimitsEnabledByDefaultAndTogglable(t *testing.T) {
 		if !result.Config.RateLimits.Enabled {
 			t.Fatal("rate limits should be enabled by default")
 		}
+		if result.Config.RateLimits.FlushInterval != 1 {
+			t.Fatalf("FlushInterval = %d, want 1", result.Config.RateLimits.FlushInterval)
+		}
 	})
 
 	withTempDir(t, func(string) {
@@ -471,6 +474,29 @@ func TestRateLimitsEnabledByDefaultAndTogglable(t *testing.T) {
 	})
 }
 
+func TestRateLimitsFlushIntervalEnv(t *testing.T) {
+	clearAllConfigEnvVars(t)
+
+	withTempDir(t, func(string) {
+		t.Setenv("RATE_LIMITS_FLUSH_INTERVAL", "0")
+		result, err := Load()
+		if err != nil {
+			t.Fatalf("Load() failed: %v", err)
+		}
+		if result.Config.RateLimits.FlushInterval != 0 {
+			t.Fatalf("FlushInterval = %d, want 0", result.Config.RateLimits.FlushInterval)
+		}
+	})
+
+	clearAllConfigEnvVars(t)
+	withTempDir(t, func(string) {
+		t.Setenv("RATE_LIMITS_FLUSH_INTERVAL", "-1")
+		if _, err := Load(); err == nil || !strings.Contains(err.Error(), "flush_interval") {
+			t.Fatalf("Load() error = %v, want flush_interval", err)
+		}
+	})
+}
+
 func TestParseRateLimitEnvLimits_RejectsUnknownField(t *testing.T) {
 	_, err := parseRateLimitEnvLimits(`[{"period":"minute","max_requsts":100}]`, true)
 	if err == nil {

docs/advanced/cli.mdx

@@ -173,9 +173,11 @@ docker exec my-gateway /gomodel --reload
   needs a restart. The gateway logs a warning naming both ports.
 - **`PID_FILE`** — it names the process that is already running.
 - **`GOMODEL_DEMO_MODE`** — the demo warnings are wired up once at startup.
-- **In-memory state** — rate limit counters, virtual-model session affinity, and
-  live log buffers start fresh, exactly as they would after a restart. Budgets
-  and usage are stored in the database and are unaffected.
+- **In-memory state** — virtual-model session affinity and live log buffers
+  start fresh, exactly as they would after a restart. Request and token rate
+  limit windows are written on shutdown and restored by the next generation.
+  Concurrency gauges and budgets/usage behave as they do on restart (gauges
+  start empty; budgets and usage live in the database).
 
 For refreshing provider model catalogs and admin-managed data *without* re-reading
 configuration, the dashboard's runtime refresh (`POST /admin/runtime/refresh`) is