NGINX Proxy Cache & Microcaching Prompt
Stand up proxy_cache (or 1-second microcaching) in front of a dynamic backend to absorb traffic spikes — with a correct cache key, bypass rules, and stale-while-revalidate — without serving stale or per-user content to the wrong people.
- Target user
- Engineers offloading a slow or spiky backend with NGINX caching
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior performance engineer who has put NGINX proxy caching in front of databases melting under load. You obsess over the cache key and the bypass rules, because a wrong key serves one user's data to another.
I will provide:
- What the backend serves and how dynamic it is (per-user? cookied? mostly-static?): [DESCRIBE CONTENT]
- The endpoints to cache vs never-cache (e.g. logged-in pages, carts): [DESCRIBE ROUTES]
- The traffic problem (spikes, slow origin, thundering herd): [DESCRIBE PROBLEM]
- Current proxy config: [PASTE CONFIG]
Design the cache:
1. **`proxy_cache_path`** — location, `levels`, `keys_zone` size, `max_size`, `inactive`, and `use_temp_path=off`; explain how the zone memory maps to number of cached keys.
2. **Cache key** — set `proxy_cache_key` deliberately. Decide whether the cookie, query string, or auth header must be part of the key, and warn loudly about caching per-user responses under a shared key.
3. **What to cache** — `proxy_cache_valid` per status code; respect or override `Cache-Control`/`Set-Cookie` from the origin with care.
4. **Bypass / no-cache** — `proxy_cache_bypass` and `proxy_no_cache` for logged-in users, POSTs, and carts, keyed on cookies/args.
5. **Microcaching** — if the content is dynamic but identical across users for ~1s, a `proxy_cache_valid 200 1s` pattern with `proxy_cache_use_stale updating` + `proxy_cache_lock on` to collapse the thundering herd into one origin request.
6. **Observability** — add `X-Cache-Status $upstream_cache_status` so HIT/MISS/BYPASS is visible, and how to read it.
Output: (a) the `http {}` `proxy_cache_path` + the `location` cache directives, commented, (b) the cache-key reasoning, (c) the bypass rules with the exact cookies/args, (d) a verification: curl twice and watch `X-Cache-Status` flip MISS→HIT, behind `nginx -t`. Never enable caching on per-user routes without a key that isolates them; validate and reload, don't hot-edit prod.
Why this prompt works
The catastrophic caching bug is a cache key that ignores identity — cache a logged-in dashboard under a key that omits the session cookie and NGINX will happily serve Alice’s account page to Bob. The prompt makes the cache key and the bypass rules the central design decisions and forces an explicit warning about per-user content, so this failure mode is confronted, not stumbled into.
Microcaching is the high-leverage trick this prompt surfaces: even a one-second proxy_cache_valid with proxy_cache_lock collapses a thundering herd of identical requests into a single origin hit, protecting a fragile backend during spikes while keeping content effectively fresh. Most teams never reach for it because they think “dynamic means uncacheable.”
The X-Cache-Status header and the curl-twice verification keep you in control: you watch MISS flip to HIT with your own eyes and confirm logged-in routes report BYPASS, all behind an nginx -t gate, instead of shipping a cache you can’t observe.