1# Cache Reserve Patterns
2 
3## Best Practices
4 
5### 1. Always Enable Tiered Cache
6 
7```typescript
8// Cache Reserve is designed for use WITH Tiered Cache
9const configuration = {
10  tieredCache: 'enabled',    // Required for optimal performance
11  cacheReserve: 'enabled',   // Works best with Tiered Cache
12  
13  hierarchy: [
14    'Lower-Tier Cache (visitor)',
15    'Upper-Tier Cache (origin region)',
16    'Cache Reserve (persistent)',
17    'Origin'
18  ]
19};
20```
21 
22### 2. Set Appropriate Cache-Control Headers
23 
24```typescript
25// Origin response headers for Cache Reserve eligibility
26const originHeaders = {
27  'Cache-Control': 'public, max-age=86400', // 24hr (minimum 10hr)
28  'Content-Length': '1024000', // Required
29  'Cache-Tag': 'images,product-123', // Optional: purging
30  'ETag': '"abc123"', // Optional: revalidation
31  // Avoid: 'Set-Cookie' and 'Vary: *' prevent caching
32};
33```
34 
35### 3. Use Cache Rules for Fine-Grained Control
36 
37```typescript
38// Different TTLs for different content types
39const cacheRules = [
40  {
41    description: 'Long-term cache for immutable assets',
42    expression: '(http.request.uri.path matches "^/static/.*\\.[a-f0-9]{8}\\.")',
43    action_parameters: {
44      cache_reserve: { eligible: true },
45      edge_ttl: { mode: 'override_origin', default: 2592000 }, // 30 days
46      cache: true
47    }
48  },
49  {
50    description: 'Moderate cache for regular images',
51    expression: '(http.request.uri.path matches "\\.(jpg|png|webp)$")',
52    action_parameters: {
53      cache_reserve: { eligible: true },
54      edge_ttl: { mode: 'override_origin', default: 86400 }, // 24 hours
55      cache: true
56    }
57  },
58  {
59    description: 'Exclude API from Cache Reserve',
60    expression: '(http.request.uri.path matches "^/api/")',
61    action_parameters: { cache_reserve: { eligible: false }, cache: false }
62  }
63];
64```
65 
66### 4. Making Assets Cache Reserve Eligible from Workers
67 
68**Note**: This modifies response headers to meet eligibility criteria but does NOT directly control Cache Reserve storage (which is zone-level automatic).
69 
70```typescript
71export default {
72  async fetch(request: Request, env: Env): Promise<Response> {
73    const response = await fetch(request);
74    if (!response.ok) return response;
75    
76    const headers = new Headers(response.headers);
77    headers.set('Cache-Control', 'public, max-age=36000'); // 10hr minimum
78    headers.delete('Set-Cookie'); // Blocks caching
79    
80    // Ensure Content-Length present
81    if (!headers.has('Content-Length')) {
82      const blob = await response.blob();
83      headers.set('Content-Length', blob.size.toString());
84      return new Response(blob, { status: response.status, headers });
85    }
86    
87    return new Response(response.body, { status: response.status, headers });
88  }
89};
90```
91 
92### 5. Hostname Best Practices
93 
94Use Worker's hostname for efficient caching - avoid overriding hostname unnecessarily.
95 
96## Architecture Patterns
97 
98### Multi-Tier Caching + Immutable Assets
99 
100```typescript
101// Optimal: L1 (visitor) → L2 (region) → L3 (Cache Reserve) → Origin
102export default {
103  async fetch(request: Request, env: Env): Promise<Response> {
104    const url = new URL(request.url);
105    const isImmutable = /\.[a-f0-9]{8,}\.(js|css|jpg|png|woff2)$/.test(url.pathname);
106    const response = await fetch(request);
107    
108    if (isImmutable) {
109      const headers = new Headers(response.headers);
110      headers.set('Cache-Control', 'public, max-age=31536000, immutable');
111      return new Response(response.body, { status: response.status, headers });
112    }
113    return response;
114  }
115};
116```
117 
118## Cost Optimization
119 
120### Cost Calculator
121 
122```typescript
123interface CacheReserveEstimate {
124  avgAssetSizeGB: number;
125  uniqueAssets: number;
126  monthlyReads: number;
127  monthlyWrites: number;
128  originEgressCostPerGB: number; // e.g., AWS: $0.09/GB
129}
130 
131function estimateMonthlyCost(input: CacheReserveEstimate) {
132  // Cache Reserve pricing
133  const storageCostPerGBMonth = 0.015;
134  const classAPerMillion = 4.50; // writes
135  const classBPerMillion = 0.36; // reads
136  
137  // Calculate Cache Reserve costs
138  const totalStorageGB = input.avgAssetSizeGB * input.uniqueAssets;
139  const storageCost = totalStorageGB * storageCostPerGBMonth;
140  const writeCost = (input.monthlyWrites / 1_000_000) * classAPerMillion;
141  const readCost = (input.monthlyReads / 1_000_000) * classBPerMillion;
142  
143  const cacheReserveCost = storageCost + writeCost + readCost;
144  
145  // Calculate origin egress cost (what you'd pay without Cache Reserve)
146  const totalTrafficGB = (input.monthlyReads * input.avgAssetSizeGB);
147  const originEgressCost = totalTrafficGB * input.originEgressCostPerGB;
148  
149  // Savings calculation
150  const savings = originEgressCost - cacheReserveCost;
151  const savingsPercent = ((savings / originEgressCost) * 100).toFixed(1);
152  
153  return {
154    cacheReserveCost: `$${cacheReserveCost.toFixed(2)}`,
155    originEgressCost: `$${originEgressCost.toFixed(2)}`,
156    monthlySavings: `$${savings.toFixed(2)}`,
157    savingsPercent: `${savingsPercent}%`,
158    breakdown: {
159      storage: `$${storageCost.toFixed(2)}`,
160      writes: `$${writeCost.toFixed(2)}`,
161      reads: `$${readCost.toFixed(2)}`,
162    }
163  };
164}
165 
166// Example: Media library
167const mediaLibrary = estimateMonthlyCost({
168  avgAssetSizeGB: 0.005, // 5MB images
169  uniqueAssets: 10_000,
170  monthlyReads: 5_000_000,
171  monthlyWrites: 50_000,
172  originEgressCostPerGB: 0.09, // AWS S3
173});
174 
175console.log(mediaLibrary);
176// {
177//   cacheReserveCost: "$9.98",
178//   originEgressCost: "$25.00",
179//   monthlySavings: "$15.02",
180//   savingsPercent: "60.1%",
181//   breakdown: { storage: "$0.75", writes: "$0.23", reads: "$9.00" }
182// }
183```
184 
185### Optimization Guidelines
186 
187- **Set appropriate TTLs**: 10hr minimum, 24hr+ optimal for stable content, 30d max cautiously
188- **Cache high-value stable assets**: Images, media, fonts, archives, documentation
189- **Exclude frequently changing**: APIs, user-specific content, real-time data
190- **Compression note**: Cache Reserve fetches uncompressed from origin, serves compressed to visitors - factor in origin egress costs
191 
192## See Also
193 
194- [README](./README.md) - Overview and core concepts
195- [Configuration](./configuration.md) - Setup and Cache Rules
196- [API Reference](./api.md) - Purging and monitoring
197- [Gotchas](./gotchas.md) - Common issues and troubleshooting
198