Skip to main content
Version: Next

Client Side Limiting Flow

The Client-Side Limiting Flow regulates API traffic by enforcing predefined Quotas within the flow. This ensures that API usage stays within limits, preventing overconsumption and maintaining stable integration. The flow dynamically manages requests and provides appropriate responses when quotas are exceeded using the Limiter and GenerateResponse processors.

Flow Diagram

Scenarios​

  1. Quota Enforcement: The flow applies traffic limits based on configured quotas, ensuring that API requests adhere to predefined thresholds for visibility and management.
  2. Custom Responses: Configure specific messages or status codes when limits are reached, giving users clear feedback on quota breaches.
  3. Quota Segmentation: The flow enforces quotas based on attributes like headers or URLs, allowing for granular traffic control, such as setting different limits for production and staging environments.
  4. Noisy Neighbor Prevention: Ensure that high-traffic clients do not negatively impact others by enforcing client-specific quotas within the flow.
  5. Proactive Client-Side Throttling: Protect API provider resources by enforcing traffic limits directly on the client side, ensuring responsible and efficient API consumption.

Flow Configuration Template​

/etc/lunar-proxy/flows/flow.yaml
name: <FlowName> # The name of the flow, e.g., ClientSideLimitingFlow

filter:
  url: <URLPattern> # Define the URL pattern for the filter, e.g., api.example.com/*, 195.458.125.1/*
  method: ["<HTTPMethod>"] # Optional: List of HTTP methods, e.g., GET, POST
  headers:
    - key: <HeaderKey> # Optional: Header key, e.g., 'X-API-Key'
      value: <HeaderValue> # Optional: header value, e.g., '12345', '67890'

processors:
  Limiter:
    processor: Limiter # Limiter processor for rate limiting
    parameters:
      - key: quota_id
        value: <QuotaID> # Specify the quota ID, e.g., MyQuota

  GenerateResponse:
    processor: GenerateResponse # Generate a response when a limit is exceeded
    parameters:
      - key: status
        value: 429 # HTTP status code for quota exceeded, e.g., 429 (Too Many Requests)
      - key: body
        value: "Quota Exceeded. Please try again later." # Response body text
      - key: Content-Type
        value: text/plain # Content type for the response

flow:
  request:
    - from:
        stream:
          name: globalStream # The stream to start the request flow
          at: start # Start point
      to:
        processor:
          name: Limiter # Process the request through the Limiter processor

    - from:
        processor:
          name: Limiter # After the Limiter processor
          condition: above_limit # If the request is blocked due to quota exceeded
      to:
        processor:
          name: GenerateResponse # Generate the 429 response

    - from:
        processor:
          name: Limiter # After the Limiter processor
          condition: below_limit # If the request is allowed (below quota limit)
      to:
        stream:
          name: globalStream # Send the request to the global stream
          at: end # End point of the request flow

  response:
    - from:
        processor:
          name: GenerateResponse # In case of quota exceeded, send the response
      to:
        stream:
          name: globalStream # Send response back to the global stream
          at: end # End point of the response flow

Flow Example​

  • API requests to httpbin.com/* are throttled with a maximum of 100 requests per minute.
  • If the quota is exceeded, the flow returns a 429 HTTP status code along with the message: "Quota Exceeded. Please try again later."
/etc/lunar-proxy/flows/flow.yaml
name: ClientSideLimitingFlow

filter:
  url: httpbin.com/*
processors:
  RateLimiter:
    processor: Limiter
    parameters:
      - key: quota_id
        value: MyQuota
  GenerateResponseLimitExceeded:
    processor: GenerateResponse
    parameters:
      - key: status
        value: 429
      - key: body
        value: "Quota Exceeded. Please try again later."
      - key: Content-Type
        value: text/plain
flow:
  request:
    - from:
        stream:
          name: globalStream
          at: start
      to:
        processor:
          name: RateLimiter

    - from:
        processor:
          name: RateLimiter
          condition: above_limit
      to:
        processor:
          name: GenerateResponseLimitExceeded

    - from:
        processor:
          name: RateLimiter
          condition: below_limit
      to:
        stream:
          name: globalStream
          at: end

  response:
    - from:
        processor:
          name: GenerateResponseLimitExceeded
      to:
        stream:
          name: globalStream
          at: end
/etc/lunar-proxy/quota/quota.yaml
quotas:
  - id: MyQuota
    filter:
      url: httpbin.com/*
    strategy:
      fixed_window:
        static:
          max: 100
          interval: 1
          interval_unit: minute

Flow Components​