Internal Limits with Spillover

Internal limits provide a way to specify nested quotas within a primary quota, allowing granular control over specific groups or endpoints under the same overall quota. These limits can have individual strategies (such as fixed window or concurrent) and, where relevant, incorporate spillover settings.

The spillover feature allows any unused quota from one window to carry over to the next, within a specified limit. This provides a buffer for users who may have inconsistent usage patterns, helping to smooth out their access while still respecting the overarching quota limits.

Example YAML Configuration

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

quota:
  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:
      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:
        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:
        max: 200 # Max requests for basic users in this window
        interval: 1
        interval_unit: day

In this example:

• The PremiumQuota and BasicQuota internal limits operate under the main quota, with tailored restrictions for each user group.
• The spillover feature on the PremiumQuota allows unused requests (up to 100) to roll over into the next interval, creating a more flexible usage model for premium users. This feature is especially helpful for users whose traffic may vary significantly day-to-day.