Internal limits with spillover

Internal limits enable you to specify nested quotas within a primary quota, establishing granular control over specific groups or endpoints under the primary quota. These limits support individual strategies (such as fixed window or concurrent) and, where relevant, incorporate spillover settings.

The spillover capability carries forward unused quota from one window to the next, within a specified limit. This helps manage irregular traffic while staying within the main quota limits.

Spillover configuration scenario

The following configuration example demonstrates internal limits with spillover settings:

/etc/lunar-proxy/quotas/{fileName}.yaml

quotas:
  - id: MyQuota # Unique identifier for the main quota
    filter:
      url: api.website.com/* # URL pattern the main quota applies to
      headers:
        - key: x-lunar-consumer-tag # Header-based grouping
          value: premium # Example group
        - key: x-lunar-consumer-tag
          value: basic # Example group

    # Primary quota strategy using Fixed Window
    strategy:
      fixed_window:
        static:
          max: 1000 # Max requests allowed in the main window
          interval: 24
          interval_unit: hour
          group_by_header: x-lunar-consumer-tag # Optional grouping by header

internal_limits: # Define nested child quotas within the main quota
  - id: PremiumQuota # Internal limit for premium users
    parent_id: MyQuota
    filter:
      headers:
        - key: x-lunar-consumer-tag
          value: premium
    strategy:
      fixed_window:
        static:
          max: 500 # Max requests for premium users in this window
          interval: 1
          interval_unit: day
        spillover:
          max: 100 # Unused quota can carry over up to 100 requests to the next window

  - id: BasicQuota # Internal limit for basic users
    parent_id: MyQuota
    filter:
      headers:
        - key: x-lunar-consumer-tag
          value: basic
    strategy:
      fixed_window:
        static:
          max: 200 # Max requests for basic users in this window
          interval: 1
          interval_unit: day

Key configuration elements include:

• The PremiumQuota and BasicQuota internal limits operate under the main quota, with tailored restrictions for each user group.
• The spillover feature on the PremiumQuota rolls over up to 100 unused requests into the next interval, creating a flexible usage model for premium users.