CDN and Edge Caching

Pathrule2 Rules • 2 Memories • 1 Skill

CDN and edge caching change correctness as well as speed because a response can outlive the request, deployment, permission, or data state that produced it. This bundle defines cache eligibility, keys, Vary behavior, validators, freshness, stale serving, invalidation, and origin shielding. Unlike Cloudflare Workers, it governs HTTP cache semantics across providers rather than edge-compute APIs and deployment conventions.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

review-cdn-cache

src/

api/

Cache only responses with a complete representation key

Authorization and caching are one design decision

infra/

cdn/

Define freshness, validation, and stale behavior per content class

Invalidation targets content identity, not one visible URL

Rules

Cache only responses with a complete representation key/src/apihighstrictA shared response is cacheable only when every input that changes its bytes or authorization is represented or intentionally normalized.

1	A shared response is cacheable only when every input that changes its bytes or authorization is represented or intentionally normalized. URL-only keys can mix identities, tenants, locales, devices, experiments, encodings, query meanings, or cookie-selected representations. Enforce this boundary in /src/api so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Classify endpoints as public shared, private browser, or non-cacheable before setting response directives.
4	- Normalize accepted query parameters and reject or bypass unknown variants that would fragment or poison the cache.
5	- Use Vary for request headers that select a representation and configure CDN-specific key inputs consistently.
6	- Never shared-cache a personalized response merely because authentication happens upstream; make identity variance explicit or mark it private or no-store.
7
8	Verification: Request equivalent and different identities, tenants, locales, encodings, cookies, headers, and query orders through the real CDN; confirm hits only for byte-equivalent authorized representations.

Define freshness, validation, and stale behavior per content class/infra/cdnhighstrictEach cache policy names its freshness lifetime, validators, revalidation, stale permissions, purge path, and failure behavior.

1	Each cache policy names its freshness lifetime, validators, revalidation, stale permissions, purge path, and failure behavior. A single long TTL makes critical state wrong, while a single no-cache policy overloads origins and removes safe resilience for immutable content. Enforce this boundary in /infra/cdn so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Use immutable content-addressed assets with long freshness and never reuse a URL for different bytes.
4	- Give mutable public content explicit freshness plus ETag or Last-Modified validation where the origin can determine equivalence correctly.
5	- Permit stale responses only for content and failure modes the product has judged safe; honor must-revalidate where stale data would cause incorrect operation.
6	- Protect the origin with request collapsing, shielding, bounded revalidation, and capacity that assumes a cold-cache event.
7
8	Verification: Expire, revalidate, purge, disconnect the origin, and create a thundering-herd load for each content class; verify the documented stale and failure outcome.

Memories

Invalidation targets content identity, not one visible URL/infra/cdnA resource can have path aliases, query variants, locales, encodings, device forms, and surrogate keys, so purging one URL may leave equivalent stale objects active.

1	A resource can have path aliases, query variants, locales, encodings, device forms, and surrogate keys, so purging one URL may leave equivalent stale objects active. Assign content or collection tags when generating cacheable responses and map mutations to the tags they invalidate.
2
3	Version assets and large immutable datasets instead of relying on global purge. Purge only after the new origin state is committed and observable. Measure invalidation propagation and keep an emergency bypass that does not expose private responses or overwhelm the origin. Keep the decision explicit at /infra/cdn; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /src/api for cache tags and /public for content-addressed assets. That related boundary consumes this decision and carries the evidence that proves it still holds.

Authorization and caching are one design decision/src/apiA response generated after an authorization check can still be replayed by a shared cache unless cache eligibility and keying preserve that decision.

1	A response generated after an authorization check can still be replayed by a shared cache unless cache eligibility and keying preserve that decision. Decide whether the representation is public, tenant-shared, user-private, or non-cacheable at the same boundary that authorizes the request.
2
3	Keep Set-Cookie and personalized headers from accidentally changing otherwise public objects. Use private browser caching only when the client may safely retain the data for the specified lifetime. Treat signed URLs and token-bearing query parameters as sensitive inputs with explicit cache and log policy. Keep the decision explicit at /src/api; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /infra/cdn for key configuration and the cache review skill for end-to-end tests. That related boundary consumes this decision and carries the evidence that proves it still holds.

Skills

review-cdn-cache/rootReview a CDN cache path for eligibility, keys, freshness, validators, stale behavior, invalidation, privacy, and origin load.

1	---
2	name: review-cdn-cache
3	description: Review a CDN cache path for eligibility, keys, freshness, validators, stale behavior, invalidation, privacy, and origin load.
4	---
5
6	# Review Cdn Cache
7
8	Run this procedure whenever the governed surface changes or its operational evidence becomes stale.
9
10	1. Trace requests from client through every proxy and CDN layer to the origin, recording normalized URL, key inputs, bypass conditions, and response directives.
11	2. Build a representation matrix for identity, tenant, locale, encoding, cookies, experiments, headers, query, and authorization; test hit and miss expectations.
12	3. Exercise freshness, conditional validation, purge, mutation, stale-while-revalidate, stale-if-error where used, and disconnected-origin behavior.
13	4. Load-test cold cache, expiry, and mass invalidation with shielding and request collapse; verify privacy, correctness, origin capacity, and observable cache reasons.
14
15	Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.

Why this pattern

Agents cache successful GET responses without proving that identity, locale, encoding, query, cookies, and authorization are represented in the cache contract.

Built for Teams serving dynamic or static web content through shared caches and CDNs.

Keeps your assistant from:

Personalized or authorized responses shared across users
Cache keys omitting locale, encoding, query, or representation inputs
Invalidation that purges one URL while equivalent variants remain stale

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25