Flow 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)
• expressions: JSONPath expressions in the API Request or Response

/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
  expressions: 
    - $.request[?(@.method == 'POST' || @.method == 'GET')] # Example of JSONPath from the request stream
    - $.response[?(@.status >= 200 && @.status <= 300)] # Example of JSONPath from the response stream

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

# Another example with an IP in the URL instead of a DNS
filter:
  url: 154.245.12.5/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.