Skip to main content

RewriteRegex

RewriteRegex middleware​

The rewriteRegex middleware allows dynamic rewriting of URL paths using regular expressions. It is ideal for complex rewrite rules that cannot be handled by simple string-based rewrites.

How It Works:​

  • Interception: The rewriteRegex middleware intercepts incoming requests and evaluates the URL path.
  • Pattern Matching: The middleware checks the path against a specified regular expression (pattern).
  • Rewrite Action: If the pattern matches, the middleware rewrites the path using the provided replacement.

Example: RegexRewrite Middleware Configuration​

Here’s an example of a RegexRewrite middleware configuration in YAML:

middlewares:
  - name: rewrite-oldpath-to-newpath
    type: rewriteRegex
    rule:
      pattern: ^/oldpath/(.*)
      replacement: /newpath/$1

In this example:

  • The middleware matches URLs starting with /oldpath/ followed by any characters (.*).
  • The matched portion after /oldpath/ is captured and referenced in the replacement as $1.
  • The resulting path is rewritten to /newpath/{captured_segment}.

Dynamic tokens​

In addition to regex capture groups ($1, $2, …), the replacement may reference values from the incoming request using {{goma.<source>.<name>}} placeholders:

TokenResolves to
{{goma.headers.<HeaderName>}}The value of the given request header.
{{goma.query.<ParamName>}}The value of the given URL query parameter.

Notes:

  • Whitespace inside the braces is tolerated, e.g. {{ goma.query.workspace }}.
  • A missing header or query parameter resolves to an empty string.
  • Token values are URL-path-escaped, so each token always expands to a single path segment. A client-supplied value such as ../../admin cannot inject extra / separators or traverse the path — it becomes ..%2F..%2Fadmin.
  • Tokens are expanded after the regex replacement, so a header or query value containing $1 is never treated as a capture-group reference.
middlewares:
  - name: rewrite-with-tokens
    type: rewriteRegex
    rule:
      pattern: ^/v2/[^/]+/(.*)
      # Header value routes the request; query param selects the environment.
      replacement: /v2/{{goma.headers.X-Workspace-Id}}/{{goma.query.env}}/$1

For a request POST /v2/acme/frontend/blobs?env=prod with header X-Workspace-Id: ws_1, the path is rewritten to /v2/ws_1/prod/frontend/blobs.

When to Use RewriteRegex​

  • When simple rewrites (like those handled by the rewrite property) are not enough.
  • When you need to handle dynamic path segments or complex patterns.

For straightforward rewrites, consider using the route rewrite property instead to reduce complexity.