| | |

Cloudflare 06 ☁️ Edge Caching & CDN Optimization — Mastering Cache-Control, Cache Rules, Tiered Cache, and programmatic cache purging

⏱️ Estimated read: 11 min | |

Cloudflare operates one of the world’s largest Content Delivery Networks (CDNs), designed to minimize the physical distance between users and the data they request. By storing copies of your content in hundreds of data centers globally, Cloudflare reduces latency, lowers origin server load, and decreases bandwidth costs. However, a CDN is only as effective as its configuration; simply pointing your DNS to Cloudflare is not enough to achieve peak performance for dynamic applications.

This chapter explores the sophisticated mechanics of edge caching and CDN optimization. We will examine how Cloudflare interprets standard HTTP headers and how you can override this behavior using granular Cache Rules. Furthermore, we will delve into architectural optimizations like Tiered Cache, which adds an additional layer of caching between the edge and your origin, and programmatic purging methods to ensure your users never see stale data.

The sections that follow walk through the syntax of Cache-Control headers, the implementation of Cloudflare Cache Rules, the logic behind Tiered Cache, and the automation of cache invalidation via the Cloudflare API.

Key point: Effective CDN optimization requires a balance between high TTLs (Time to Live) for performance and precise invalidation strategies for data integrity; Cloudflare allows you to manage this through a combination of origin headers, edge rules, and API-driven purging.


Why Cache Optimization exists

The physical distance problem. Data cannot travel faster than the speed of light. Without a CDN, a user in Tokyo requesting a resource from a server in London faces a minimum round-trip time that creates a sluggish experience. Caching places the content at the “Edge,” mere milliseconds away from the user, regardless of where the origin server resides.

The origin bottleneck problem. Every request that hits your origin server consumes CPU, memory, and database connections. During traffic spikes, an unoptimized application can quickly become overwhelmed. Edge caching acts as a shield, absorbing the vast majority of requests and ensuring that the origin only processes necessary, dynamic transactions.

The egress cost problem. Many cloud providers charge significant fees for data leaving their network. By serving assets from Cloudflare’s cache, you drastically reduce the amount of data transferred out of your origin. This makes caching not just a performance tool, but a critical architectural strategy for cost management.

The stale data trade-off. Developers often fear caching because it can lead to users seeing outdated information. Modern CDN optimization solves this by providing granular control over invalidation. Instead of using low TTLs “just in case,” you can use long TTLs for performance and trigger an immediate purge the moment the source data changes.

The Tiered Cache advantage. In a standard CDN setup, if 300 data centers each request the same file from your origin, your origin still sees 300 requests. Tiered Cache introduces “Upper Tier” data centers that aggregate these requests, so your origin might only see a single request, further protecting your infrastructure.


a. Interpreting and Setting Cache-Control Headers

Cloudflare respects standard HTTP Cache-Control headers sent from your origin server, provided they do not conflict with your Cloudflare dashboard settings. These headers are the primary way your application communicates its caching requirements to the edge.

// Standard header for public, long-lived assets like images
Cache-Control: public, max-age=31536000, s-maxage=86400

The max-age directive tells the browser how long to cache the file, while s-maxage (shared max-age) specifically tells Cloudflare how long to keep the item in its edge cache. If s-maxage is present, it overrides max-age for the CDN.

Another powerful directive is stale-while-revalidate. This allows Cloudflare to serve a stale version of a resource from the cache while it simultaneously fetches a fresh version from the origin in the background.

// Serve stale content for up to 60s while refreshing in the background
Cache-Control: public, s-maxage=60, stale-while-revalidate=60

This prevents the “cache stampede” where multiple users hit the origin at the exact moment a cache entry expires. The first user triggers the refresh but still gets a fast response from the stale cache, and subsequent users get the fresh content once the refresh is complete.


b. Cloudflare Cache Rules and Tiered Cache

While Cache-Control headers are useful, you often need to override them or apply caching logic to legacy origins where you cannot easily change headers. Cloudflare Cache Rules (which replaced the older Page Rules for caching) allow you to define logic based on the URL, cookies, headers, or even the user’s country.

# Conceptual logic for a Cache Rule
If URL matches "/api/v1/products/*"
Then:
  Edge Cache TTL: 2 hours
  Browser Cache TTL: 30 minutes
  Cache Key: include Query String, ignore Header "X-User-ID"

Cache Rules also allow you to control “Cache Keys.” A cache key is the unique identifier Cloudflare uses to look up a file. By default, the key is the URL. However, if your application serves different content based on a header or cookie, you must include that in the cache key to prevent users from seeing each other’s data.

Tiered Cache is a global topology optimization. Instead of every edge data center going to your origin, they go to a regional “Upper Tier” hub. If the hub has the file, it serves it. If not, only the hub fetches from your origin.

User -> Edge (Edge Miss) -> Hub (Hub Hit) -> Return to User
# Result: Origin was never contacted.

c. Programmatic Cache Purging via API

