CDN Caching (Edge)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

// Cloudflare Worker - Custom cache key
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request));
});
 
async function handleRequest(request) {
  const url = new URL(request.url);
  
  // Create custom cache key
  const cacheKeyComponents = [
    url.origin + url.pathname,     // Base URL without query params
    getSortedQueryString(url),     // Normalized query string
    getDeviceType(request),        // Device classification
    getGeoRegion(request),         // Geographic region
  ];
  
  const cacheKey = cacheKeyComponents.join('::');
  
  // Check cache with custom key
  const cache = caches.default;
  const cacheRequest = new Request(cacheKey, { cf: request.cf });
  
  let response = await cache.match(cacheRequest);
  
  if (!response) {
    // Cache miss - fetch from origin
    response = await fetch(request);
    
    // Only cache successful responses
    if (response.ok) {
      // Clone response for caching
      const responseToCache = response.clone();
      
      // Add Cache-Control if origin didn't
      if (!response.headers.get('Cache-Control')) {
        const headers = new Headers(response.headers);
        headers.set('Cache-Control', 'public, max-age=3600');
        responseToCache = new Response(responseToCache.body, {
          status: responseToCache.status,
          headers
        });
      }
      
      event.waitUntil(cache.put(cacheRequest, responseToCache));
    }
  }
  
  return response;
}
 
function getSortedQueryString(url) {
  const params = [...url.searchParams.entries()];
  // Ignore tracking parameters
  const filtered = params.filter(([key]) => 
    !['utm_source', 'utm_medium', 'ref', 'fbclid'].includes(key)
  );
  // Sort for consistent cache keys
  filtered.sort((a, b) => a[0].localeCompare(b[0]));
  return filtered.map(([k, v]) => `${k}=${v}`).join('&');
}
 
function getDeviceType(request) {
  const ua = request.headers.get('User-Agent') || '';
  if (/Mobile|Android|iPhone/i.test(ua)) return 'mobile';
  if (/Tablet|iPad/i.test(ua)) return 'tablet';
  return 'desktop';
}
 
function getGeoRegion(request) {
  // Cloudflare provides geo data
  const country = request.cf?.country || 'XX';
  const regionMap = {
    US: 'americas', CA: 'americas', MX: 'americas', BR: 'americas',
    GB: 'europe', DE: 'europe', FR: 'europe', IT: 'europe',
    JP: 'apac', CN: 'apac', IN: 'apac', AU: 'apac',
  };
  return regionMap[country] || 'other';
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# Stale-While-Revalidate: Serve stale immediately, fetch fresh in background
Cache-Control: public, max-age=60, stale-while-revalidate=300
 
# Timeline:
# 0-60 seconds:   Fresh - serve from cache
# 60-360 seconds: Stale but acceptable - serve stale, fetch fresh in background
# 360+ seconds:   Must revalidate before serving
 
# Stale-If-Error: Serve stale if origin is unreachable
Cache-Control: public, max-age=300, stale-if-error=86400
 
# Timeline:
# 0-300 seconds:    Fresh - serve from cache
# 300+ seconds:     Stale - if origin returns 5xx or times out, serve stale
# After 86400 secs: Don't serve stale even on errors
 
# Combined pattern for resilient API responses
Cache-Control: public, max-age=60, stale-while-revalidate=300, stale-if-error=86400
 
# This provides:
# - 60 seconds of fresh cache
# - Immediate response with background refresh for 5 more minutes
# - Graceful degradation to stale content during outages for up to 24 hours

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

// Cloudflare API - Purge specific URLs
async function purgeUrls(urls) {
  const response = await fetch(
    `https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ files: urls }),
    }
  );
  return response.json();
}
 
// Purge by prefix (wildcard)
async function purgePrefix(prefix) {
  // Not all CDNs support this; check your provider
  const response = await fetch(
    `https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ prefixes: [prefix] }),
    }
  );
  return response.json();
}
 
// Purge by cache tag (surrogate key)
// Requires adding Surrogate-Key header to responses
async function purgeByTag(tags) {
  // Fastly API example
  const requests = tags.map(tag =>
    fetch(`https://api.fastly.com/service/${SERVICE_ID}/purge/${tag}`, {
      method: 'POST',
      headers: { 'Fastly-Key': API_KEY },
    })
  );
  return Promise.all(requests);
}
 
