Conditional Filters

Filters support conditions (request phase) and response_conditions (response phase) to gate execution

Category: Practical
Task: Filters support conditions (request phase) and response_conditions (response phase) to gate execution

Prerequisites: The product runtime and any backend services referenced by this configuration.

Run it: Use ghcr.io/praxis-proxy/praxis:0.7.2 and follow the first reverse-proxy tutorial to mount and start the configuration.

This configuration comes from the selected release. The example has not been run here; external services are not bundled.

Download the source file.

# Conditional Filter Execution
#
# Filters support `conditions` (request phase) and `response_conditions`
# (response phase) to gate execution. Two operators:
#
#   when:   run ONLY IF all predicates match
#   unless: SKIP IF any predicate matches
#
# Condition evaluation flow:
#
#   Request arrives
#        |
#        v
#   +-----------+     all match      +-------------+
#   | when: [A] |  ───────────────►  | Run filter  |
#   +-----------+                    +-------------+
#        |                                 |
#        | any miss                        v
#        v                           +-----------+     any match
#   +------------+                   | unless: B |  ──────► Skip
#   | Skip filter|                   +-----------+
#   +------------+                         |
#                                          | no match
#                                          v
#                                    +-------------+
#                                    | Run filter  |
#                                    +-------------+
#
# Request predicates: path, path_prefix, methods, headers.
# Response predicates: status, headers.
# Multiple conditions are ANDed.
#
# Three patterns demonstrated here:
#   1. timeout on /api/ only; health checks exempt
#   2. request header injected on mutations only
#   3. Cache-Control set only on successful responses
#
listeners:
  - name: default
    address: "127.0.0.1:8080"
    filter_chains:
      - main

filter_chains:
  - name: main
    filters:
      - filter: router
        routes:
          - path_prefix: "/"
            cluster: backend

      # 5 s SLA on API calls; health checks exempt.
      - filter: timeout
        timeout_ms: 5000
        conditions:
          - when:
              path_prefix: "/api/"
          - unless:
              path_prefix: "/healthz"

      # Tag mutations so backends can distinguish gateway traffic.
      - filter: headers
        request_add:
          - name: "X-Internal-Source"
            value: "gateway"
        conditions:
          - when:
              methods: ["POST", "PUT", "PATCH", "DELETE"]

      # Cache-Control only on successful responses.
      - filter: headers
        response_set:
          - name: "Cache-Control"
            value: "public, max-age=60"
        response_conditions:
          - when:
              status: [200]

      - filter: load_balancer
        clusters:
          - name: backend
            endpoints:
              - "127.0.0.1:3000"

insecure_options:
  allow_private_endpoints: true # example proxies to local backends