HATEOAS Caching — Caching Hypermedia Responses with ETags and Cache-Control

const express = require('express');
const crypto = require('crypto');
const app = express();

// Generate ETag from resource state
function generateETag(resource) {
  const hash = crypto.createHash('sha256');
  hash.update(JSON.stringify({
    id: resource.id,
    status: resource.status,
    updatedAt: resource.updatedAt,
    links: resource._links,
  }));
  return `"${hash.digest('hex').substring(0, 16)}"`;
}

// Conditional request middleware
function conditionalGet(req, res, next) {
  const originalJson = res.json.bind(res);
  
  res.json = function(body) {
    // Generate ETag
    const etag = generateETag(body);
    res.set('ETag', etag);
    
    // Check If-None-Match
    const clientEtag = req.headers['if-none-match'];
    if (clientEtag === etag) {
      return res.status(304).end();
    }
    
    return originalJson(body);
  };
  
  next();
}

app.get('/devices/:id', conditionalGet, (req, res) => {
  const device = getDevice(req.params.id);
  const stateLinks = getStateActions(device);
  
  res.json({
    ...device,
    _links: {
      self: { href: `/devices/${device.id}` },
      ...stateLinks,
    },
  });
});

// Invalidate cache on state change
app.post('/devices/:id/quarantine', (req, res) => {
  const device = updateDeviceState(req.params.id, 'quarantined');
  
  // Setting a new ETag invalidates cached versions
  res.set('ETag', generateETag(device));
  res.set('Cache-Control', 'no-cache');
  
  res.json({
    ...device,
    _links: {
      self: { href: `/devices/${device.id}` },
      'dt:clean': { href: `/devices/${device.id}/clean` },
    },
  });
});

// Different caching strategies for different resources
const cachePolicies = {
  // Device resources: short TTL, revalidate on state change
  device: {
    'Cache-Control': 'public, max-age=30, must-revalidate',
  },
  
  // Link-intensive collection: medium TTL
  collection: {
    'Cache-Control': 'public, max-age=60, stale-while-revalidate=30',
  },
  
  // Action endpoints: no caching (state-sensitive)
  action: {
    'Cache-Control': 'no-cache, no-store, must-revalidate',
  },
  
  // Static documentation links: long TTL
  documentation: {
    'Cache-Control': 'public, max-age=86400, immutable',
  },
  
  // User-specific resources: private cache
  userResource: {
    'Cache-Control': 'private, max-age=10',
  },
};

// Apply caching policy based on content type
function applyCachePolicy(req, res, next) {
  const originalJson = res.json.bind(res);
  
  res.json = function(body) {
    // Determine resource type from response
    const type = determineType(req, body);
    const policy = cachePolicies[type] || cachePolicies.collection;
    
    for (const [key, value] of Object.entries(policy)) {
      res.set(key, value);
    }
    
    // Add Vary header for content negotiation
    res.set('Vary', 'Accept, Authorization');
    
    return originalJson(body);
  };
  
  next();
}

// Link-specific caching
function withLinkCache(link, ttlSeconds) {
  return {
    href: link,
    cacheTTL: ttlSeconds,
    cachedAt: Date.now(),
    isExpired() {
      return Date.now() - this.cachedAt > this.ttlSeconds * 1000;
    },
  };
}

class HypermediaCache {
  constructor(defaultTTL = 30000) {
    this.cache = new Map();
    this.defaultTTL = defaultTTL;
    this.pendingRequests = new Map();
  }
  
  async get(url, options = {}) {
    const cacheKey = this.makeKey(url, options);
    const cached = this.cache.get(cacheKey);
    
    // Return cached response if fresh
    if (cached && !this.isExpired(cached, options)) {
      console.log(`Cache HIT: ${url}`);
      return cached.data;
    }
    
    // Deduplicate in-flight requests
    if (this.pendingRequests.has(cacheKey)) {
      return this.pendingRequests.get(cacheKey);
    }
    
    console.log(`Cache MISS: ${url}`);
    
    const fetchPromise = this.fetchAndCache(url, options, cacheKey);
    this.pendingRequests.set(cacheKey, fetchPromise);
    
    try {
      return await fetchPromise;
    } finally {
      this.pendingRequests.delete(cacheKey);
    }
  }
  
  async fetchAndCache(url, options, cacheKey) {
    const headers = { ...options.headers };
    const cached = this.cache.get(cacheKey);
    
    // Conditional request
    if (cached && cached.etag) {
      headers['If-None-Match'] = cached.etag;
    }
    
    const res = await fetch(url, { ...options, headers });
    
    if (res.status === 304) {
      // Cache is still valid
      cached.expiresAt = Date.now() + this.getTTL(res);
      return cached.data;
    }
    
    const data = await res.json();
    const etag = res.headers.get('ETag');
    const cacheControl = res.headers.get('Cache-Control');
    
    // Cache the response
    this.cache.set(cacheKey, {
      data,
      etag,
      expiresAt: Date.now() + this.getTTL(res),
      links: data._links || {},
    });
    
    // Also cache discovered links separately
    if (data._links) {
      for (const [rel, link] of Object.entries(data._links)) {
        this.linkCache.set(rel, { url: link.href, expiresAt: Date.now() + 60000 });
      }
    }
    
    return data;
  }
  
  // Invalidate specific links when state changes
  invalidateLinks(resourceId) {
    const patterns = [`/devices/${resourceId}`, `/devices/${resourceId}/`];
    for (const key of this.cache.keys()) {
      if (patterns.some(p => key.includes(p))) {
        this.cache.delete(key);
      }
    }
  }
}