Rewrite Rules

Rewrite Rules allow you to transform incoming URLs before any other processing happens. They work like nginx rewrite rules, enabling URL normalization, legacy URL support, and clean URL structures.

Rewrite Rules: transform incoming URLs before processing.

What are Rewrite Rules?

Rewrite Rules modify the request URL based on pattern matching. They're evaluated early in the request flow, right after Access Rules and before Conditional Rules, ensuring that URL transformations happen before configuration rules evaluate the URL.

Key characteristics:

• Execute second in the rule sequence (after Access Rules, before Conditional Rules)
• Transform URLs before cache lookup
• nginx-style URL rewriting
• Evaluated in position order (1, 2, 3...)
• Stop after first match - once a rule matches, no further Rewrite Rules are evaluated

The Create Rewrite Rule form: name, description, match type, URI pattern and target path.

How Rewrite Rules Work

Rewrite Rules are evaluated in ascending position order (1 -> 2 -> 3...) for every incoming request. When a rule's URL pattern matches, the URL is rewritten to the target path and evaluation stops.

Position-Based Evaluation

Request: /old-path
    |
Rewrite Rule (Position 1) -> Match /old-path? -> Rewrite to /new-path -> STOP
    | (no match)
Rewrite Rule (Position 2) -> Match? -> Rewrite -> STOP
    | (no match)
Continue to Conditional Rules with original or rewritten URL...

Important: Once a Rewrite Rule matches, no further Rewrite Rules are evaluated. The rewritten URL is then used by all subsequent Conditional Rules.

URL Matching

Rewrite Rules match URLs using three different matchers:

The Match Type dropdown: Equals, regular expression and case-insensitive regex.

Matchers

Equals (=): Exact match

Matcher: Equals
URL: /old-page
Target: /new-page

Matches: /old-page
Doesn't match: /old-page/, /old-page?query=1, /old-page-extra

Regular Expression (~): Case-sensitive regex

Matcher: Regular Expression
URL: ^/blog/(\d+)
Target: /articles/$1

Matches: /blog/123 -> /articles/123
Doesn't match: /BLOG/123 (case-sensitive)

Case-insensitive Regex (~*): Case-insensitive regex

Matcher: Case-insensitive Regex
URL: ^/products/(.*)
Target: /shop/$1

Matches: /products/item -> /shop/item
Also matches: /PRODUCTS/item -> /shop/item

URL vs URI

• URL: The complete web address including protocol and domain
  • Example: https://www.example.com/category/data.html
• URI: Just the path without domain or protocol
  • Example: /category/data.html

Rewrite Rules work with URIs (the path only).

When to Use Rewrite Rules

Use Rewrite Rules When:

• You need to support legacy URLs while restructuring your site
• You want clean, SEO-friendly URLs (e.g., /product/123 instead of /product.php?id=123)
• You're migrating from another platform and need to maintain old URL structures
• You need URL normalization (e.g., remove trailing slashes, lowercase URLs)
• URL transformations should happen before other rules evaluate

Rewrite rules also power smoxy's on-the-fly image processing - they map clean, public URLs onto the /_sx/img/... processing paths.

Use Cases & Examples

Example 1: Legacy URL Support

Scenario: You've restructured your site from /old-section/page.html to /new-section/page, but need to support old links.

Position: 1
Matcher: Regular Expression
URL: ^/old-section/(.*)\.html$
Target: /new-section/$1

Result:
/old-section/about.html -> /new-section/about
/old-section/contact.html -> /new-section/contact

Why rewrite instead of redirect? Rewrites are transparent - the user doesn't see the URL change, and you maintain the original request context. Conditional Rules can then apply configurations based on the new URL.

Example 2: Clean URL Structure

Scenario: Your application uses query parameters, but you want clean URLs for SEO.

Position: 1
Matcher: Regular Expression
URL: ^/product/([0-9]+)$
Target: /product.php?id=$1

Result:
/product/12345 -> /product.php?id=12345
(Clean URL is rewritten to actual backend URL)

Why this works: Users and search engines see clean URLs (/product/12345), but your backend receives the query parameter format it expects.

Example 3: Platform Migration

Scenario: Migrating from WordPress to a new platform and need to support old post URLs.

Position: 1
Matcher: Regular Expression
URL: ^/([0-9]{4})/([0-9]{2})/(.*)$
Target: /posts/$1-$2-$3

Result:
/2024/03/my-blog-post -> /posts/2024-03-my-blog-post
/2023/12/another-post -> /posts/2023-12-another-post

Combined with Conditional Rules: After the rewrite, a Conditional Rule matching /posts/* can apply specific caching or optimization settings.

Target Path

The Target Path is where the URL gets rewritten to. It can be:

• Static path: /new-location
• With capture groups: /section/$1 (uses regex capture groups from the URL pattern)
• Multiple captures: /category/$1/item/$2

Important: The target path is the actual backend path your application will receive. Make sure it's a valid path your application can handle.

Rule Order Best Practices

Since Rewrite Rules stop on first match, order them carefully. For how rewrite ordering fits into the overall pipeline, see Execution & Ordering.

1. Most Specific First

Position 1: /exact/specific/path -> /target1
Position 2: /specific/* -> /target2
Position 3: /* -> /target3

2. Exact Matches Before Patterns

Position 1: = /special-page -> /new-special
Position 2: ~ ^/special -> /regular-special

3. Consider Downstream Rules

Remember that Conditional Rules will evaluate against the rewritten URL, not the original:

Rewrite Rule: /old/* -> /new/*
Conditional Rule: Match /new/* (not /old/*)

4. Consolidate Similar Patterns

Use regex to handle multiple cases efficiently:

Less efficient (multiple rules):

/old-about -> /about
/old-contact -> /contact
/old-help -> /help

More efficient (single rule):

^/old-(.*)$ -> /$1

Use regex for flexibility:

Multiple specific rules:

/product-1 -> /item/1
/product-2 -> /item/2
...

Single flexible rule:

^/product-([0-9]+)$ -> /item/$1

Uniqueness

Each zone must have unique:

• Rule names - each rule must have a unique name
• URL patterns - you cannot have duplicate URL patterns

If you try to create a duplicate, you'll see: "Name already exists" or "Same matcher exists."

Common Mistakes

Catch-all rewrite at position 1

Position 1: ~ ^/(.*)$ -> /new/$1
-> Rewrites EVERYTHING, other rules never match

Specific patterns first

Position 1: = /special -> /new-special
Position 2: ~ ^/blog/(.*)$ -> /articles/$1
Position 3: ~ ^/old-(.*)$ -> /$1

---

Forgetting about Conditional Rules

Rewrite Rule: /old-admin -> /admin
Conditional Rule: Match /old-admin/* -> NEVER MATCHES
Should match: /admin/*

Conditional Rules match rewritten URLs

Rewrite Rule: /old-admin -> /admin
Conditional Rule: Match /admin/* -> Matches after rewrite

---

Invalid target path

URL: ^/product/(.*)$
Target: /invalid/$2 (capture group $2 doesn't exist)
-> Broken rewrite

Valid capture groups

URL: ^/product/(.*)$
Target: /item/$1 (uses capture group $1)

Testing Rewrite Rules

1. Enable Debug Headers in your zone configuration
2. Make test requests with the original URLs
3. Check response headers to see which rules were applied and what the URL became
4. Verify Conditional Rules are matching the rewritten URL, not the original