To maintain high TTLs without serving stale data, your deployment or CMS pipeline should trigger a purge when content changes. Cloudflare provides three main ways to purge: by URL, by Tag (Enterprise only), or Purge Everything.

# Purging specific URLs via cURL
curl -X POST "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{"files":["https://example.com/styles.css"]}'

Purging by Tag (Cache-Tag) is the most efficient method for complex applications. You can tag an HTTP response with Cache-Tag: product-123. Later, when that specific product is updated in your database, you send a single API call to purge all objects associated with that tag, regardless of their URL.

# Purging by Cache-Tag
curl -X POST "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     --data '{"tags":["product-123"]}'

This “Push” model of cache invalidation is what enables “Instant Purge,” where Cloudflare removes the object from its global network in under 150 milliseconds.


Complete Example Session

// ============================================
// PART 1: DEFINING ORIGIN HEADERS
// ============================================
// Express.js example setting caching headers
app.get('/assets/logo.png', (req, res) => {
  res.set('Cache-Control', 'public, max-age=31536000, s-maxage=86400'); // 1 year browser, 1 day edge
  res.sendFile('/path/to/logo.png');
});

// ============================================
// PART 2: DYNAMIC API CACHING
// ============================================
app.get('/api/news', (req, res) => {
  // Use stale-while-revalidate for high performance news feed
  res.set('Cache-Control', 'public, s-maxage=10, stale-while-revalidate=50');
  res.json(newsData);
});

// ============================================
// PART 3: CACHE TAGGING FOR GRANULAR PURGE
// ============================================
app.get('/product/blue-widget', (req, res) => {
  res.set('Cache-Tag', 'product-id-456, category-widgets'); // Attach tags for later purging
  res.render('product-page');
});

// ============================================
// PART 4: BYPASSING CACHE FOR PRIVATE DATA
// ============================================
app.get('/user/dashboard', (req, res) => {
  res.set('Cache-Control', 'private, no-cache, no-store, must-revalidate'); // Ensure no CDN/browser caching
  res.send(userData);
});

// ============================================
// PART 5: CLOUDFLARE CACHE RULE (CONCEPTUAL)
// ============================================
// Matching: hostname equals "api.example.com" AND path starts with "/v1/public"
// Action: Cache Level: Cache Everything, Edge TTL: 1 Month

// ============================================
// PART 6: PROGRAMMATIC PURGE SCRIPT (NODE.JS)
// ============================================
async function purgeProductCache(productId) {
  const url = `https://api.cloudflare.com/client/v4/zones/${process.env.CF_ZONE_ID}/purge_cache`;
  await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CF_API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ tags: [`product-id-${productId}`] }) // Targeted invalidation
  });
}

// ============================================
// PART 7: PURGING BY PREFIX
// ============================================
// body: JSON.stringify({ prefixes: ["example.com/blog/"] }) 
// Clears all blog-related posts simultaneously

// ============================================
// PART 8: TIERED CACHE CONFIGURATION
// ============================================
// Setting Tiered Cache to "Generic Global" via API
// PATCH zones/:zone_id/settings/tiered_cache_smart_topology_enable value: "on"

// ============================================
// PART 9: CACHE KEY CUSTOMIZATION
// ============================================
// Using a Cache Rule to ignore specific tracking query strings
// e.g., ignore "utm_source", "fbclid" to increase hit rates

// ============================================
// PART 10: VERIFYING CACHE STATUS
// ============================================
// Check headers in terminal:
// curl -I https://example.com/assets/logo.png
// Look for: CF-Cache-Status: HIT

The ten parts above demonstrate the full lifecycle of a cached resource, from origin header definition to automated invalidation and verification.


Quick Reference

Essential Cache Headers

HeaderPurposeCloudflare Action
max-ageBrowser TTLRespects unless overridden
s-maxageCDN TTLOverrides max-age for Edge
no-storeDisable cachingWill not cache the object
privateSingle user onlyWill not cache on Edge

CF-Cache-Status Values

StatusMeaning
HITServed from Edge cache
MISSNot in cache, fetched from origin
EXPIREDWas in cache but TTL lapsed; re-fetched
BYPASSRule explicitly told CF not to cache
DYNAMICDefault for assets CF doesn’t cache (e.g. HTML)

Purge API Methods

MethodAccuracyUse Case
Purge Everything100%Major site redesign / site-wide error
Purge by URLHighSpecific asset update (CSS/JS)
Purge by TagHighCMS content updates (Enterprise)
Purge by PrefixMediumClearing an entire directory

Best Practices

✅ Do This:

// Use s-maxage to give the CDN a different TTL than the browser
Cache-Control: public, max-age=3600, s-maxage=86400            // ✅

// Use stale-while-revalidate for background updates
Cache-Control: public, s-maxage=60, stale-while-revalidate=30  // ✅

// Always include Cache-Control: private for sensitive pages
Cache-Control: private, no-store                               // ✅

// Use Tiered Cache to reduce origin load
// (Enable in Dashboard -> Caching -> Tiered Cache)           // ✅

