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

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

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.