Files
skills/public/proxies-cache-control.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

673 lines
29 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>proxies-cache-control</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/proxies-cache-control.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/proxies-cache-control">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/proxies-cache-control.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>proxies-cache-control</h1><p class="lede">HTTP caching strategies including cache headers, CDN patterns, cache invalidation, stale-while-revalidate, and edge caching optimization</p><h1>Cache Control</h1>
<p><strong>Scope</strong>: HTTP caching, cache headers, CDN patterns, invalidation strategies <strong>Lines</strong>: ~380 <strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Implementing HTTP caching strategies</li><li>Optimizing CDN usage</li><li>Configuring cache headers</li><li>Debugging cache-related issues</li><li>Implementing cache invalidation</li><li>Setting up edge caching</li><li>Optimizing web performance</li><li>Working with proxy caches</li></ul>
<h2>Core Concepts</h2>
<h3>HTTP Caching Layers</h3>
<pre><code>Client → Browser Cache → CDN Edge → Origin Cache → Origin Server
(private) (shared) (shared) (source)</code></pre>
<p><strong>Cache Types</strong>:</p>
<ul><li><strong>Private Cache</strong>: Browser cache (single user)</li><li><strong>Shared Cache</strong>: CDN, proxy cache (multiple users)</li><li><strong>Gateway Cache</strong>: Reverse proxy cache (nginx, Varnish)</li></ul>
<h3>Cache-Control Directives</h3>
<p><strong>Request Directives</strong>:</p>
<pre><code class="lang-http">Cache-Control: no-cache # Revalidate with origin
Cache-Control: no-store # Don&#x27;t cache at all
Cache-Control: max-age=0 # Immediate revalidation
Cache-Control: max-stale=3600 # Accept stale up to 1h
Cache-Control: min-fresh=60 # Must be fresh for 60s
Cache-Control: only-if-cached # Return cached or 504</code></pre>
<p><strong>Response Directives</strong>:</p>
<pre><code class="lang-http">Cache-Control: public # Cacheable by any cache
Cache-Control: private # Only browser cache
Cache-Control: no-cache # Must revalidate
Cache-Control: no-store # Don&#x27;t cache
Cache-Control: max-age=3600 # Fresh for 1 hour
Cache-Control: s-maxage=7200 # Shared cache max age
Cache-Control: must-revalidate # Must revalidate when stale
Cache-Control: proxy-revalidate # Shared caches must revalidate
Cache-Control: immutable # Never changes</code></pre>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Static Assets with Immutable Caching</h3>
<p><strong>Use Case</strong>: JavaScript, CSS, images with content hashing</p>
<pre><code class="lang-http"># ❌ Bad: Short cache time
GET /app.js HTTP/1.1
Response:
Cache-Control: max-age=3600
# ✅ Good: Immutable with content hash
GET /app.abc123def.js HTTP/1.1
Response:
Cache-Control: public, max-age=31536000, immutable</code></pre>
<pre><code class="lang-nginx"># Nginx configuration
location ~* \.(?:css|js|jpg|jpeg|png|gif|ico|svg|woff|woff2)$ {
expires 1y;
add_header Cache-Control &quot;public, immutable&quot;;
access_log off;
# Enable gzip for compressible assets
gzip_static on;
}</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>Maximum cache efficiency</li><li>Eliminates revalidation requests</li><li>Content hash prevents stale content</li><li>CDN-friendly</li></ul>
<h3>Pattern 2: API Responses with Conditional Requests</h3>
<p><strong>Use Case</strong>: Frequently accessed but changing data</p>
<pre><code class="lang-python"># ❌ Bad: No caching
@app.route(&#x27;/api/users/&lt;user_id&gt;&#x27;)
def get_user(user_id):
user = get_user_from_db(user_id)
return jsonify(user)</code></pre>
<pre><code class="lang-python"># ✅ Good: ETag with conditional requests
from flask import Flask, jsonify, request, make_response
import hashlib
@app.route(&#x27;/api/users/&lt;user_id&gt;&#x27;)
def get_user(user_id):
user = get_user_from_db(user_id)
user_json = jsonify(user).get_data()
# Generate ETag
etag = hashlib.md5(user_json).hexdigest()
# Check If-None-Match
if request.headers.get(&#x27;If-None-Match&#x27;) == f&#x27;&quot;{etag}&quot;&#x27;:
return &#x27;&#x27;, 304 # Not Modified
response = make_response(jsonify(user))
response.headers[&#x27;ETag&#x27;] = f&#x27;&quot;{etag}&quot;&#x27;
response.headers[&#x27;Cache-Control&#x27;] = &#x27;private, max-age=60, must-revalidate&#x27;
return response</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>Bandwidth savings with 304 responses</li><li>Reduced server processing</li><li>Guaranteed fresh data</li><li>Works with CDNs</li></ul>
<h3>Pattern 3: Stale-While-Revalidate</h3>
<p><strong>Use Case</strong>: Balance freshness and performance</p>
<pre><code class="lang-http"># ✅ Serve stale while fetching fresh
Cache-Control: max-age=60, stale-while-revalidate=300
# Timeline:
# 0-60s: Serve from cache (fresh)
# 60-360s: Serve from cache (stale) + async revalidate
# 360s+: Must fetch from origin</code></pre>
<pre><code class="lang-nginx"># Nginx configuration
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g;
server {
location /api/ {
proxy_cache api_cache;
proxy_cache_valid 200 60s;
proxy_cache_use_stale updating; # Serve stale while updating
proxy_cache_background_update on;
proxy_cache_lock on;
add_header X-Cache-Status $upstream_cache_status;
proxy_pass http://backend;
}
}</code></pre>
<hr>
<h2>Cache Invalidation Strategies</h2>
<h3>1. Time-Based Expiration</h3>
<pre><code class="lang-http"># Simple time-based
Cache-Control: max-age=3600
# Different for shared vs private
Cache-Control: private, max-age=300, s-maxage=3600</code></pre>
<h3>2. ETag/Last-Modified Validation</h3>
<pre><code class="lang-python">from datetime import datetime
@app.route(&#x27;/api/article/&lt;article_id&gt;&#x27;)
def get_article(article_id):
article = get_article_from_db(article_id)
# Last-Modified header
last_modified = article[&#x27;updated_at&#x27;].strftime(&#x27;%a, %d %b %Y %H:%M:%S GMT&#x27;)
# Check If-Modified-Since
if_modified = request.headers.get(&#x27;If-Modified-Since&#x27;)
if if_modified and if_modified == last_modified:
return &#x27;&#x27;, 304
response = make_response(jsonify(article))
response.headers[&#x27;Last-Modified&#x27;] = last_modified
response.headers[&#x27;Cache-Control&#x27;] = &#x27;private, max-age=300&#x27;
return response</code></pre>
<h3>3. Cache Purging</h3>
<pre><code class="lang-python"># Purge specific URL from cache
import requests
def purge_cache(url: str):
&quot;&quot;&quot;Send PURGE request to proxy cache&quot;&quot;&quot;
try:
response = requests.request(&#x27;PURGE&#x27;, url)
return response.status_code == 200
except:
return False
# Usage
purge_cache(&#x27;https://cdn.example.com/api/users/123&#x27;)</code></pre>
<pre><code class="lang-bash"># Nginx cache purge
curl -X PURGE https://example.com/cached-page
# Varnish cache purge
curl -X BAN -H &quot;X-Ban-Url: /api/users/.*&quot; http://localhost:6081/</code></pre>
<h3>4. Surrogate-Control for CDN</h3>
<pre><code class="lang-http"># Control CDN cache separately from browser cache
Cache-Control: private, max-age=60
Surrogate-Control: max-age=3600
# CDN uses Surrogate-Control (3600s)
# Browser uses Cache-Control (60s)</code></pre>
<hr>
<h2>CDN Configuration</h2>
<h3>Cloudflare</h3>
<pre><code class="lang-javascript">// Cloudflare Workers - Custom caching
addEventListener(&#x27;fetch&#x27;, event =&gt; {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
const cache = caches.default
const cacheKey = new Request(request.url, request)
// Check cache
let response = await cache.match(cacheKey)
if (!response) {
// Fetch from origin
response = await fetch(request)
// Clone response (can only read once)
response = new Response(response.body, response)
// Set custom cache headers
response.headers.set(&#x27;Cache-Control&#x27;, &#x27;public, max-age=3600&#x27;)
response.headers.set(&#x27;X-Cache-Status&#x27;, &#x27;MISS&#x27;)
// Store in cache
event.waitUntil(cache.put(cacheKey, response.clone()))
} else {
response.headers.set(&#x27;X-Cache-Status&#x27;, &#x27;HIT&#x27;)
}
return response
}</code></pre>
<h3>AWS CloudFront</h3>
<pre><code class="lang-json">{
&quot;CacheBehaviors&quot;: [
{
&quot;PathPattern&quot;: &quot;/api/*&quot;,
&quot;TargetOriginId&quot;: &quot;api-origin&quot;,
&quot;ViewerProtocolPolicy&quot;: &quot;redirect-to-https&quot;,
&quot;AllowedMethods&quot;: [&quot;GET&quot;, &quot;HEAD&quot;, &quot;OPTIONS&quot;],
&quot;CachedMethods&quot;: [&quot;GET&quot;, &quot;HEAD&quot;, &quot;OPTIONS&quot;],
&quot;Compress&quot;: true,
&quot;MinTTL&quot;: 0,
&quot;DefaultTTL&quot;: 300,
&quot;MaxTTL&quot;: 3600,
&quot;ForwardedValues&quot;: {
&quot;QueryString&quot;: true,
&quot;Headers&quot;: [&quot;Authorization&quot;, &quot;Accept&quot;],
&quot;Cookies&quot;: {
&quot;Forward&quot;: &quot;none&quot;
}
}
},
{
&quot;PathPattern&quot;: &quot;/static/*&quot;,
&quot;TargetOriginId&quot;: &quot;static-origin&quot;,
&quot;ViewerProtocolPolicy&quot;: &quot;redirect-to-https&quot;,
&quot;Compress&quot;: true,
&quot;MinTTL&quot;: 31536000,
&quot;DefaultTTL&quot;: 31536000,
&quot;MaxTTL&quot;: 31536000
}
]
}</code></pre>
<hr>
<h2>Implementation Examples</h2>
<h3>Python with Flask-Caching</h3>
<pre><code class="lang-python">from flask import Flask
from flask_caching import Cache
app = Flask(__name__)
# Configure cache
cache = Cache(app, config={
&#x27;CACHE_TYPE&#x27;: &#x27;redis&#x27;,
&#x27;CACHE_REDIS_HOST&#x27;: &#x27;localhost&#x27;,
&#x27;CACHE_REDIS_PORT&#x27;: 6379,
&#x27;CACHE_DEFAULT_TIMEOUT&#x27;: 300
})
@app.route(&#x27;/api/expensive&#x27;)
@cache.cached(timeout=60, query_string=True)
def expensive_operation():
&quot;&quot;&quot;Cached for 60 seconds, varies by query string&quot;&quot;&quot;
result = perform_expensive_calculation()
return jsonify(result)
@app.route(&#x27;/api/users/&lt;user_id&gt;&#x27;)
@cache.memoize(timeout=120)
def get_user(user_id):
&quot;&quot;&quot;Cached per user_id for 120 seconds&quot;&quot;&quot;
user = get_user_from_db(user_id)
return jsonify(user)
# Manual cache control
@app.route(&#x27;/api/data&#x27;)
def get_data():
cache_key = f&quot;data:{request.args.get(&#x27;filter&#x27;)}&quot;
# Try cache first
data = cache.get(cache_key)
if data is None:
data = fetch_data()
cache.set(cache_key, data, timeout=300)
response = make_response(jsonify(data))
response.headers[&#x27;Cache-Control&#x27;] = &#x27;private, max-age=300&#x27;
return response
# Cache invalidation
@app.route(&#x27;/api/users/&lt;user_id&gt;&#x27;, methods=[&#x27;PUT&#x27;])
def update_user(user_id):
update_user_in_db(user_id, request.json)
# Invalidate cache
cache.delete_memoized(get_user, user_id)
return jsonify({&#x27;status&#x27;: &#x27;updated&#x27;})</code></pre>
<h3>Go with groupcache</h3>
<pre><code class="lang-go">package main
import (
&quot;context&quot;
&quot;fmt&quot;
&quot;github.com/golang/groupcache&quot;
&quot;net/http&quot;
)
var dataCache *groupcache.Group
func init() {
// Create cache group
dataCache = groupcache.NewGroup(&quot;data&quot;, 64&lt;&lt;20, groupcache.GetterFunc(
func(ctx context.Context, key string, dest groupcache.Sink) error {
// Fetch from source (called on cache miss)
data, err := fetchDataFromDB(key)
if err != nil {
return err
}
dest.SetBytes([]byte(data))
return nil
},
))
}
func handleRequest(w http.ResponseWriter, r *http.Request) {
key := r.URL.Path
var data []byte
err := dataCache.Get(r.Context(), key, groupcache.AllocatingByteSliceSink(&amp;data))
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
// Set cache headers
w.Header().Set(&quot;Cache-Control&quot;, &quot;public, max-age=3600&quot;)
w.Header().Set(&quot;Content-Type&quot;, &quot;application/json&quot;)
w.Write(data)
}
func fetchDataFromDB(key string) (string, error) {
// Simulate database query
return fmt.Sprintf(`{&quot;key&quot;: &quot;%s&quot;, &quot;value&quot;: &quot;data&quot;}`, key), nil
}
func main() {
http.HandleFunc(&quot;/&quot;, handleRequest)
http.ListenAndServe(&quot;:8080&quot;, nil)
}</code></pre>
<hr>
<h2>Cache Key Design</h2>
<h3>Good Cache Key Patterns</h3>
<pre><code class="lang-python"># ✅ Good: Include all varying factors
cache_key = f&quot;user:{user_id}:profile:v{api_version}&quot;
cache_key = f&quot;search:{query}:{page}:{sort}:{filter}&quot;
cache_key = f&quot;product:{product_id}:{lang}:{currency}&quot;
# ❌ Bad: Missing important factors
cache_key = f&quot;user:{user_id}&quot; # Doesn&#x27;t vary by API version
cache_key = f&quot;search:{query}&quot; # Doesn&#x27;t vary by pagination</code></pre>
<h3>Cache Key Normalization</h3>
<pre><code class="lang-python">def normalize_cache_key(params: dict) -&gt; str:
&quot;&quot;&quot;Create consistent cache key from parameters&quot;&quot;&quot;
# Sort keys for consistency
sorted_params = sorted(params.items())
# Normalize values
normalized = []
for key, value in sorted_params:
if isinstance(value, list):
value = &#x27;,&#x27;.join(sorted(str(v) for v in value))
normalized.append(f&quot;{key}={value}&quot;)
return &#x27;:&#x27;.join(normalized)
# Usage
cache_key = normalize_cache_key({
&#x27;user_id&#x27;: 123,
&#x27;filters&#x27;: [&#x27;active&#x27;, &#x27;premium&#x27;],
&#x27;page&#x27;: 2
})
# Result: &quot;filters=active,premium:page=2:user_id=123&quot;</code></pre>
<hr>
<h2>Best Practices</h2>
<h3>1. Use Appropriate Cache Directives</h3>
<pre><code class="lang-http"># Static assets (with versioning)
Cache-Control: public, max-age=31536000, immutable
# User-specific data
Cache-Control: private, max-age=300
# Frequently changing data
Cache-Control: private, max-age=60, must-revalidate
# Never cache
Cache-Control: no-store, no-cache, must-revalidate</code></pre>
<h3>2. Implement Cache Warming</h3>
<pre><code class="lang-python"># Pre-populate cache with frequently accessed data
def warm_cache():
popular_items = get_popular_items()
for item_id in popular_items:
cache_key = f&quot;item:{item_id}&quot;
data = fetch_item_data(item_id)
cache.set(cache_key, data, timeout=3600)
# Run on startup or scheduled
warm_cache()</code></pre>
<h3>3. Monitor Cache Hit Rates</h3>
<pre><code class="lang-python">from prometheus_client import Counter, Histogram
cache_hits = Counter(&#x27;cache_hits_total&#x27;, &#x27;Total cache hits&#x27;)
cache_misses = Counter(&#x27;cache_misses_total&#x27;, &#x27;Total cache misses&#x27;)
cache_latency = Histogram(&#x27;cache_operation_seconds&#x27;, &#x27;Cache operation latency&#x27;)
@cache_latency.time()
def get_cached_data(key):
data = cache.get(key)
if data:
cache_hits.inc()
return data
else:
cache_misses.inc()
data = fetch_data(key)
cache.set(key, data)
return data</code></pre>
<hr>
<h2>Troubleshooting</h2>
<h3>Issue 1: Stale Cache</h3>
<p><strong>Symptoms</strong>: Users seeing old data <strong>Common Causes</strong>:</p>
<ul><li>Long max-age values</li><li>Missing cache invalidation</li><li>Clock skew</li></ul>
<p><strong>Solutions</strong>:</p>
<pre><code class="lang-python"># 1. Use shorter TTLs with revalidation
response.headers[&#x27;Cache-Control&#x27;] = &#x27;max-age=60, must-revalidate&#x27;
# 2. Implement cache versioning
cache_key = f&quot;data:{version}:{id}&quot;
# 3. Use ETags for validation
response.headers[&#x27;ETag&#x27;] = generate_etag(data)</code></pre>
<h3>Issue 2: Cache Stampede</h3>
<p><strong>Symptoms</strong>: Multiple requests hit origin simultaneously <strong>Solution</strong>:</p>
<pre><code class="lang-python">import threading
locks = {}
def get_with_lock(key: str):
&quot;&quot;&quot;Prevent cache stampede with locking&quot;&quot;&quot;
# Try cache first
data = cache.get(key)
if data is not None:
return data
# Acquire lock for this key
if key not in locks:
locks[key] = threading.Lock()
with locks[key]:
# Check cache again (another thread may have filled it)
data = cache.get(key)
if data is not None:
return data
# Fetch and cache
data = fetch_data(key)
cache.set(key, data, timeout=300)
return data</code></pre>
<hr>
<h2>Related Skills</h2>
<ul><li><code>proxies-nginx-configuration</code> - Nginx caching configuration</li><li><code>proxies-reverse-proxy</code> - Reverse proxy caching</li><li><code>protocols-http-fundamentals</code> - HTTP headers and caching</li><li><code>database-redis</code> - Redis as cache backend</li><li><code>observability-performance-monitoring</code> - Cache metrics</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-27</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/proxies-cache-control.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>