Proxy cache key in Nginx - Step-by-Step Execution

Process Flow - Proxy cache key

Client Request Received

↓

Extract Cache Key Components

↓

Build Cache Key String

↓

Check Cache for Key

↓

Serve Cached

↓

Store Response

↓

Serve Response

The proxy cache key is built from parts of the client request to identify cached content. Nginx uses this key to find or store cached responses.

Execution Sample

Nginx

proxy_cache_key "$scheme://$host$request_uri";

This sets the cache key to the full URL including scheme, host, and request URI.

Process Table

Step	Action	Value of $scheme	Value of $host	Value of $request_uri	Constructed cache key	Cache lookup result	Next action
1	Receive request	https	example.com	/index.html			Start processing
2	Extract variables	https	example.com	/index.html			Variables ready
3	Build cache key	https	example.com	/index.html	https://example.com/index.html		Cache key formed
4	Check cache				https://example.com/index.html	Miss	Fetch from backend
5	Fetch response						Get fresh content
6	Store response in cache				https://example.com/index.html		Cache updated
7	Serve response						Response sent to client
8	Next request same key	https	example.com	/index.html	https://example.com/index.html	Hit	Serve cached content

💡 Cache key lookup ends after serving cached or fresh response.

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 6	After Step 8
$scheme		https	https	https	https
$host		example.com	example.com	example.com	example.com
$request_uri		/index.html	/index.html	/index.html	/index.html
cache_key			https://example.com/index.html	https://example.com/index.html	https://example.com/index.html
cache_status				Miss	Hit

Key Moments - 3 Insights

Why does the cache key include $scheme, $host, and $request_uri?

Including these variables ensures the cache key uniquely identifies the full URL requested, avoiding serving wrong cached content. See execution_table step 3 where the key is built.

What happens if the cache key is not found in cache?

Nginx fetches the content from the backend server, stores it in cache with the key, then serves it. This is shown in execution_table steps 4 to 7.

Can the cache key be customized?

Yes, you can include or exclude variables to control cache granularity. The example uses a simple full URL key, but you can add headers or cookies if needed.

Visual Quiz - 3 Questions

Look at the execution_table at step 3. What is the constructed cache key?

A https://example.com/

B http://example.com/index.html

C https://example.com/index.html

D /index.html

💡 Hint

Check the 'Constructed cache key' column at step 3 in the execution_table.

At which step does Nginx find a cache miss?

A Step 2

B Step 4

C Step 6

D Step 8

💡 Hint

Look at the 'Cache lookup result' column in the execution_table.

If the $host changes, what happens to the cache key?

A Cache key changes

B Cache key stays the same

C Cache key becomes empty

D Cache key is ignored

💡 Hint

Refer to variable_tracker for $host and cache_key values.

Concept Snapshot

proxy_cache_key directive builds a unique key from request parts.
Common variables: $scheme, $host, $request_uri.
Nginx uses this key to find or store cached responses.
Changing variables changes cache key and cache entries.
Proper key ensures correct cached content served.

Full Transcript

When Nginx receives a client request, it extracts parts like scheme, host, and request URI. These parts are combined to form a cache key string. Nginx checks if this key exists in the cache. If found (cache hit), it serves the cached content. If not found (cache miss), it fetches fresh content from the backend, stores it in cache with that key, and serves it. The cache key must uniquely identify the requested resource to avoid serving wrong content. You can customize the cache key by including different variables. This process ensures efficient and correct caching behavior.

Practice

1. What is the main purpose of the proxy_cache_key directive in nginx?

easy

A. To define how nginx identifies and stores cached content

B. To set the maximum size of the cache

C. To specify the cache expiration time

D. To enable SSL for proxy connections

Solution

1. Step 1: Understand the role of proxy_cache_key

   The proxy_cache_key tells nginx how to uniquely identify cached content by combining variables like scheme, host, and URI.

2. Step 2: Differentiate from other cache settings

   Other directives control cache size or expiration, but proxy_cache_key specifically defines the cache lookup key.

3. Final Answer:

   To define how nginx identifies and stores cached content -> Option A

4. Quick Check:

   proxy_cache_key = cache identifier [OK]

Hint: proxy_cache_key sets cache identity, not size or time [OK]

Common Mistakes:

• Confusing cache key with cache size or expiration
• Thinking it enables SSL
• Assuming it controls cache storage location

2. Which of the following is the correct syntax to set a proxy cache key using scheme, host, and request URI in nginx?

easy

A. proxy_cache_key $scheme$host$request_uri;

B. proxy_cache_key $scheme://$host$request_uri;

