Prefix match in Nginx - Deep Dive

Overview - Prefix match

What is it?

Prefix match in nginx is a way to decide which server block or location block should handle a web request based on the beginning part of the URL path. It checks if the requested URL starts with a specific string and uses that to route the request. This helps nginx serve different content or apply different rules depending on the URL prefix.

Why it matters

Without prefix matching, nginx would not know how to efficiently route requests to the right place based on URL patterns. This would make it hard to serve different parts of a website or application differently, leading to slower responses or incorrect content delivery. Prefix matching makes web servers flexible and fast by quickly deciding how to handle requests.

Where it fits

Before learning prefix match, you should understand basic nginx configuration and how server and location blocks work. After mastering prefix match, you can learn about more advanced matching methods like regular expressions and exact matches, and how nginx processes requests in order.

Mental Model

Core Idea

Prefix match means nginx looks at the start of a URL path to decide which configuration block should handle the request.

Think of it like...

It's like sorting mail by looking at the first few letters of the address to decide which mailbox to put it in.

Request URL path
  ↓
┌─────────────────────────┐
│ nginx checks prefixes   │
│ of location blocks      │
├─────────────┬───────────┤
│ /images     │ /api      │
│ (matches if│ (matches if│
│ URL starts │ URL starts│
│ with /images)│ with /api)│
└─────────────┴───────────┘
  ↓               ↓
Serve images    Serve API
content         requests

Build-Up - 6 Steps

1

Foundation

Understanding nginx location blocks

Concept: Learn what location blocks are and how they define handling rules for URL paths.

