fix(api): never cache the SPA entry HTML

@fastify/static served `/` as index.html with the asset policy —
`public, max-age=31536000, immutable` — so a browser that had visited
before a release kept the old SPA on every plain navigation for up to a
year, and only a reload revalidated. That is how the events release
looked invisible from a browser that already had the home page cached.
The SPA fallthrough handler already sent no-cache for every other path.

`/` now falls through to that handler (`index: false`), and a direct
/index.html gets no-cache through an onSend override, since the static
plugin's setHeaders runs before send writes Cache-Control. Hashed
/assets/ stay immutable. Spec: architecture.md → Deployment.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TGqwPjt3v4eMfiHpPmCKnR

Author: themightychris

apps/api/src/plugins/static-web.ts

@@ -54,6 +54,19 @@ async function staticWebPlugin(fastify: FastifyInstance): Promise<void> {
     cacheControl: true,
     maxAge: '1y',
     immutable: true,
+    // Never let the entry HTML carry those headers: with the default index
+    // option `/` was served as index.html marked immutable for a year, so a
+    // browser that had visited before a release kept the old SPA on every
+    // plain navigation (specs/architecture.md → "Deployment"). `/` now falls
+    // through to the handler below; a direct /index.html gets no-cache too.
+    index: false,
+  });
+
+  // A direct /index.html is served by the static plugin above; override the
+  // immutable header it would stamp on it (the plugin's own setHeaders runs
+  // before send writes Cache-Control, so a hook after the handler is needed).
+  fastify.addHook('onSend', async (request, reply) => {
+    if (request.url.split('?')[0] === '/index.html') reply.header('cache-control', 'no-cache');
   });
 
   // Read index.html once at boot — it's small and avoids per-request disk IO.

apps/api/tests/deploy.test.ts

@@ -101,10 +101,21 @@ describe('static-web plugin', () => {
     expect(spaRes.body).toContain('<title>cfp</title>');
     expect(spaRes.headers['cache-control']).toContain('no-cache');
 
+    // The entry HTML is never cached — `/` and /index.html included. A
+    // year-long immutable `/` kept old visitors on the pre-release SPA.
+    for (const url of ['/', '/index.html']) {
+      const res = await app.inject({ method: 'GET', url });
+      expect(res.statusCode, url).toBe(200);
+      expect(res.headers['content-type'], url).toMatch(/text\/html/);
+      expect(res.body, url).toContain('<title>cfp</title>');
+      expect(res.headers['cache-control'], url).toBe('no-cache');
+    }
+
     // Hashed asset served directly with long cache
     const assetRes = await app.inject({ method: 'GET', url: '/assets/app-deadbeef.js' });
     expect(assetRes.statusCode).toBe(200);
     expect(assetRes.body).toContain('console.log');
+    expect(assetRes.headers['cache-control']).toContain('immutable');
 
     // /api/* unknown route still returns JSON 404, not HTML
     const apiRes = await app.inject({ method: 'GET', url: '/api/does-not-exist' });

specs/architecture.md

@@ -166,6 +166,8 @@ npm run type-check       # tsc --noEmit across workspaces
 
 A single Docker image bundles the built API and serves the static `apps/web/dist` from the same Fastify instance via `@fastify/static`. One container, one ingress.
 
+Caching: the hashed files under `/assets/` are immutable for a year; the entry HTML (`/`, `/index.html`, and every SPA fallthrough path) is `no-cache`, so a browser revalidates it on every navigation and picks up a release as soon as it lands. The HTML is the only file that decides which assets load next; caching it caches the old site.
+
 Runtime configuration (sealed-secrets in our cluster):
 
 | Env var | Purpose |