Caching strategies

How CDN caching works#

When a user requests content, the flow is: origin → edge → user. Your origin server (VM, storage bucket, or external host) delivers the response. Edge CDN nodes sit in 988 locations worldwide and cache responses closer to your users. On a cache hit, the edge serves the content directly without contacting your origin. This reduces latency and takes load off your origin.

The first request for a given URL triggers a fetch from origin. Subsequent requests for that URL (within the cache TTL) are served from the edge. Understanding this flow helps you tune cache behaviour for performance and cost.

Cache-Control headers and Edge#

Your origin can send standard Cache-Control headers to influence caching. Edge respects max-age, s-maxage, and private/no-store. For example, Cache-Control: max-age=3600, s-maxage=86400 tells the edge to cache for 24 hours (s-maxage) even if the browser honours 1 hour (max-age).

If your origin omits or sends conflicting headers, Edge applies a default TTL. You can also override origin directives via the console or API. This is useful when you want consistent behaviour across deployments without changing application code.

Default TTLs and path-based rules#

Set a default TTL for your CDN deployment in the console under Configuration → Caching. This applies when the origin does not send cache directives.

Path-based cache rules let you fine-tune behaviour by URL pattern. A common strategy:

• Long TTL for static assets: 7–30 days or more for paths such as /assets/* or *.js, *.css and *.woff2.
• Short TTL for HTML: 0–5 minutes for dynamic pages, on paths such as /* or /*.html.
• No cache for dynamic content: bypass the cache entirely for API paths and user-specific pages.

In the console, add rules under Configuration → Cache Rules. You can also configure rules with the Edge CLI. Run edge cdn cache-rules --help for the syntax.

Cache bypass for dynamic content#

For user dashboards, API responses, or personalised content, caching is usually wrong. Two approaches:

1. Origin headers: set Cache-Control: no-store or private on those responses. Edge will not cache them.
2. Path-based bypass: add a cache rule that matches the path (e.g. /api/*) and sets TTL to 0 or “bypass”.

Use bypass sparingly. Every uncached request hits your origin and increases load. Keep dynamic paths limited to what truly needs freshness.

Cache purging: when and how#

Purge invalidates cached content before its TTL expires. Use it when you update a file, redeploy, or fix a mistake and need users to see the new version immediately.

When to purge: After deploying static site updates, changing assets (JS/CSS), uploading new images, or fixing incorrect content. Avoid purging entire deployments routinely, as it defeats the purpose of caching.

How to purge: In the console, go to your CDN deployment → Purging. You can purge by URL, path prefix, or (for deployments that support it) by tag. Via the CLI:

edge cdn purge <deployment-id> --url "https://yoursite.com/page"

Purging propagates across the edge network within seconds. There is no charge for purge operations within reasonable limits.

Image optimisation cache behaviour#

Edge’s image optimisation (resize, format conversion, quality) generates derived images on demand. These derived images are cached separately. Each unique URL (including query params like ?w=800) is cached independently.

Set a long TTL for image paths. Optimised images do not change unless the source changes. When you replace the source image, purge the relevant URLs or path to invalidate cached variants.

Monitoring cache hit rates#

The console provides cache metrics per deployment: hit rate, miss rate, and bandwidth served from cache vs origin. High hit rates (e.g. 90%+) mean your origin is protected and users get fast responses.

Low hit rates often mean: TTLs are too short, paths are bypassing cache, or traffic is spread across many unique URLs. Review your cache rules and consider longer TTLs for static content. Use the Edge CLI or API to pull analytics for deeper analysis.