Dynamic Response Header Quota

Dynamic Response Header Quota empowers granular quota management by dynamically adjusting limits based on response's header values. This capability ensures tailored traffic allocation while respecting overall system limits.

• Dynamic Response Headers: Fields such as remaining_header, reset_time_header, and retry_after_header provide real-time feedback to API consumers.
• Flexible Configuration: Supports all strategies with dynamic quota settings.
• Efficient Resource Management: Allocates resources dynamically based on the response's header values.

Dynamic Quotas with Fixed Window Strategy

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

quotas:
  - id: RegionalQuota
    filter:
      url: api.global-website.com/* # Apply to all API endpoints under this URL pattern
    strategy:
      fixed_window:
        max: 10000 # Premium region quota
        interval: 1
        interval_unit: day
        dynamic: # Dynamic Response Header-Based Configuration
          remaining_header: X-RateLimit-Remaining
          reset_time_header: X-RateLimit-Reset
          reset_time_header_format: relative_duration
          retry_after_header: Retry-After
          retry_after_header_format: http_date 

internal_limits:
  - id: PremiumRegionQuota
    parent_id: RegionalQuota
    filter:
      headers:
        - key: x-user-region
          value: premium-region
    strategy:
      fixed_window:
        max: 1000 # Premium region quota
        interval: 1
        interval_unit: day
          
  - id: BasicRegionQuota
    parent_id: RegionalQuota
    filter:
      headers:
        - key: x-user-region
          value: basic-region
    strategy:
      fixed_window:
        max: 5000 # Basic region quota
        interval: 1
        interval_unit: day

Dynamic Quotas with Concurrent Strategy

Dynamic quotas can also be applied to the concurrent strategy, enabling fine-grained control over simultaneous connections.

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

quotas:
  - id: ConcurrentQuotaBySubscription
    filter:
      url: api.subscription-website.com/*
    strategy:
      concurrent:
        max_request_count: 200 # Maximum concurrent requests
        dynamic:
          remaining_header: X-Concurrent-Remaining

Key Components of Dynamic Quotas

Field	Description	Mandatory/Optional	Example
strategy.fixed_window.dynamic.remaining_header	Header indicating remaining quota.	Optional	X-RateLimit-Remaining
strategy.fixed_window.dynamic.reset_time_header	Header indicating when the quota resets.	Optional	X-RateLimit-Reset
strategy.fixed_window.dynamic.retry_after_header	Header indicating retry-after details.	Optional	Retry-After
strategy.concurrent.remaining_header	Header indicating remaining concurrent requests.	Optional	X-Concurrent-Remaining
filter.headers.key	Header key used for filtering requests.	Optional	x-user-region
filter.headers.value	Header value used for filtering requests.	Optional	premium-region

available time formats: Proposed reset_time_header_format Values and Behavior: "unix_seconds" Expected Header Value: A string representing an integer (e.g., "1743092568"). Behavior: The gateway will parse the header value as the number of seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC). The result is an absolute UTC timestamp. Example Header: X-RateLimit-Reset: 1743092568 "unix_milliseconds" Expected Header Value: A string representing an integer (e.g., "1743092568000"). Behavior: The gateway will parse the header value as the number of milliseconds since the Unix epoch (UTC). The result is an absolute UTC timestamp. Example Header: X-RateLimit-Reset-Ms: 1743092568000 "relative_seconds" Expected Header Value: A string representing an integer (e.g., "3600"). Behavior: The gateway will parse the header value as the number of seconds from the time the response is received. The absolute reset timestamp will be calculated as time_of_response_receipt_utc + parsed_seconds. Example Header: X-Reset-In-Seconds: 3600 "relative_duration" Expected Header Value: A string representing a duration (e.g., "12ms", "2m30s", "1h"). Behavior: The gateway will parse the header value as a duration. The supported format should be similar to Go's time.ParseDuration (e.g., "ns", "us" or "µs", "ms", "s", "m", "h"). The absolute reset timestamp will be calculated as time_of_response_receipt_utc + parsed_duration. Example Header: X-Reset-In: 2m30s "http_date" Expected Header Value: A string formatted according to standard HTTP date formats (RFC 1123, RFC 850, asctime). (e.g., "Wed, 21 Oct 2025 07:28:00 GMT"). Behavior: The gateway will parse the header value as an absolute UTC timestamp according to these standard date formats. This is the format often used by the Retry-After header when it specifies an absolute time. Example Header: X-RateLimit-Expires: Wed, 21 Oct 2025 07:28:00 GMT

Benefits

• Avoid Hard-Coding Quota Values: Fully rely on API response headers for rate limits, eliminating the need to hard-code numbers.
• Adapt to Provider Rules: Some API providers only return response headers without supplying explicit quota values. This adaptation ensures compliance with their rules.