Shaping Requests at the Edge Without Workers

Applications often need their incoming HTTP requests shaped in specific ways before processing: URLs normalized to a consistent format, paths and query strings rewritten based on conditions, or headers added to carry context about the client. Running this logic on origin servers adds complexity and overhead. Cloudflare's Transform Rules offload these common request modifications to the edge, providing a simpler alternative to writing and maintaining Cloudflare Workers code for routine tasks.

Transform Rules cover three primary functions:

  • URL Normalization: Converts request URLs to a standard, unencoded format before security features evaluate them.
  • URL Rewrite: Performs static or dynamic rewrites of the URL path and query string based on request attributes.
  • Header Modify: Adds or removes static or dynamic headers on requests destined for the origin.

Why Encoding Matters for Security Rules

A key motivation behind URL Normalization is preventing encoded URLs from bypassing security controls. Attackers frequently percent-encode path segments to evade firewall rules. For instance, a rate limiting rule targeting /login could be circumvented by sending requests to /%6cogin, which decodes to the same path.

With URL Normalization enabled, Cloudflare decodes the incoming URL to a standard format before executing security features like rate limiting. This ensures rules match against the canonical path. By default, normalization is applied at Cloudflare's edge for all zones but disabled when forwarding requests to origins. This configuration allows security products to operate on normalized URLs while the origin server still receives the original, unmodified URL. Settings can be adjusted via the Cloudflare dashboard or API to suit specific needs.

Rewrites vs. Redirects

It's important to distinguish URL Rewrites from URL Redirects. A rewrite is a server-side modification that occurs before the request is processed by the web server; it is transparent to the end user and does not change the URL displayed in the browser. A redirect, in contrast, sends the client to a new location via a 301 or 302 status code, which updates the browser's address bar. Redirects can be implemented with Cloudflare Page Rules, while Transform Rules handle rewrites.

URL rewrites execute before other Cloudflare products such as Firewall Rules, Page Rules, and Workers. Rewrites function with static strings or dynamic expressions based on request attributes like country of origin, referrer, or URL path segments.

Static Rewrite Example

Consider a scenario where visitors to www.example.com with a cookie version=v1 should see content from the /v1 directory. A static rewrite can send the origin server a request for www.example.com/v1 while the user's browser continues to show www.example.com. This approach is useful for A/B testing new content versions.

Dynamic Rewrite: Prefixing Paths

Dynamic rewrites can apply logic based on incoming request patterns. For example, a rule could rewrite all URLs by prepending /v1/ when the version=v1 cookie is present. Visiting www.example.com/Literaturelibrary/book1314 would result in the origin receiving www.example.com/v1/Literaturelibrary/book1314. Similarly, a deeper path like www.example.com/fictionlibrary/book52/line43/universe becomes www.example.com/v1/fictionlibrary/book52/line43/universe. The browser URL stays unchanged; only the origin request is modified.

Dynamic Rewrite: Path and Query Replacement

Another use case involves both path and query string changes. A rule could replace the leading /global segment with /v1 and swap the query parameter page=1 for newpage=1, conditional on the version=v1 cookie. Under this rule, www.example.com/global/Literaturelibarary/book1013?page=1 would be rewritten to www.example.com/v1/Literaturelibarary/book1013?newpage=1. Longer paths like www.example.com/global/fictionlibarary/book52/line43/universe?page=1 receive the same treatment, resulting in www.example.com/v1/fictionlibarary/book52/line43/universe?newpage=1.

Managing Request Headers

Adding or removing request headers is another popular Transform Rule use case. Configurations allow for static header values, dynamic values derived from request attributes such as geolocation data, and non-string values. For instance, a rule can add a static header Foo: bar when the request hostname is www.example.com, so the origin server observes that header on matching requests.

Dynamic headers are useful for passing computed fields like the end user's country to the origin. Special support is also available for Cloudflare Bot Management customers: the bot score, an integer from 1 to 99 indicating the likelihood of a request being automated, can be attached as a request header via Transform Rules for consumption by origin applications.

Simplifying Request Transformation

Transform Rules bring URL Normalization, URL Rewrites, and HTTP header modification into a unified, script-free interface. By handling these tasks at the edge, they reduce the burden on origin infrastructure and offer a practical drop-in solution for common request-shaping workflows. The rules are available for configuration in the Cloudflare dashboard.