Design discussion for how rate limit configuration should evolve from the current callable-based approach to static configuration, and the precedence model for multiple configuration sources. Parent epic: https://gitlab.com/groups/gitlab-com/gl-infra/-/work_items/2021 Related: https://gitlab.com/gitlab-com/gl-infra/production-engineering/-/work_items/26769 (YAML schema project) Related: https://gitlab.com/gitlab-com/gl-infra/production-engineering/-/work_items/28775 (design doc updates) Context: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/233816#note_3306569087 ## Problem The current `ApplicationRateLimiter` uses callable `limit` and `period` values (Procs that read from `ApplicationSettings` at check time). This allows admins to change rate limits via the API or admin panel without restarting the application. Labkit's `Rule` supports callables, but the adapter pattern in the Stage 2a migration (gitlab!233816) rebuilds the `Limiter` and `Rule` on every request to resolve these values. This works but is wasteful and couples the labkit API to the Rails configuration model. We need a clear plan for how configuration evolves through three phases. ## Phase 1: Callable support in labkit (near-term) **Goal:** No breaking changes for self-managed or GitLab.com. Labkit should natively support callable `limit` and `period` on rules, resolved at check time (not at `Limiter.new` time). This is already partially implemented — `Rule` accepts callables, and the `Evaluator` resolves them via `resolve_value`. The adapter should be able to pass callable rules directly without rebuilding per request. This ensures that existing database-backed configuration (via `ApplicationSettings`) continues to work unchanged. Self-managed installations keep their ability to configure rate limits through the admin panel and API. ## Phase 2: Labkit-injected rules with precedence (mid-term) **Goal:** Decouple platform-level rate limit configuration from the application. Labkit gains the ability to inject rules from additional sources (YAML files, external service) **before** the default rules passed in by the caller. Since labkit uses first-match-wins evaluation, injected rules take precedence over caller-provided defaults. The precedence model: 1. **Labkit-injected rules** (from YAML, external service) — evaluated first, highest priority 2. **Caller-provided rules** (from ApplicationSettings, hardcoded defaults) — evaluated after, serve as fallback This means: - GitLab.com can have platform-level rules (from YAML or external service) that override the application defaults - Self-managed installations without injected rules continue to use the database-backed configuration unchanged - A platform rule that matches a request "wins" over the default, allowing per-customer, per-tier, or per-endpoint overrides without changing the application code Example: ```ruby limiter = Labkit::RateLimit::Limiter.new( name: "rack_request_user", rules: [ # These would be injected by labkit from YAML/external service: { name: "premium_api", match: { namespace_plan: "premium" }, characteristics: [:user], limit: 100, period: 60, action: :block }, # These are the caller's defaults (from ApplicationSettings): { name: "default_api", match: { request_type: "api" }, characteristics: [:user], limit: -> { settings.api_limit }, period: 60, action: :block } ] ) ``` The premium-plan rule matches first for premium users, overriding the default. Non-premium users fall through to the default rule. This ties into: - https://gitlab.com/gitlab-com/gl-infra/production-engineering/-/work_items/26769 (YAML schema project — defines the format for static rules) - https://gitlab.com/gitlab-com/gl-infra/production-engineering/-/work_items/28775 (design docs — should be updated to reflect this precedence model) ## Phase 3: Fully static configuration (long-term) **Goal:** Rate limit configuration becomes static and declarative, loaded from configuration files or an external service. All rate limits are defined in configuration (YAML files, external service), not in application code. This applies to all platforms (GitLab.com, Dedicated, self-managed) and all modular features — no longer limited to GitLab-rails. In this phase: - Callable `limit`/`period` values are retired in favor of static values managed through the configuration system - The admin panel configuration is replaced by the external configuration interface (or YAML files for self-managed) - labkit becomes the single source of truth for rate limit configuration, not just the counting/enforcement layer ## Questions to resolve 1. Should labkit's `configure` block support registering rule sources (e.g., `config.add_rule_source(:yaml, path: "...")`)? Or should rule injection happen at `Limiter.new` time? 2. For the YAML schema (#26769): should it support callable-equivalent patterns (e.g., referencing ApplicationSettings values), or should YAML rules always be static? 3. Do we need a new design doc for the precedence model, or can we extend the existing rate limiting simplification design doc? 4. Timeline: when do we deprecate callable support? Only after all platforms have migrated to static configuration?