Flows Components

To take full advantage of Lunar.dev Flows' capabilities, you'll need to understand its core elements.

Lunar Flows use a modular framework, allowing for precise control over API traffic. API Streams—both requests and responses—are segmented into sub-streams using filters based on parameters like URL, HTTP method, or headers. This segmentation ensures focused traffic management.

Processors operate on streams, performing tasks such as rate limiting, modifying traffic, or generating responses. Flows are collections of processors connected in sequence through from and to definitions, creating flexible traffic control pipelines.

This modular approach allows flows to call other flows, enabling scalable, customizable API management that adapts to evolving traffic needs. By structuring traffic into reusable components, Lunar Flows ensure efficient, secure, and adaptable API consumption strategies.

For more details, including how key elements like streams, filters, and processors interact, refer to the Flow Structure page.

---

API Streams

API Streams

An API stream represents the traffic flow, either in API requests or API responses. These streams are divided into two main types:

• API Request Stream: Represents all incoming API requests.
• API Response Stream: Represents all outgoing API responses.

Both request and response streams can be broken down into sub-streams defined by applying filters. These sub-streams allow for more focused traffic management, ensuring specific portions of the traffic are handled according to predefined rules.

API Stream Filter

API Stream Filter

A stream filter defines how traffic is segmented into sub-streams. Filters can be based on various parameters, such as:

• url: API provider (URL) and specific endpoint (with wildcards or specific paths)
• method: HTTP methods (e.g., POST, GET)
• headers: header (key-value pairs)

/etc/lunar-proxy/flows/flow.yaml

# Stream Filter Example: Define the criteria for filtering API traffic
filter:
  url: api.example.com/v1/* # Filter by URL pattern
  method: 
    - POST # Example of filtering by HTTP method
  headers:
    - key: x-lunar-consumer-tag # Filter by header key
      value: premium # Example header value
    - key: x-lunar-consumer-tag # Filter by header key
      value: basic # Example header value

Use Case Example: In this setup, POST requests to api.example.com/v1/* are segmented based on whether they come from premium or basic users. This could be used in scenarios where you want to apply stricter rate limits to basic users but allow premium users to access the API more frequently.

For example, with this filter in place, you can implement separate rate-limiting rules for premium and basic users by associating different processors for each segment of traffic, enabling tailored traffic management.

Wildcards and Domain Matching

When using wildcards in Stream Filters, you don't need to use regular expressions. Wildcards like *.api.example.com are accepted and make it easy to define patterns that match multiple subdomains or paths.

For instance, using a wildcard like:

/etc/lunar-proxy/flows/flow.yaml

# Stream Filter Example: Define the criteria for filtering API traffic
filter:
  url: *.api.example.com # Filter by URL pattern
  method: 
    - POST # Example of filtering by HTTP method

is perfectly valid and covers all subdomains such as dev.api.example.com or test.api.example.com, without the complexity of regex.

This makes configuring filters more straightforward and user-friendly for scenarios where you need flexible matching across domains or URL patterns.

Flow Processors

Flow Processors

A processor applies logic to traffic within a stream. Processors can modify, log, or count traffic, among other operations. Each processor reads from an input stream and sends its output to an output stream.

The following code snippet demonstrates the range of available processors in the system, showcasing their different capabilities, including filtering, rate limiting, queuing, and generating responses.

Processor Examples:

1. Limiter Processor

   The Limiter processor applies rate limiting to manage API traffic and ensure quotas are not exceeded. For example, you can define a quota for API usage and limit the number of requests allowed per user or service. If the quota is reached, the traffic is throttled or rejected.

/etc/lunar-proxy/flows/flow.yaml

Limiter:
  processor: Limiter
  parameters:
    - key: quota_id
      value: MyQuota  # The quota ID for rate limiting

Use Case: Limit premium users to 1,000 API calls per day. If they exceed the limit, subsequent requests are blocked.

2. Filter Processor

   The Filter processor allows traffic segmentation based on various criteria such as domains, headers, or request methods. This is useful for applying different rules or limits based on who is making the request.

/etc/lunar-proxy/flows/flow.yaml

Filter:
  processor: Filter
  parameters:
    - key: header
      value: X-Domain-Access=<any-value>

Use Case: Block traffic from specific domains while allowing access from trusted ones.

3. Queue Processor

   The Queue processor manages traffic by placing requests in a queue when the system is overloaded. It helps maintain smooth traffic flow by queuing excess requests instead of rejecting them outright.

   

   /etc/lunar-proxy/flows/flow.yaml

   Queue:
     processor: Queue
     parameters:
       - key: quota_id
         value: MyQueue  # The quota ID for queuing
       - key: ttl_seconds
         value: 60  # Requests in queue live for 60 seconds
       - key: queue_size
         value: 100  # Maximum queue size
       - key: priority_group_by_header
         value: x-Consumer-Group  # Prioritize requests based on a header
       - key: priority_groups
         value:
           premium: 1  # Premium users get highest priority
           basic: 2  # Basic users have lower priority

   Use Case: When your API is handling more requests than it can process, queue up the lower-priority basic users while giving priority to premium users.

4. GenerateResponse Processor

   The GenerateResponse processor is used to return custom responses to users, especially when certain conditions (such as quota exhaustion or queue limit reached) are met.

   /etc/lunar-proxy/flows/flow.yaml

   GenerateResponse:
     processor: GenerateResponse
     parameters:
       - key: status
         value: 429  # HTTP status code for quota or queue limit exceeded
       - key: body
         value: "Quota Exceeded. Please try again later."  # Custom response message
       - key: Content-Type
         value: text/plain  # Set content type for the response

   Use Case: When a user exceeds their quota, send a custom response informing them that their request has been rejected with a 429 status.