// Usage in deployment pipeline
async function deployAndInvalidate() {
  // 1. Deploy new version of assets
  await deployAssets();
  
  // 2. Purge old cached content
  await purgeByTag(['static-assets', 'v1.2.3']);
  
  // 3. Warm the cache for critical paths
  await warmCache([
    'https://example.com/',
    'https://example.com/products',
    'https://example.com/api/featured',
  ]);
  
  console.log('Deployment complete, caches invalidated and warmed');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

# AWS CloudFront Distribution with Origin Shield
AWSTemplateFormatVersion: '2010-09-09'
Description: CloudFront distribution with Origin Shield configured
 
Resources:
  CDNDistribution:
    Type: AWS::CloudFront::Distribution
    Properties:
      DistributionConfig:
        Origins:
          - Id: MyOrigin
            DomainName: origin.example.com
            CustomOriginConfig:
              HTTPPort: 80
              HTTPSPort: 443
              OriginProtocolPolicy: https-only
              OriginSSLProtocols:
                - TLSv1.2
            
            # Origin Shield Configuration
            OriginShield:
              Enabled: true
              # Choose region closest to your origin
              OriginShieldRegion: us-east-1
            
            # Origin timeout and retry settings
            ConnectionAttempts: 3
            ConnectionTimeout: 10
            
        DefaultCacheBehavior:
          TargetOriginId: MyOrigin
          ViewerProtocolPolicy: redirect-to-https
          
          # Cache settings
          CachePolicyId: !Ref CachePolicy
          
        # Enable compression
        PriceClass: PriceClass_All
        Enabled: true
 
  CachePolicy:
    Type: AWS::CloudFront::CachePolicy
    Properties:
      CachePolicyConfig:
        Name: OptimizedCaching
        DefaultTTL: 86400      # 1 day
        MaxTTL: 31536000       # 1 year
        MinTTL: 0
        
        ParametersInCacheKeyAndForwardedToOrigin:
          CookiesConfig:
            CookieBehavior: none
          HeadersConfig:
            HeaderBehavior: whitelist
            Headers:
              - Accept-Encoding
              - Accept-Language
          QueryStringsConfig:
            QueryStringBehavior: all
          
          EnableAcceptEncodingBrotli: true
          EnableAcceptEncodingGzip: true

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# API endpoint: Product catalog (changes hourly, allows staleness)
Cache-Control: public, max-age=60, stale-while-revalidate=300
# CDN serves fresh for 1 minute, then stale while refreshing for 5 more minutes
 
# API endpoint: Stock prices (changes constantly, minimal staleness)
Cache-Control: public, max-age=1, stale-while-revalidate=5
# Only 1-second freshness, but still absorbs traffic spikes
 
# API endpoint: Trending content (social proof, some staleness OK)
Cache-Control: public, max-age=30, stale-while-revalidate=60
# Updates every 30 seconds; users see fresh-ish content
 
# API endpoint: User-specific but not sensitive (recommendations)
Cache-Control: private, max-age=300
# Browser caches 5 minutes; CDN doesn't cache (private)
 
# Approach: Geographic variations of "public" content
# Cache different versions by region
Vary: Accept-Encoding
# Plus CDN-level configuration to vary by geographic region

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

// Edge worker: Personalized content with cached base
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event));
});
 
async function handleRequest(event) {
  const request = event.request;
  const url = new URL(request.url);
  
  // Example: Homepage personalization
  if (url.pathname === '/') {
    return personalizeHomepage(event);
  }
  
  // Pass through to origin
  return fetch(request);
}
 
async function personalizeHomepage(event) {
  const request = event.request;
  
  // Fetch cached base HTML (generic version)
  const cache = caches.default;
  const baseUrl = new URL(request.url);
  baseUrl.searchParams.set('base', 'true');
  
  let baseHtml = await cache.match(baseUrl);
  
  if (!baseHtml) {
    baseHtml = await fetch(baseUrl.toString());
    event.waitUntil(cache.put(baseUrl, baseHtml.clone()));
  }
  
  // Get personalization data (from cookie or API)
  const userData = await getUserData(request);
  
  // Transform cached base with personalization
  const personalizedHtml = await personalizeHtml(baseHtml, userData);
  
  return new Response(personalizedHtml, {
    headers: {
      'Content-Type': 'text/html',
      'Cache-Control': 'private, max-age=0',  // Don't cache personalized version
    },
  });
}
 
