Skip to main content

URL Rewrite

Overview​

The URL Rewrite Traffic Policy action allows you to modify the incoming request URL using regular expressions before it reaches the upstream server, while keeping the URL seen by the client unchanged.

This action is particularly useful for routing users without exposing internal system details.

Configuration Reference​

This is the Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request

Type​

url-rewrite

Configuration Fields​

  • fromstringCEL

    A regular expression pattern used to match a part of the URL.

    Supports CEL Interpolation.

  • tostringRequiredCEL

    A regular expression pattern used to replace the matched part of the URL.

    Supports CEL Interpolation.

Behavior​

This action replaces all occurrences of the from regular expression in the request URL with the to replacement value.

Matching​

Matching is performed against the entire URL, including the scheme, userinfo, host, and port, not just the path.

To match requests that begin with /products, use CEL Interpolation and write ^${req.url.authority}/products, or use an expression like req.url.path.startsWith('/products') in the phase rule's expressions field.

Note about CEL Interpolation​

All CEL Interpolation will occur before regular expressions are evaluated.

Examples​

Rewrite using Paths​

The following Traffic Policy configuration demonstrates how to use the url-rewrite action to transparently rewrite the request URL from /products to /products.php.

Example Traffic Policy Document​

---
on_http_request:
  - expressions:
      - "req.url.path == '/products'"
    actions:
      - type: "url-rewrite"
        config:
          from: "/products"
          to: "/products.php"

This configuration will rewrite any request to /products to /products.php without changing the URL seen by the client. This is useful for hiding away the underlying implementation details of your service.

Example Request​

$ curl -i https://example.ngrok.app/products
HTTP/2 200 OK
Example Server Logs​
GET /product.php               200 OK

Conclusion​

In this example, a request to /products is internally routed to /products.php, and the response is served from products.php while the client remains unaware of the URL rewrite.

Rewrite using Regular Expressions​

The following Traffic Policy configuration demonstrates how to use the url-rewrite action to transparently rewrite the request URL from /products/* to /products.php.

Example Traffic Policy Document​

---
on_http_request:
  - expressions:
      - "req.url.path.startsWith('/products')"
    actions:
      - type: "url-rewrite"
        config:
          from: "/products/?([.*]+)?"
          to: "/products.php?query=$1"

This configuration will rewrite any request to /products/* to /products.php?query=$1 without changing the URL seen by the client. This is useful for hiding away the underlying implementation details of your service.

Example Request​

$ curl -i https://example.ngrok.app/products/123
HTTP/2 200 OK
Example Server Logs​
GET /product.php?query=123          200 OK

Conclusion​

In this example, a request to /products is internally routed to /products.php?query=123, and the response is served from products.php while the client remains unaware of the URL rewrite.

Rewrite using CEL Interpolation​

The following Traffic Policy configuration demonstrates how to use the url-rewrite action to transparently rewrite the request URL from /products/* to /products.php using a global policy rule (no expression) by leveraging CEL Interpolation.

Example Traffic Policy Document​

---
on_http_request:
  - actions:
      - type: "url-rewrite"
        config:
          from: "${req.url.authority}/products/?([.*]+)?"
          to: "/products.php?query=$1"

This configuration will rewrite any request urls that start with /products/* to /products.php?query=$1 without changing the URL seen by the client. It does this by leveraging CEL Interpolation to replace the from value with the request URL authority. This is useful for hiding away the underlying implementation details of your service.

Example Request​

$ curl -i https://example.ngrok.app/products/123
HTTP/2 200 OK
Example Server Logs​
GET /product.php?query=123          200 OK

Conclusion​

In this example, a request to /products is internally routed to /products.php?query=123, and the response is served from products.php while the client remains unaware of the URL rewrite.

Action Result Variables​

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

  • actions.ngrok.url_rewrite.matchesarray of strings

    List of elements that matched the URL before the rewrite action was applied. These can be specific parts of the URL, such as the domain, path, or query parameters, that were matched based on the action configuration.

  • actions.ngrok.url_rewrite.urlstring

    The final URL after the rewrite action has been applied. This is the new URL to which the original request is redirected after the specified modifications have been made.

  • actions.ngrok.url_rewrite.error.codestring

    A machine-readable code describing an error that occurred during the action's execution.

  • actions.ngrok.url_rewrite.error.messagestring

    A human-readable message providing details about an error that occurred during the action's execution.