Url Rewriting

Regex-based path transformation and query string manipulation

Category: Practical
Task: Regex-based path transformation and query string manipulation

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

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

Download the source file.

Companion resources from the same snapshot:

# URL Rewriting
#
# Regex-based path transformation and query string manipulation.
#
# Operations execute in declared order:
#
#   /v1/users?api-version=2024-01&user=alice&debug=true
#        |
#        v
#   +------------------------------+
#   | regex_replace                |  /v1/users -> /v2/users
#   +------------------------------+
#        |
#        v
#   +------------------------------+
#   | preserve_query_params_only   |  keeps only api-version and user
#   +------------------------------+
#        |
#        v
#   +------------------------------+
#   | add_query_params             |  appends source=gateway
#   +------------------------------+
#        |
#        v
#   /v2/users?api-version=2024-01&user=alice&source=gateway
#
# preserve_query_params_only is an allowlist: keep only these params, drop
# everything else. For targeted removal use strip_query_params (a denylist).
# See url-rewriting-preserve.yaml for a focused preserve example.
#
# Usage:
#   cargo run -p praxis-proxy -- -c examples/configs/transformation/url-rewriting.yaml
#   curl "http://localhost:8080/v1/users?api-version=2024-01&user=alice&debug=true"
#   # Request reaches backend as /v2/users?api-version=2024-01&user=alice&source=gateway
#
# NOTE: The router checks rewritten_path before the original
# URI, so "rewrite then route" pipelines work: place a rewrite
# filter before the router and the router will match against
# the rewritten path.
#
# If both path_rewrite and url_rewrite appear in the same
# pipeline, only the last one's rewrite takes effect.
# Validation rejects this by default; set
# allow_rewrite_override: true on the later filter to permit
# it. Security consideration: filter order matters; the last
# rewrite wins, so misordering can bypass path-based ACLs.

listeners:
  - name: default
    address: "127.0.0.1:8080"
    filter_chains:
      - main

filter_chains:
  - name: main
    filters:
      - filter: url_rewrite
        operations:
          - regex_replace:
              pattern: "^/v1/(.*)"
              replacement: "/v2/$1"
          - preserve_query_params_only:
              - api-version
              - user
          - add_query_params:
              source: gateway

      - filter: router
        routes:
          - path_prefix: "/"
            cluster: backend

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

insecure_options:
  allow_private_endpoints: true # example proxies to local backends