# Pathrule Pattern: CDN and Edge Caching (1.0.0) # ::pathrule:package:cdn-edge-caching ### [RULE] Cache only responses with a complete representation key (path: /src/api) 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. - Classify endpoints as public shared, private browser, or non-cacheable before setting response directives. - Normalize accepted query parameters and reject or bypass unknown variants that would fragment or poison the cache. - Use Vary for request headers that select a representation and configure CDN-specific key inputs consistently. - Never shared-cache a personalized response merely because authentication happens upstream; make identity variance explicit or mark it private or no-store. 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. --- ### [RULE] Define freshness, validation, and stale behavior per content class (path: /infra/cdn) 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. - Use immutable content-addressed assets with long freshness and never reuse a URL for different bytes. - Give mutable public content explicit freshness plus ETag or Last-Modified validation where the origin can determine equivalence correctly. - Permit stale responses only for content and failure modes the product has judged safe; honor must-revalidate where stale data would cause incorrect operation. - Protect the origin with request collapsing, shielding, bounded revalidation, and capacity that assumes a cold-cache event. Verification: Expire, revalidate, purge, disconnect the origin, and create a thundering-herd load for each content class; verify the documented stale and failure outcome. --- ### [MEMORY] Invalidation targets content identity, not one visible URL (path: /infra/cdn) 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. 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. 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. --- ### [MEMORY] Authorization and caching are one design decision (path: /src/api) 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. 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. 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. --- ### [SKILL] review-cdn-cache (path: /) --- name: review-cdn-cache description: Review a CDN cache path for eligibility, keys, freshness, validators, stale behavior, invalidation, privacy, and origin load. --- # Review Cdn Cache Run this procedure whenever the governed surface changes or its operational evidence becomes stale. 1. Trace requests from client through every proxy and CDN layer to the origin, recording normalized URL, key inputs, bypass conditions, and response directives. 2. Build a representation matrix for identity, tenant, locale, encoding, cookies, experiments, headers, query, and authorization; test hit and miss expectations. 3. Exercise freshness, conditional validation, purge, mutation, stale-while-revalidate, stale-if-error where used, and disconnected-origin behavior. 4. Load-test cold cache, expiry, and mass invalidation with shielding and request collapse; verify privacy, correctness, origin capacity, and observable cache reasons. 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.