async function getUserData(request) {
  const cookie = request.headers.get('Cookie');
  const userId = extractUserIdFromCookie(cookie);
  
  if (!userId) {
    return { isAnonymous: true, segments: [] };
  }
  
  // Fetch user segments (cached at edge)
  const segmentsUrl = `https://api.example.com/users/${userId}/segments`;
  const segmentsResponse = await fetch(segmentsUrl, {
    cf: { cacheTtl: 300 }  // Cache user segments for 5 minutes
  });
  
  return segmentsResponse.json();
}
 
async function personalizeHtml(response, userData) {
  const html = await response.text();
  
  // Use HTMLRewriter for streaming transformation
  return new HTMLRewriter()
    .on('[data-personalize="greeting"]', {
      element(element) {
        element.setInnerContent(
          userData.isAnonymous ? 'Welcome!' : `Welcome back, ${userData.name}!`
        );
      }
    })
    .on('[data-segment]', {
      element(element) {
        const targetSegment = element.getAttribute('data-segment');
        if (!userData.segments.includes(targetSegment)) {
          element.remove();
        }
      }
    })
    .transform(new Response(html));
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

// CDN Analytics Query - Example using CloudWatch for CloudFront
const AWS = require('aws-sdk');
const cloudwatch = new AWS.CloudWatch();
 
async function getCDNMetrics(distributionId, hours = 24) {
  const endTime = new Date();
  const startTime = new Date(endTime - hours * 60 * 60 * 1000);
  
  const metrics = [
    { name: 'Requests', stat: 'Sum' },
    { name: 'BytesDownloaded', stat: 'Sum' },
    { name: 'CacheHitRate', stat: 'Average' },
    { name: 'OriginLatency', stat: 'Average' },
    { name: '4xxErrorRate', stat: 'Average' },
    { name: '5xxErrorRate', stat: 'Average' },
  ];
  
  const params = {
    Namespace: 'AWS/CloudFront',
    StartTime: startTime,
    EndTime: endTime,
    Period: 3600,  // 1 hour granularity
    Dimensions: [
      { Name: 'DistributionId', Value: distributionId },
      { Name: 'Region', Value: 'Global' },
    ],
    MetricDataQueries: metrics.map((m, i) => ({
      Id: `m${i}`,
      MetricStat: {
        Metric: {
          Namespace: 'AWS/CloudFront',
          MetricName: m.name,
          Dimensions: [
            { Name: 'DistributionId', Value: distributionId },
            { Name: 'Region', Value: 'Global' },
          ],
        },
        Period: 3600,
        Stat: m.stat,
      },
    })),
  };
  
  const data = await cloudwatch.getMetricData(params).promise();
  
  // Calculate summary
  const summary = {
    totalRequests: sum(data.MetricDataResults[0].Values),
    bytesServed: sum(data.MetricDataResults[1].Values),
    avgCacheHitRate: average(data.MetricDataResults[2].Values),
    avgOriginLatency: average(data.MetricDataResults[3].Values),
    errorRate: average(data.MetricDataResults[4].Values) + 
               average(data.MetricDataResults[5].Values),
  };
  
  return summary;
}
 
// Set up alerting for cache issues
async function checkCacheHealth(distributionId) {
  const metrics = await getCDNMetrics(distributionId, 1);
  
  const alerts = [];
  
  if (metrics.avgCacheHitRate < 0.7) {
    alerts.push({
      severity: 'warning',
      message: `Cache hit rate low: ${(metrics.avgCacheHitRate * 100).toFixed(1)}%`,
      action: 'Review TTL configurations and Vary headers',
    });
  }
  
  if (metrics.avgOriginLatency > 500) {
    alerts.push({
      severity: 'critical',
      message: `Origin latency high: ${metrics.avgOriginLatency.toFixed(0)}ms`,
      action: 'Check origin server health and network path',
    });
  }
  
  if (metrics.errorRate > 0.01) {
    alerts.push({
      severity: 'critical',
      message: `Error rate elevated: ${(metrics.errorRate * 100).toFixed(2)}%`,
      action: 'Investigate origin errors in logs',
    });
  }
  
  return alerts;
}