Flows are YAML configurations that define how the Lunar.dev Gateway should handle requests—from matching incoming paths to applying logic like rate limiting, tool invocation, or response shaping. Each flow combines filters, processors, and a routing graph to control how requests and responses move through the system.

Flow Example

This example shows a working flow that applies rate limiting to all incoming requests using a quota and conditionally generates a 429 - Rate limit exceeded. Please try again later. response when the limit is exceeded.

id: simple-rate-limit-flow # name of your flow

filter:
  path: "*"   # The filter to determine if a request enters this flow or not.

processors:
  RateLimiter: # Unique identifier for the processor 
    processor: Limiter # Processor type. e.g., Limiter, GenerateResponse, Filter$
    parameters: # A list of parameters that for your Processor. 
      - key: quota_id 
        value: my-quota # The quota id that is defined in your Quota file
    metrics: # optional to also add metrics for each processor 
      enabled: true # if enabled will send 
      labels: # select labels to send in addition to processor-specific metrics
        - flow_name
        - processor_key
        - http_method
        - host
        - status_code
        - consumer_tag  # Enables consumer tracking on a per-processor basis

  GenerateResponseLimitExceeded: # Unique identifier for the processor 
    processor: GenerateResponse # Processor type. This can be from one of the existing processors
    parameters: # A list of parameters that for your Processor.
      - key: status
        value: 429
      - key: body
        value: "Rate limit exceeded. Please try again later."
      - key: Content-Type
        value: text/plain
    metrics: # optional to also add metrics for each processor 
      enabled: true # if enabled will send 
      labels: # select labels to send in addition to processor-specific metrics
        - flow_name
        - processor_key
        - http_method
        - host
        - status_code
        - consumer_tag  # Enables consumer tracking on a per-processor basis

flow: # this is the start of the flow graph where you can follow a request thru the different options.
  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

Components Breakdown

Filter

The flow uses a stream filter with url: "*" to apply this logic to every request entering the gateway.

Processors

Two processors are defined:

• Limiter — checks the request against your Quota (my-quota)
• GenerateResponse — returns a 429 status with a plain text message when the quota is exceeded

These are declared in the processors block and referenced by name in the flow graph.

You can also enable processor-level metrics by adding a metrics: block directly within each processor definition. This allows you to track detailed runtime metrics for that specific processor, including request patterns, response codes, and per-consumer activity.

Adding this block enables fine-grained observability for each processor and is especially useful when you're tracking quota enforcement or response behavior across different consumers or API clients.

Graph

The flow graph defines how requests and responses move through the system. It’s divided into two parts: request and response.

In the request path:

• All requests enter through the globalStream at start
• The Limiter processor checks if the request is above or below the quota
  • If above the limit, the flow routes to the GenerateResponse processor to return a generated 429
  • If below the limit, the request continues to the backend via the globalStream at end

In the response path:

• If a 429 response was generated, it is sent back to the client
• Otherwise, the response generated by the Provider will be sent to the client

Flow routing is done using from and to steps, with optional conditions like above_limit and below_limit to branch execution based on processor output.