@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/gemini-cli/perf-cache-invalidation/SKILL.md

@@ -0,0 +1,228 @@
+# Cache Invalidation
+
+> Solve the hardest problem in computer science — cache invalidation strategies including TTL-based expiry, event-driven invalidation, versioned cache keys, cache stampede prevention with locking and probabilistic early expiration, and fan-out invalidation for denormalized data.
+
+## When to Use
+
+- Users see stale data after content updates and you need faster cache freshness
+- Cache expiry causes thundering herd / stampede on the origin or database
+- A content management system needs real-time content updates across cached pages
+- Denormalized cache entries reference data that changes independently
+- You need to choose between TTL-based and event-driven invalidation
+- Cache miss storms after deploys or cache restarts overload the backend
+- Distributed caches across multiple regions need coordinated invalidation
+- Versioned cache keys are being considered to avoid explicit invalidation
+- Rate of content change varies by entity (some change hourly, some yearly)
+- Cache invalidation bugs cause data inconsistency between cache and database
+
+## Instructions
+
+1. **Choose an invalidation strategy.** Match the strategy to your consistency requirements:
+
+   | Strategy              | Freshness                      | Complexity | Best For                         |
+   | --------------------- | ------------------------------ | ---------- | -------------------------------- |
+   | TTL-based             | Eventual (up to TTL)           | Low        | Content that tolerates staleness |
+   | Event-driven          | Near-real-time                 | Medium     | CMS, user-facing content         |
+   | Versioned keys        | Immediate                      | Medium     | Immutable data, API responses    |
+   | Hybrid (TTL + events) | Near-real-time with safety net | High       | Most production systems          |
+
+2. **Implement TTL-based expiration with jitter.** Add random jitter to prevent synchronized expiry:
+
+   ```javascript
+   function setWithJitter(key, value, baseTTL) {
+     // Add +/- 10% jitter to prevent synchronized expiry
+     const jitter = baseTTL * 0.1 * (Math.random() * 2 - 1);
+     const ttl = Math.round(baseTTL + jitter);
+     return redis.setex(key, ttl, JSON.stringify(value));
+   }
+
+   // 300 items with baseTTL=3600 expire between 3240-3960 seconds
+   // instead of all expiring at exactly 3600 seconds
+   ```
+
+3. **Implement event-driven invalidation.** Publish invalidation events when source data changes:
+
+   ```javascript
+   // On data change: publish invalidation event
+   async function updateArticle(articleId, data) {
+     await db.articles.update(articleId, data);
+
+     // Publish invalidation event
+     await redis.publish(
+       'cache:invalidate',
+       JSON.stringify({
+         type: 'article',
+         id: articleId,
+         tags: ['homepage', `section:${data.section}`, `author:${data.authorId}`],
+       })
+     );
+   }
+
+   // Cache subscriber: listen for invalidation events
+   const subscriber = redis.duplicate();
+   subscriber.subscribe('cache:invalidate');
+   subscriber.on('message', (channel, message) => {
+     const event = JSON.parse(message);
+     // Delete specific cache entry
+     redis.del(`article:${event.id}`);
+     // Delete related cache entries
+     event.tags.forEach((tag) => invalidateByTag(tag));
+   });
+   ```
+
+4. **Use versioned cache keys for immutable patterns.** Instead of invalidating, change the key:
+
+   ```javascript
+   // Version stored in a lightweight metadata key
+   async function getArticle(articleId) {
+     const version = await redis.get(`article:${articleId}:version`);
+     const cacheKey = `article:${articleId}:v${version}`;
+
+     const cached = await redis.get(cacheKey);
+     if (cached) return JSON.parse(cached);
+
+     const article = await db.articles.findById(articleId);
+     await redis.setex(cacheKey, 86400, JSON.stringify(article));
+     return article;
+   }
+
+   async function updateArticle(articleId, data) {
+     await db.articles.update(articleId, data);
+     // Increment version — old key naturally expires via TTL
+     await redis.incr(`article:${articleId}:version`);
+   }
+   ```
+
+5. **Prevent cache stampede with locking.** When a cache entry expires, only one process should recompute:
+
+   ```javascript
+   async function getWithLock(key, computeFn, ttl = 3600) {
+     const cached = await redis.get(key);
+     if (cached) return JSON.parse(cached);
+
+     // Try to acquire lock
+     const lockKey = `lock:${key}`;
+     const acquired = await redis.set(lockKey, '1', 'NX', 'EX', 30);
+
+     if (acquired) {
+       try {
+         // This process recomputes
+         const value = await computeFn();
+         await redis.setex(key, ttl, JSON.stringify(value));
+         return value;
+       } finally {
+         await redis.del(lockKey);
+       }
+     } else {
+       // Another process is recomputing — wait and retry
+       await new Promise((resolve) => setTimeout(resolve, 100));
+       return getWithLock(key, computeFn, ttl);
+     }
+   }
+   ```
+
+6. **Implement probabilistic early expiration (XFetch).** Proactively refresh cache entries before they expire:
+
+   ```javascript
+   async function getWithXFetch(key, computeFn, ttl = 3600, beta = 1.0) {
+     const cached = await redis.get(key);
+     if (cached) {
+       const entry = JSON.parse(cached);
+       const now = Date.now();
+       const expiry = entry.expiry;
+       const delta = entry.computeTime; // ms to recompute
+
+       // Probabilistic early recomputation
+       // Higher beta = more aggressive early refresh
+       const shouldRefresh = now - delta * beta * Math.log(Math.random()) >= expiry;
+
+       if (!shouldRefresh) {
+         return entry.value;
+       }
+     }
+
+     // Recompute
+     const start = Date.now();
+     const value = await computeFn();
+     const computeTime = Date.now() - start;
+
+     await redis.setex(
+       key,
+       ttl,
+       JSON.stringify({
+         value,
+         expiry: Date.now() + ttl * 1000,
+         computeTime,
+       })
+     );
+
+     return value;
+   }
+   ```
+
+7. **Handle fan-out invalidation for denormalized data.** When a user updates their name, invalidate all cached entities that embed that name:
+
+   ```javascript
+   // Maintain a reverse index: entity → dependent cache keys
+   async function invalidateUser(userId) {
+     const dependents = await redis.smembers(`deps:user:${userId}`);
+     // dependents might be: ['article:123', 'comment:456', 'team:789']
+
+     if (dependents.length > 0) {
+       await redis.del(...dependents);
+       await redis.del(`deps:user:${userId}`);
+     }
+     await redis.del(`user:${userId}`);
+   }
+   ```
+
+## Details
+
+### The XFetch Algorithm
+
+The XFetch algorithm (from the paper "Optimal Probabilistic Cache Stampede Prevention") provides a mathematically optimal solution to cache stampede. Instead of waiting for expiry and then competing for a lock, XFetch probabilistically triggers recomputation before expiry. The probability increases as the entry approaches expiry and scales with the computation cost (expensive computations start refreshing earlier). The beta parameter controls aggressiveness: beta=1.0 is optimal for single-threaded access, beta=2.0+ for high-concurrency scenarios.
+
+### Worked Example: Facebook Lease-Based Invalidation
+
+Facebook's Memcache infrastructure (described in their "Scaling Memcache at Facebook" NSDI 2013 paper) implements lease-based cache invalidation. When a cache miss occurs, the client receives a lease token from Memcache. Only the lease holder can write the recomputed value back to cache — other concurrent requests for the same key receive a "wait" response and retry after a short delay (typically 10ms). This prevents the stampede problem without explicit locking: at most one backend request recomputes any given cache entry, regardless of how many concurrent cache misses occur. The lease has a 10-second timeout as a safety net.
+
+### Worked Example: Stripe Versioned Cache Keys
+
+Stripe uses versioned cache keys with monotonically increasing generation numbers for their API response caches. When underlying data changes, the generation number is incremented atomically (a single Redis INCR operation). Cache invalidation is therefore a metadata update, not a cache purge. Old cache entries naturally expire via TTL. This approach eliminates the race condition between "delete old entry" and "write new entry" — the new version is simply a different key. It also provides implicit cache warmup: the old version continues serving until the new version is populated.
+
+### Anti-Patterns
+
+**Invalidating by deleting without stampede protection.** If a popular cache entry is deleted, N concurrent requests all see a cache miss simultaneously. All N requests hit the database. With 1,000 concurrent users and a 500ms query, that is 1,000 simultaneous database queries for the same data. Use locking, XFetch, or stale-while-revalidate.
+
+**Using wallclock-based TTLs without jitter.** If 10,000 cache entries are all set with TTL=3600 at the same time (e.g., during cache warming), they all expire at the same second. Add 5-10% random jitter to spread expiry over a time window.
+
+**Invalidating parent caches without derived caches.** If a user's name changes and you invalidate `user:123` but not `article:456` (which embeds the user's name), the article shows stale author information. Maintain dependency tracking for denormalized caches.
+
+**Fire-and-forget invalidation without confirmation.** Network drops, Redis failovers, or message queue delays can silently prevent invalidation messages from arriving. Implement at-least-once delivery for critical invalidation events and use TTL as a safety net.
+
+## Source
+
+- "Scaling Memcache at Facebook" (NSDI 2013) — https://www.usenix.org/conference/nsdi13/technical-sessions/presentation/nishtala
+- "Optimal Probabilistic Cache Stampede Prevention" (XFetch algorithm) — https://cseweb.ucsd.edu/~avattani/papers/cache_stampede.pdf
+- Redis documentation on distributed locking (Redlock) — https://redis.io/docs/manual/patterns/distributed-locks/
+- Martin Kleppmann, "Designing Data-Intensive Applications" (O'Reilly), Chapter 5
+- CDN purging best practices — Fastly, Cloudflare, Akamai documentation
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- Cache stampede is prevented via locking, XFetch, or stale-while-revalidate on high-traffic entries.
+- TTL-based expiry uses jitter to prevent synchronized cache expiration storms.
+- Denormalized cache entries are invalidated when their source data changes.

package/dist/agents/skills/gemini-cli/perf-cache-invalidation/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-cache-invalidation
+version: '1.0.0'
+description: Cache invalidation — TTL strategies, event-driven invalidation, cache stampede prevention, and versioned cache keys
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-server-side-caching
+  - perf-browser-cache
+  - perf-cdn-cache-control
+  - perf-cdn-strategies
+stack_signals: []
+keywords:
+  - cache invalidation
+  - ttl
+  - cache stampede
+  - thundering herd
+  - event-driven invalidation
+  - versioned keys
+  - cache warming
+  - probabilistic early expiration
+  - lock-based invalidation
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/perf-cdn-cache-control/SKILL.md

@@ -0,0 +1,198 @@
+# CDN Cache Control
+
+> Master CDN-specific caching mechanics — cache key composition, Vary header impact, Surrogate-Control directives, tag-based instant purging, edge TTL management with s-maxage, and edge-side includes for granular partial caching.
+
+## When to Use
+
+- CDN cache hit ratio is below 90% and you need to diagnose cache fragmentation
+- Cache purging takes too long or purges too broadly (entire zone instead of targeted paths)
+- You need different TTLs for CDN edge vs browser cache (s-maxage vs max-age)
+- Vary header configuration is causing excessive cache fragmentation
+- Personalized content is incorrectly cached or served to wrong users at the CDN
+- Edge-side includes (ESI) are being evaluated for partial page caching
+- Cache warming is needed after deployments to prevent origin overload
+- Surrogate-Key or Cache-Tag headers need to be implemented for targeted purging
+- CDN configuration needs to handle content negotiation (encoding, language, format)
+- Flash sale or high-traffic events require CDN cache strategy planning
+
+## Instructions
+
+1. **Separate CDN TTL from browser TTL.** Use `s-maxage` for CDN and `max-age` for browser:
+
+   ```
+   # CDN caches for 1 hour, browser caches for 5 minutes
+   Cache-Control: public, max-age=300, s-maxage=3600
+
+   # CDN caches for 1 day, browser must always revalidate
+   Cache-Control: public, max-age=0, s-maxage=86400, must-revalidate
+   ```
+
+   `s-maxage` only applies to shared caches (CDN, proxy). Browsers ignore it and use `max-age`.
+
+2. **Configure Surrogate-Control for CDN-specific behavior.** Some CDNs support Surrogate-Control headers for directives that should not reach the browser:
+
+   ```
+   # Fastly/Varnish Surrogate-Control
+   Surrogate-Control: max-age=86400
+   Cache-Control: no-cache
+
+   # CDN caches for 1 day; browser always revalidates
+   # CDN strips Surrogate-Control before forwarding to browser
+   ```
+
+3. **Implement tag-based cache purging.** Tag individual responses with cache keys for targeted invalidation:
+
+   ```
+   # Tag responses with content identifiers
+   Surrogate-Key: article-12345 section-news author-jane homepage
+   # (Fastly)
+
+   Cache-Tag: article-12345, section-news, author-jane, homepage
+   # (Cloudflare)
+
+   # Purge by tag (all responses tagged with "article-12345")
+   # Fastly API:
+   POST /service/{id}/purge/article-12345
+
+   # Cloudflare API:
+   POST /zones/{id}/purge_cache
+   {"tags": ["article-12345"]}
+   ```
+
+4. **Optimize cache key composition.** The cache key determines what is considered a unique response. Audit and simplify:
+
+   ```
+   # Default cache key (often too broad):
+   scheme + host + path + query-string + cookies + accept-encoding + accept-language
+
+   # Optimized cache key:
+   scheme + host + path + sorted-query(keep: page, q; strip: utm_*, fbclid)
+
+   # CDN configuration (Cloudflare example):
+   # Cache Rules → Custom cache key → Query string: Include specific
+   ```
+
+5. **Configure Vary header correctly.** The Vary header tells caches to store separate versions based on specific request headers:
+
+   ```
+   # Good: vary on encoding (mandatory for compressed content)
+   Vary: Accept-Encoding
+
+   # Acceptable: vary on encoding and language
+   Vary: Accept-Encoding, Accept-Language
+
+   # Bad: vary on everything (disables caching)
+   Vary: *
+
+   # Bad: vary on Cookie (per-user cache = 0% hit rate)
+   Vary: Cookie
+   ```
+
+   Each unique combination of Vary header values creates a separate cache entry. `Vary: Accept-Encoding` typically creates 2-3 variants (br, gzip, identity). Adding `Accept-Language` with 10 languages creates 20-30 variants.
+
+6. **Implement cache warming after purge.** After a cache purge or deploy, pre-populate the CDN cache:
+
+   ```bash
+   # Warm cache for top pages from multiple PoP regions
+   URLS=(
+     "https://example.com/"
+     "https://example.com/products"
+     "https://example.com/about"
+   )
+   for url in "${URLS[@]}"; do
+     curl -s -o /dev/null -w "%{http_code} %{time_total}s %{url_effective}\n" "$url"
+   done
+   ```
+
+7. **Use soft purge instead of hard purge.** Soft purge marks content as stale rather than deleting it. The stale content is served while the CDN fetches a fresh copy from origin:
+
+   ```
+   # Hard purge: content deleted, next request goes to origin (cache miss)
+   # Soft purge: content marked stale, served while revalidating (no miss)
+
+   # Fastly soft purge:
+   PURGE /path HTTP/1.1
+   Fastly-Soft-Purge: 1
+   ```
+
+## Details
+
+### Cache Key Design Principles
+
+The ideal cache key includes only information that changes the response content. Including extraneous information (tracking parameters, session cookies) creates unique cache entries for identical content.
+
+Common cache key pollution sources:
+
+- **UTM parameters** (`utm_source`, `utm_medium`, `utm_campaign`) — strip from cache key
+- **Session cookies** — exclude from cache key for public content
+- **Random query parameters** — cache-busting params like `_=timestamp`
+- **Client hints** — `Sec-CH-UA`, `Sec-CH-UA-Mobile` create device-specific entries
+
+### Edge-Side Includes (ESI)
+
+ESI allows a CDN to assemble a page from multiple cached fragments, each with its own TTL:
+
+```html
+<!-- Page template (TTL: 5 minutes) -->
+<html>
+  <header>
+    <esi:include src="/fragments/nav" />
+  </header>
+  <main>
+    <esi:include src="/fragments/article-12345" />
+  </main>
+  <aside>
+    <esi:include src="/fragments/trending" />
+  </aside>
+</html>
+
+<!-- /fragments/nav (TTL: 1 hour — rarely changes) -->
+<!-- /fragments/article-12345 (TTL: 1 day — content-hashed) -->
+<!-- /fragments/trending (TTL: 5 minutes — frequently updated) -->
+```
+
+### Worked Example: The New York Times Tag-Based Purging
+
+The New York Times uses Fastly's Surrogate-Key headers to tag every article response with its article ID, section, author, and homepage status. When an editor updates an article, the CMS sends a purge request for that article's tag. Fastly purges all cached variants of that article across all global PoPs in under 150ms. Without tag-based purging, they would need to purge by URL — but each article may be served at multiple URLs (canonical, AMP, mobile) and embedded in section pages and the homepage. Tag-based purging handles all these variants with a single API call.
+
+### Worked Example: Shopify Flash Sale Caching
+
+Shopify handles 80,000+ requests per second during flash sales using a Varnish-based CDN configuration with grace mode. During normal operation, product pages are cached with a 60-second TTL. During flash sales, they extend the grace (stale-while-revalidate) period to 300 seconds. If the origin becomes slow or unavailable under load, the CDN continues serving stale content while attempting to refresh. This prevents the thundering herd problem: instead of all cache misses hitting origin simultaneously, a single background refresh updates the cache while all other requests are served from stale.
+
+### Anti-Patterns
+
+**Vary: \* (disables caching entirely).** The `*` value tells caches that the response varies on everything — effectively uncacheable. If you see `Vary: *` in responses, it is a misconfiguration. Identify the actual varying dimensions and list them explicitly.
+
+**Including Cookie in the cache key for public content.** If the page content is the same for all users, cookies should not be part of the cache key. Each unique cookie value creates a separate cache entry, resulting in near-0% hit rates. Use `private` caching or client-side personalization instead.
+
+**Purging the entire cache instead of targeted paths.** A full-zone purge forces every resource to be re-fetched from origin. For a site with 100,000 cached resources, this creates a thundering herd on origin. Use path-based or tag-based purging to invalidate only what changed.
+
+**Not separating browser TTL from CDN TTL.** Without `s-maxage`, the CDN uses `max-age` — meaning the browser and CDN have identical caching behavior. A 5-minute browser TTL makes sense (users see fresh content), but the CDN should have a longer TTL (1 hour) to maximize edge cache hits.
+
+## Source
+
+- RFC 9111: HTTP Caching — https://www.rfc-editor.org/rfc/rfc9111
+- Fastly Surrogate-Key documentation — https://docs.fastly.com/en/guides/working-with-surrogate-keys
+- Cloudflare Cache-Tag purging — https://developers.cloudflare.com/cache/how-to/purge-cache/
+- W3C Edge Side Includes specification — https://www.w3.org/TR/esi-lang
+- Varnish Cache documentation — https://varnish-cache.org/docs/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **related_skills:** perf-browser-cache, perf-cdn-strategies, perf-cache-invalidation, perf-compression, otel-performance-insights, api-http-caching
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- CDN cache hit ratio exceeds 90% with cache key fragmentation minimized.
+- s-maxage is configured separately from max-age for appropriate CDN vs browser TTLs.
+- Tag-based or path-based purging is implemented instead of full-zone cache purges.

package/dist/agents/skills/gemini-cli/perf-cdn-cache-control/skill.yaml

@@ -0,0 +1,40 @@
+name: perf-cdn-cache-control
+version: '1.0.0'
+description: CDN cache control — cache keys, Vary header strategies, surrogate control, cache purging, and edge TTL management
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-browser-cache
+  - perf-cdn-strategies
+  - perf-cache-invalidation
+  - perf-compression
+  - otel-performance-insights
+  - api-http-caching
+stack_signals: []
+keywords:
+  - cdn cache
+  - cache key
+  - vary header
+  - surrogate-control
+  - cache purge
+  - edge ttl
+  - s-maxage
+  - cache tag
+  - instant purge
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/perf-cdn-strategies/SKILL.md

@@ -0,0 +1,161 @@
+# CDN Strategies
+
+> Design and optimize Content Delivery Network architecture — tiered caching, origin shielding, edge compute patterns, cache hit ratio optimization, multi-CDN strategies, and geographic routing for globally distributed applications.
+
+## When to Use
+
+- Users in distant regions experience TTFB exceeding 500ms due to origin server distance
+- Origin server is under heavy load from cache misses and you need to reduce origin traffic
+- Cache hit ratio is below 90% and you need to improve CDN efficiency
+- You are designing a multi-region application and need a CDN-first architecture
+- Flash sales or viral content cause traffic spikes that overwhelm the origin
+- Edge compute is being evaluated for personalization, A/B testing, or authentication
+- Multiple CDN providers need to be orchestrated for redundancy and performance
+- Static assets, API responses, and HTML pages have different caching requirements
+- You need to understand PoP (Point of Presence) architecture and anycast routing
+- Geographic content restrictions or data sovereignty requirements affect CDN configuration
+
+## Instructions
+
+1. **Understand CDN architecture.** A CDN consists of Points of Presence (PoPs) distributed globally. Each PoP contains edge servers that cache content. When a user requests a resource, DNS (typically anycast) routes them to the nearest PoP.
+
+   ```
+   User Request Flow:
+   User → DNS (anycast) → Nearest PoP Edge → [Cache HIT] → Response
+                                             → [Cache MISS] → Shield PoP → Origin → Response
+   ```
+
+2. **Configure tiered caching.** Most CDNs support multi-tier caching:
+   - **Edge tier** — 200+ global PoPs, closest to users, smallest cache
+   - **Shield/Regional tier** — 10-20 regional PoPs, larger cache, reduces origin load
+   - **Origin tier** — your server(s), generates content on cache miss
+
+   Enable origin shielding to collapse multiple edge misses into a single origin request:
+
+   ```
+   Without shielding:     Edge-A miss → Origin
+                          Edge-B miss → Origin
+                          Edge-C miss → Origin  (3 origin requests)
+
+   With shielding:        Edge-A miss → Shield → Origin
+                          Edge-B miss → Shield → (cache hit)
+                          Edge-C miss → Shield → (cache hit)  (1 origin request)
+   ```
+
+3. **Optimize cache hit ratio.** Target >95% cache hit ratio for static assets, >80% for dynamic content. Strategies:
+   - Normalize cache keys (strip unnecessary query params, sort remaining params)
+   - Use `Vary` header correctly (only vary on headers that actually change the response)
+   - Set appropriate TTLs by content type (static assets: 1 year, HTML: minutes to hours)
+   - Warm cache after deploys or purges (pre-populate popular content)
+
+4. **Implement edge compute for dynamic content.** Edge compute runs application logic at the CDN edge, eliminating origin roundtrips for common operations:
+
+   ```javascript
+   // Cloudflare Worker example: A/B testing at the edge
+   export default {
+     async fetch(request) {
+       const bucket = request.headers.get('cookie')?.includes('ab=B') ? 'B' : 'A';
+       const url = new URL(request.url);
+       url.pathname = `/${bucket}${url.pathname}`;
+       return fetch(url);
+     },
+   };
+   ```
+
+5. **Design cache keys carefully.** The cache key determines what constitutes a unique cacheable response. Poor cache key design causes either cache pollution (too many unique entries) or incorrect responses (too few entries).
+
+   ```
+   Good cache key:  scheme + host + path + normalized-query
+   Bad cache key:   scheme + host + path + all-headers + cookies
+                    (creates per-user cache entries, ~0% hit rate)
+   ```
+
+6. **Configure multi-CDN for redundancy.** DNS-based routing directs traffic to the best-performing CDN:
+   - Active-active: distribute traffic across CDNs based on performance metrics
+   - Active-passive: failover to secondary CDN when primary is degraded
+   - Use tools like Citrix Intelligent Traffic Management or NS1 for real-time CDN steering
+
+7. **Monitor CDN performance.** Track these metrics:
+   - Cache hit ratio (target: >95% for static, >80% for dynamic)
+   - Origin offload percentage (percentage of requests NOT hitting origin)
+   - Edge TTFB (time from edge to user, should be <50ms)
+   - Origin TTFB (time from edge to origin on miss, identifies origin bottlenecks)
+
+## Details
+
+### Anycast Routing
+
+CDNs use anycast — the same IP address is advertised from every PoP via BGP. The internet's routing infrastructure directs each user to the geographically nearest PoP. Anycast provides automatic failover: if a PoP goes offline, BGP reconverges and traffic routes to the next nearest PoP. Typical failover time: 10-30 seconds.
+
+### Cache Warming Strategies
+
+After a deploy or cache purge, hit rates temporarily drop. Warming strategies:
+
+- **Synthetic requests** — script that requests popular URLs from each PoP
+- **Stale-while-revalidate** — serve stale content while fetching fresh in background
+- **Soft purge** — mark content as stale rather than deleting (Fastly's approach), continue serving stale while revalidating
+
+### Worked Example: Netflix Open Connect
+
+Netflix serves 125 million hours of video daily through their Open Connect CDN. Instead of using a traditional CDN, Netflix deploys custom cache appliances directly inside ISP networks. Each appliance stores the most popular content for that region (determined by machine learning prediction). This approach reduces internet transit traffic by 70% and achieves sub-10ms latency for video streams. The key insight: for high-bandwidth content, pushing cache servers into the last-mile network eliminates backbone traversal entirely.
+
+### Worked Example: The Guardian CDN-First Architecture
+
+The Guardian improved First Contentful Paint by 1.2 seconds by moving from a single-origin architecture to a CDN-first design with edge-side includes (ESI). Static page shells are cached at the edge with a 60-second TTL. Dynamic components (personalized recommendations, live scores) are fetched client-side or via ESI fragments with separate TTLs. The result: 95% of page views are served entirely from CDN edge with <50ms TTFB, compared to the previous 300-800ms origin response time. Origin requests dropped by 85%.
+
+### Anti-Patterns
+
+**Caching personalized content without proper Vary headers.** If your CDN caches a page with user-specific content (name, cart, recommendations) without varying on the correct identifier, it serves user A's data to user B. Personalized content must either use `Vary` headers correctly, be excluded from caching, or be fetched client-side after the cached shell loads.
+
+**Not configuring origin shielding.** Without shielding, a cache expiry causes every edge PoP to simultaneously request from origin. With 200 PoPs, this creates a thundering herd of 200 concurrent origin requests for the same content. Origin shielding collapses these to 1 request.
+
+**Short TTLs globally instead of tiered TTLs.** Setting `Cache-Control: max-age=60` on all content means even static assets (CSS, JS, images) are revalidated every minute. Use content-type-specific TTLs: static assets with content hashes get `max-age=31536000`, HTML gets `max-age=60, stale-while-revalidate=3600`.
+
+**Ignoring CDN cache key design.** Default cache keys often include all query parameters, cookies, and sometimes headers. A URL with analytics parameters (`?utm_source=twitter&utm_medium=social`) creates a different cache entry than the base URL, reducing hit rates. Strip non-functional query parameters from cache keys.
+
+**Using a single CDN region for global traffic.** Deploying origin servers in a single region (e.g., us-east-1) and relying solely on CDN edge caching creates a single point of failure and high shield-to-origin latency for distant PoPs. Deploy origin replicas in at least two regions and configure the CDN shield tier to route to the nearest origin.
+
+**Purging entire cache zones instead of targeted invalidation.** When a single asset changes, purging the entire cache (sometimes called a "zone purge") drops hit rates to zero temporarily and creates a thundering herd against the origin. Use surrogate keys or cache tags to purge only the specific resources that changed. Fastly, Cloudflare, and Akamai all support tag-based purging.
+
+### Decision Guidance: When to Use Edge Compute vs. Origin Logic
+
+Edge compute is ideal for latency-sensitive, low-complexity operations: URL rewrites, A/B test bucket assignment, geolocation-based routing, bot detection, and request/response header manipulation. Avoid running complex business logic at the edge — database access from edge functions introduces unpredictable latency depending on the PoP-to-database distance, and debugging distributed edge deployments is significantly harder than centralized origin debugging. A good rule of thumb: if the operation needs a database query, keep it at the origin. If it can run with only the request context and a key-value store, it belongs at the edge.
+
+### Cache Invalidation Strategies
+
+Cache invalidation is often the hardest part of CDN management. Three primary approaches:
+
+- **TTL-based expiration** — simplest approach, content expires after a fixed duration. Works well for content with predictable update cadences (news articles refresh hourly, product prices refresh every 5 minutes).
+- **Purge-on-publish** — the CMS or deploy pipeline sends a purge request when content changes. Provides near-instant freshness but requires integration between the publishing system and the CDN API.
+- **Stale-while-revalidate** — serves stale content immediately while fetching fresh content in the background. Combines low latency with eventual freshness. Best for content where serving slightly stale data is acceptable (e.g., product listing pages, blog posts).
+
+For most applications, combining TTL-based expiration with stale-while-revalidate provides the best balance: `Cache-Control: max-age=300, stale-while-revalidate=3600` serves cached content for 5 minutes, then serves stale for up to an hour while revalidating in the background.
+
+When using purge-on-publish, always implement rate limiting on purge API calls. A misconfigured deploy pipeline that purges thousands of URLs in a tight loop can overwhelm the CDN's purge infrastructure and cause cascading cache misses across all PoPs.
+
+## Source
+
+- Cloudflare CDN Architecture — https://www.cloudflare.com/learning/cdn/what-is-a-cdn/
+- Netflix Open Connect — https://openconnect.netflix.com/
+- Fastly Edge Cloud Platform documentation — https://docs.fastly.com/
+- Akamai CDN Performance Best Practices — https://developer.akamai.com/
+- "Content Delivery Networks: Fundamentals, Design, and Evolution" (Wiley)
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- Cache hit ratio exceeds 95% for static assets and 80% for cacheable dynamic content.
+- Origin shielding is enabled, reducing origin load by at least 80% for cacheable content.
+- Edge TTFB is under 50ms for cached content at all major geographic regions.