❌ Don’t Do This:

// Use very short TTLs for static assets
Cache-Control: public, max-age=5                               // ❌

// Cache POST requests (unless explicitly intended)
// CF generally bypasses POST by default                       // ❌

// Forget to purge cache after a production deployment
// (Users will see old JS/CSS files)                           // ❌

// Use "Cache Everything" on pages with CSRF tokens
// (Tokens will be leaked to other users)                      // ❌

Common Pitfalls

PitfallWhy It HappensFix
No cache for HTMLCF only caches static files by defaultUse a Cache Rule to “Cache Everything”
Private data cachedMissing private or no-store headersEnsure sensitive routes send private headers
Low Hit RatioQuery strings vary (tracking IDs)Use Cache Rules to “Ignore Query String”
Purge not workingUsing the wrong Zone ID or API TokenVerify credentials in the Cloudflare Dashboard
Stale assets on deployBrowser cache is too longUse versioned filenames (e.g., style.v2.css)

Real-World Examples

1. Static Asset Caching

Cache-Control: public, max-age=31536000, immutable

2. Short-lived API Response

Cache-Control: public, s-maxage=30, stale-while-revalidate=10

3. Bypassing Cache for Devs

Match: Header "X-Dev-Mode" exists -> Cache Level: Bypass

4. Purge specific image

curl -X POST ... --data '{"files":["https://site.com/img.jpg"]}'

5. User Profile (Private)

Cache-Control: private, must-revalidate, max-age=0

6. Micro-caching Search Results

Cache-Control: public, s-maxage=1, max-age=1

7. Tiered Cache Topology

"tiered_cache_smart_topology_enable": "on"

8. Cache Key by Country

Cache Rule -> Cache Key -> Custom -> Include "Geo" header

9. Purge by Cache-Tag (API)

{ "tags": ["blog-post-101"] }

10. Cache Everything Rule

URL: *example.com/*.html -> Edge TTL: 2 hours

Visual

Edge vs Origin Workflow

┌───────────────────────────────────────────────────────────┐
│  USER REQUEST FLOW                                        │
│                                                           │
│  User ────► [ Cloudflare Edge ] ───(HIT)───┐              │
│                  │                         │              │
│                (MISS)                      ▼              │
│                  │                  [ Cached Asset ]      │
│                  ▼                         │              │
│          [ Origin Server ] ◄───────────────┘              │
│                                                           │
│  * Edge checks TTL and Cache-Control headers from origin  │
└───────────────────────────────────────────────────────────┘

Tiered Cache Hierarchy

┌───────────────────────────────────────────────────────────┐
│  TIERED CACHE TOPOLOGY                                    │
│                                                           │
│  Edge DC (London)  ───┐                                   │
│  Edge DC (Paris)   ───┼──► [ Upper Tier Hub ] ──► [Origin]│
│  Edge DC (Berlin)  ───┘       (Amsterdam)                 │
│                                                           │
│  * Only the Hub talks to the Origin on a cache miss       │
│  * Reduces origin load by orders of magnitude             │
└───────────────────────────────────────────────────────────┘

Cache Purge Propagation

┌───────────────────────────────────────────────────────────┐
│  INSTANT PURGE (The "Push" Model)                         │
│                                                           │
│  [ CMS / API ] ───(Purge Command)───► [ CF Control Plane ]│
│                                              │            │
│  ┌───────────────────────────────────────────┴┐           │
│  ▼                      ▼                     ▼           │
│ [Edge 1]               [Edge 2]              [Edge N]     │
│ (Invalidated)          (Invalidated)         (Invalidated)│
│                                                           │
│  * Global propagation in < 150 milliseconds              │
└───────────────────────────────────────────────────────────┘

Summary

ItemValue
Primary HeaderCache-Control
CDN-specific TTLs-maxage
Feature for HitsTiered Cache
Manual ClearingCache Purging
Default LogicExtension-based
Custom LogicCache Rules
Tagging SystemCache-Tag
Background Refreshstale-while-revalidate
Header to CheckCF-Cache-Status

Key takeaways:

  • Cloudflare follows standard HTTP headers. By using s-maxage, you can define specific instructions for the CDN that differ from what the user’s browser sees.
  • Cache Rules provide granular control. They allow you to override origin behavior, customize cache keys, and cache content types (like HTML) that Cloudflare ignores by default.
  • Tiered Cache is a performance multiplier. It consolidates requests to your origin into regional hubs, significantly reducing traffic and protecting your infrastructure.
  • Instant Purge allows for high TTLs. You can cache content for days or weeks, knowing you can clear the entire global network via API the second your content changes.
  • Cache Tags are the gold standard for Enterprise. They allow you to group related objects and purge them with a single API call, regardless of their URL structure.

Remember: CDN optimization is not a “set and forget” task. It requires understanding the interplay between browser caching, edge caching, and the origin’s data freshness requirements. By mastering Cache-Control and programmatic purging, you can build applications that are lightning-fast globally while maintaining perfect data consistency.

Was this helpful?


Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!