In nginx, a location block defines how to process requests for URLs that match a certain pattern. For example: location / { # rules here } This block matches all URLs starting with '/'. Location blocks help organize how nginx serves different parts of a website.

Result

You know that location blocks group rules for URL paths.

Understanding location blocks is essential because prefix matching happens inside these blocks.

2

Foundation

Basic prefix matching syntax

Concept: Learn how to write a prefix match in nginx using location blocks.

A prefix match is written simply as: location /prefix { # rules } This matches any URL path that starts with '/prefix'. For example, '/prefix/page' matches, but '/other' does not.

Result

You can write a location block that matches URLs starting with a specific prefix.

Knowing the syntax lets you control which requests nginx handles with which rules.

3

Intermediate

Longest prefix match rule

🤔Before reading on: do you think nginx uses the first matching prefix or the longest matching prefix? Commit to your answer.

Concept: Nginx chooses the location block with the longest matching prefix when multiple prefixes match.

If you have: location / { # rule A } location /images/ { # rule B } A request to '/images/pic.jpg' matches both prefixes, but nginx uses the longer '/images/' prefix block.

Result

Nginx routes requests to the most specific prefix match available.

Understanding longest prefix match prevents confusion when multiple location blocks could match a URL.

4

Intermediate

Prefix match vs exact and regex matches

🤔Before reading on: do you think prefix matches have higher priority than regex matches? Commit to your answer.

Concept: Nginx processes exact matches first, then prefix matches, then regex matches, affecting which block handles a request.

Nginx matching order: 1. Exact match (= prefix) 2. Longest prefix match 3. Regex matches (~ or ~*) So a regex match can override a prefix match if no exact match exists.

Result

You understand how prefix matches fit into nginx's matching priority.

Knowing this order helps you design nginx configs that behave as expected.

5

Advanced

Using prefix match with modifiers

🤔Before reading on: do you think adding '^~' changes how prefix matches behave? Commit to your answer.

Concept: The '^~' modifier tells nginx to stop searching if a prefix match is found, skipping regex checks.

Example: location ^~ /static/ { # serve static files } This means if URL starts with '/static/', nginx uses this block immediately without checking regex locations.

Result

You can control nginx's matching behavior to optimize performance and avoid unwanted regex matches.

Understanding '^~' lets you fine-tune nginx routing for speed and clarity.

6

Expert

Prefix match internals and performance impact

🤔Before reading on: do you think prefix matches are slower than regex matches? Commit to your answer.

Concept: Prefix matches are implemented as efficient string comparisons, making them faster than regex matches in nginx's request processing.

Nginx stores prefix matches in a tree structure for quick lookup. It compares URL path prefixes without complex pattern evaluation. Regex matches require full pattern evaluation, which is slower. Using prefix matches for common paths improves performance.

Result

You understand why prefix matches are preferred for common URL routing.

Knowing the internal efficiency guides you to write performant nginx configurations.

Under the Hood

Nginx parses the URL path of each request and compares it against location blocks. Prefix matches are stored in a tree-like structure allowing nginx to quickly find the longest matching prefix by traversing nodes corresponding to URL segments. This avoids scanning all locations. If a prefix match is found, nginx may continue to check regex locations unless the '^~' modifier is used to stop further checks.

Why designed this way?

Prefix matching was designed for speed and simplicity. Most web requests follow predictable URL patterns, so quick string prefix checks are efficient. Regex matching is more flexible but slower. The design balances performance and flexibility by prioritizing prefix matches and allowing regex only when needed.

Request URL path
  ↓
┌─────────────────────────────┐
│ nginx location tree lookup  │
├─────────────┬───────────────┤
│ /           │ /images/      │
│ (root node) │ (child node)  │
└─────────────┴───────────────┘
  ↓               ↓
Match longest prefix
  ↓
Check for '^~' modifier
  ↓
If no '^~', check regex locations
  ↓
Serve request

Myth Busters - 4 Common Misconceptions

Quick: Does nginx always use the first matching prefix location it finds? Commit to yes or no.

Common Belief: Nginx uses the first prefix location that matches the URL.

Reality: Nginx uses the longest matching prefix location, not the first one it finds.

Why it matters: Assuming the first match is used can cause unexpected routing, serving wrong content or rules.

Quick: Do prefix matches override exact matches? Commit to yes or no.

Common Belief: Prefix matches have higher priority than exact matches.

Reality: Exact matches have the highest priority and override prefix matches.

Why it matters: Misunderstanding this can lead to configs where exact matches are ignored, causing bugs.

Quick: Does adding '^~' to a prefix location allow regex locations to still be checked? Commit to yes or no.

Common Belief: The '^~' modifier does not affect regex matching order.

Reality: The '^~' modifier stops nginx from checking regex locations if the prefix matches.

Why it matters: Ignoring '^~' effects can cause performance issues or unexpected regex matches.

Quick: Are prefix matches slower than regex matches? Commit to yes or no.

Common Belief: Prefix matches are slower because they check strings multiple times.

Reality: Prefix matches are faster because they use efficient tree lookups and simple string comparisons.

Why it matters: Believing prefix matches are slow may lead to overusing regex and hurting performance.

Expert Zone

1

Prefix matches are case-sensitive by default, which can cause subtle bugs if URLs vary in case.

2

The trailing slash in prefix matches matters: '/images' and '/images/' can match different requests.

3

Using '^~' disables regex checks but does not prevent exact matches from overriding the prefix match.

When NOT to use

Prefix match is not suitable when you need complex pattern matching like wildcards or optional parts. In those cases, use regex locations (~ or ~*). Also, prefix matches cannot handle query strings or headers; use other nginx modules or directives for those.

Production Patterns

In production, prefix matches are used to route static content (e.g., '/static/'), API endpoints (e.g., '/api/'), or admin panels (e.g., '/admin/'). The '^~' modifier is often applied to static content locations to improve performance by skipping regex checks.

Connections

Trie data structure

Prefix matching in nginx uses a tree structure similar to a trie for efficient prefix lookup.

Understanding tries from computer science helps grasp how nginx quickly finds the longest prefix match.

URL routing in web frameworks

Prefix matching is a basic form of URL routing used in many web frameworks to map URLs to handlers.

Knowing nginx prefix match clarifies how routing works in frameworks like Express or Django.

Postal mail sorting

Prefix matching is like sorting mail by address prefixes to deliver to correct mailboxes.

This real-world sorting analogy helps understand how nginx routes requests efficiently.

Common Pitfalls

#1 Using prefix match without '^~' when regex locations exist

Wrong approach:

location /static/ {
# serve static files
}

location ~* \.(jpg|png)$ {
# regex for images
}

Correct approach:

location ^~ /static/ {
# serve static files
}

location ~* \.(jpg|png)$ {
# regex for images
}

Root cause:

Without '^~', nginx checks regex locations after prefix matches, possibly overriding intended static file handling.

#2 Assuming prefix matches are case-insensitive

Wrong approach:

location /Images/ {
# serve images
}

Correct approach:

location /images/ {
# serve images
}

Root cause:

Nginx prefix matches are case-sensitive, so '/Images/' does not match '/images/'.

#3 Overlapping prefix matches without understanding longest match

Wrong approach:

location / {
# general rules
}
location /app/ {
# app rules
}

# Request to /app/page uses '/' block

Correct approach:

location / {
# general rules
}
location /app/ {
# app rules
}

# Request to /app/page uses '/app/' block

Root cause:

Misunderstanding nginx picks the longest matching prefix leads to wrong expectations about which block handles requests.

Key Takeaways

Prefix match in nginx routes requests by checking if the URL path starts with a specific string.

Nginx chooses the longest matching prefix location block to handle a request when multiple prefixes match.

The '^~' modifier tells nginx to stop searching further if a prefix match is found, skipping regex checks.

Prefix matches are faster than regex matches because they use efficient string comparisons and tree lookups.

Understanding prefix match priority and behavior helps avoid common configuration mistakes and improves server performance.