Cache busting: perché l'aggiornamento non si vede e come si risolve davvero

1// La configurazione corretta è ASIMMETRICA: due politiche opposte per2// due tipi di file con proprietà opposte.3​4// L'HTML cambia contenuto allo stesso URL → non può essere in cache lunga.5// no-cache non significa "non memorizzare": significa "memorizza pure,6// ma chiedimi sempre se è ancora buono". Con ETag la risposta è un 3047// da poche decine di byte.8app.use(express.static(PUBLIC, { setHeaders: (res, p) => {9  if (p.endsWith('.html')) res.setHeader('Cache-Control', 'no-cache');10}}));11​12// Gli asset versionati NON cambiano mai contenuto allo stesso URL:13// se cambia il contenuto, cambia l'URL. Quindi cache lunga e immutable.14// "immutable" dice al browser di non rivalidare NEMMENO su ricaricamento.15app.use('/js-build', express.static(path.join(PUBLIC, 'js-build'), {16  maxAge: '365d', immutable: true17}));

1- Cache-Control: public, max-age=86400        # HTML in cache per un giorno2+ Cache-Control: no-cache                     # rivalida sempre (ETag)3​4# La prima riga è l'errore che rende invisibile ogni altra precauzione:5# il documento con i riferimenti versionati resta in cache 24 ore, quindi6# per 24 ore il browser continua a chiedere i vecchi URL — che, essendo7# immutabili, ha già in cache. L'aggiornamento non arriva mai.

1// Due modi di versionare, con una differenza pratica che conta.2​3// 1. Query string: l'URL del file resta lo stesso, cambia il parametro.4//    Semplice, e sufficiente per il browser. Il problema è che ALCUNI5//    proxy intermedi ignorano la query string nella chiave di cache:6//    per loro /app.js?v=1 e /app.js?v=2 sono lo stesso oggetto.7<script src="/js-build/app.js?v=1718031040"></script>8​9// 2. Hash nel nome: l'URL è diverso, quindi è un oggetto diverso per10//    chiunque, senza eccezioni. È l'approccio da preferire in produzione.11<script src="/js-build/app.9f3a2c1e.js"></script>

1// Versionare con il tempo di modifica: nessun passaggio di build, il2// numero si ricava dal file stesso a ogni avvio.3function versioneAsset() {4  const file = ['css-build/app.css', 'js-build/app.js'];5  let max = 0;6  for (const f of file) {7    const m = fs.statSync(path.join(ASSET_DIR, f)).mtimeMs;8    if (m > max) max = m;9  }10  return Math.floor(max);11}12​13// Funziona bene ed è quello che uso su questo sito. Due limiti da14// conoscere prima di adottarlo:15//16// - il tempo di modifica cambia anche quando il CONTENUTO non cambia17//   (un rsync senza -a, un ripristino da backup): si costringono tutti18//   i visitatori a riscaricare un file identico;19// - con più server, i tempi di modifica differiscono: due utenti20//   ricevono URL diversi per lo stesso file. Innocuo per la correttezza,21//   ma dimezza l'efficacia della cache condivisa.22//23// Con l'hash del contenuto nessuno dei due si presenta: stesso contenuto,24// stesso nome, su qualunque macchina.

1// L'hash del contenuto, in venti righe e senza aggiungere strumenti.2const crypto = require('crypto');3​4function scriviConHash(sorgente, cartellaUscita, nomeBase, estensione) {5  const contenuto = fs.readFileSync(sorgente);6  const hash = crypto.createHash('sha256')7    .update(contenuto)8    .digest('hex')9    .slice(0, 8);                      // 8 caratteri: 4 miliardi di valori,10                                       // più che sufficienti per un progetto11​12  const nome = `${nomeBase}.${hash}${estensione}`;13  fs.writeFileSync(path.join(cartellaUscita, nome), contenuto);14  return nome;15}16​17// Il build scrive anche un manifesto, che il server legge una volta18// all'avvio per sapere quale nome usare nei template.19const manifesto = {20  'app.js':  scriviConHash('build/app.js',  OUT, 'app',  '.js'),21  'app.css': scriviConHash('build/app.css', OUT, 'app', '.css')22};23fs.writeFileSync(path.join(OUT, 'manifesto.json'), JSON.stringify(manifesto, null, 2));

1// Il service worker è l'anello che rende inutile tutto il resto, perché2// intercetta le richieste PRIMA che escano dal browser.3//4// ✗ Il difetto classico: mettere in cache l'HTML con "cache first".5//   L'utente riceve per sempre la pagina della prima visita, con dentro6//   i vecchi URL versionati. Il cache busting non entra mai in gioco.7self.addEventListener('fetch', (e) => {8  e.respondWith(caches.match(e.request).then(r => r || fetch(e.request)));9});10​11// ✓ Politiche diverse per tipo di risorsa, come per gli header HTTP.12self.addEventListener('fetch', (e) => {13  const url = new URL(e.request.url);14​15  // Navigazioni: rete per prima, cache solo come rete di salvataggio16  // quando si è offline.17  if (e.request.mode === 'navigate') {18    e.respondWith(fetch(e.request).catch(() => caches.match('/offline.html')));19    return;20  }21​22  // Asset con hash nel nome: cache per sempre, senza pensarci.23  if (/\.[0-9a-f]{8}\.(js|css|woff2)$/.test(url.pathname)) {24    e.respondWith(caches.match(e.request).then(r => r || fetch(e.request)));25  }26});