C. proxy_cache_key $scheme://host$request_uri;

D. proxy_cache_key "$scheme://$host$request_uri";

Solution

1. Step 1: Check syntax for proxy_cache_key

   The value must be a string, so it should be enclosed in double quotes if it contains special characters like ://.

2. Step 2: Verify variable usage

   Variables like $scheme, $host, and $request_uri must be concatenated properly inside quotes.

3. Final Answer:

   proxy_cache_key "$scheme://$host$request_uri"; -> Option D

4. Quick Check:

   Quotes needed for complex keys = proxy_cache_key "$scheme://$host$request_uri"; [OK]

Hint: Use quotes when combining variables with symbols like :// [OK]

Common Mistakes:

• Omitting quotes around the key string
• Missing $ before variables
• Incorrect concatenation without quotes

3. Given this nginx config snippet:

proxy_cache_key "$scheme://$host$request_uri";

What will be the cache key for a request to https://example.com/path/page?query=1?

medium

A. example.com/path/page?query=1

B. https://example.com/path/page?query=1

C. https://example.com/path/page

D. http://example.com/path/page?query=1

Solution

1. Step 1: Substitute variables with request values

   $scheme is 'https', $host is 'example.com', and $request_uri includes path and query: '/path/page?query=1'.

2. Step 2: Combine variables as per the key format

   Joining them gives 'https://example.com/path/page?query=1'.

3. Final Answer:

   https://example.com/path/page?query=1 -> Option B

4. Quick Check:

   Variables combined exactly = https://example.com/path/page?query=1 [OK]

Hint: Remember $request_uri includes query string [OK]

Common Mistakes:

• Ignoring the query string in $request_uri
• Using http instead of https for scheme
• Leaving out the scheme or host

4. You set proxy_cache_key "$scheme://$host$uri"; but nginx caches different query strings as the same content. What is the likely cause?

medium

A. You did not enable proxy_cache_path

B. You used $request_uri which already includes query string

C. You forgot to include $args in the cache key

D. You used double quotes instead of single quotes

Solution

1. Step 1: Understand $uri vs $request_uri

   $uri contains only the path (normalized), excluding the query string. $request_uri includes the query.

2. Step 2: Analyze the symptom

   Different query strings yield the same $uri, hence same cache key, causing shared cache content.

3. Final Answer:

   You forgot to include $args in the cache key -> Option C

4. Quick Check:

   $uri excludes query; add $args [OK]

Hint: $uri lacks query string; add $args [OK]

Common Mistakes:

• Confusing cache key with cache size or expiration
• Thinking it enables SSL
• Assuming it controls cache storage location

5. You want to cache content separately for mobile and desktop users. Which proxy cache key configuration achieves this if user agent contains 'Mobile' for mobile devices?

hard

A. proxy_cache_key "$scheme://$host$request_uri:$is_mobile"; # where $is_mobile is set by map

B. proxy_cache_key "$scheme://$host$request_uri:$http_user_agent ~* Mobile";

C. proxy_cache_key "$scheme://$host$request_uri:$http_user_agent";

D. proxy_cache_key "$scheme://$host$request_uri";

Solution

1. Step 1: Understand the need for conditional cache key

   We want to separate cache for mobile and desktop, so the key must include a variable indicating device type.

2. Step 2: Use a map to set $is_mobile variable

   nginx can use map to set $is_mobile to 'mobile' or 'desktop' based on $http_user_agent matching 'Mobile'. Including $is_mobile in cache key separates caches.

3. Step 3: Evaluate options

   proxy_cache_key "$scheme://$host$request_uri:$http_user_agent"; uses full user agent, which is too specific and causes cache fragmentation. proxy_cache_key "$scheme://$host$request_uri:$http_user_agent ~* Mobile"; is invalid syntax. proxy_cache_key "$scheme://$host$request_uri"; ignores device type. proxy_cache_key "$scheme://$host$request_uri:$is_mobile"; # where $is_mobile is set by map correctly uses $is_mobile set by map.

4. Final Answer:

   proxy_cache_key "$scheme://$host$request_uri:$is_mobile"; # where $is_mobile is set by map -> Option A

5. Quick Check:

   Use map variable for device type in cache key = proxy_cache_key "$scheme://$host$request_uri:$is_mobile"; # where $is_mobile is set by map [OK]

Hint: Use map to create $is_mobile variable for cache key [OK]

Common Mistakes:

• Using full user agent causing too many cache entries
• Trying regex inside proxy_cache_key (invalid)
• Ignoring device type in cache key