Add cache headers to applet bundles and workspace file streams

Both the applet-bundle route and the workspace media-file (`fileUrl`)
route sent NO cache headers, so a TLS-terminating reverse proxy
(Cloudflare) applied its default extension-based edge caching. The stable
`index.js` entry url then served a stale bundle after every `moi bundle`,
and private workspace media could be stored on a shared edge.

Split caching by whether the url is stable or content-hashed:

- Applet entry `index.js` (stable url across rebuilds): ETag from
  (size, mtime) + `no-cache`, with 304 on `If-None-Match`. The edge must
  revalidate, so an unchanged bundle costs a 304 and a rebuilt one busts —
  no more stale bundles behind a proxy.
- Applet chunks/assets (`chunk-<hash>.js`, `<stem>-<hash>.<ext>`): the url
  is a fingerprint of the bytes, so `public, max-age=31536000, immutable`.
  Cached forever at edge and browser (mirrors the SPA chunks).
- Workspace media (`/fs/*`): the user's own, mutable files — `private,
  no-cache` + ETag (304 on match) so they are NEVER stored by a shared
  edge and the browser revalidates cheaply. Headers ride the 200, 206 and
  304 paths. Mirrors the existing `/preview/*` route.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FpGBXW5iHAsc8K2543Z7BU

Author: claude

server/api.ts

@@ -104,7 +104,7 @@ one.get('/widgets/*', c => {
   const id = c.req.param('id')
   const { name, file } = parseAppletTail(c.req.url, id, 'widgets')
   if (!name) return c.text('Not found', 404)
-  return serveWidget(name, file, c.get('ws').path, apiBaseFor(id))
+  return serveWidget(name, file, c.get('ws').path, apiBaseFor(id), c.req.header('if-none-match'))
 })
 
 // Views — full-screen agent apps. Mirrors the widget pair above: the exact path
@@ -115,7 +115,7 @@ one.get('/views/*', c => {
   const id = c.req.param('id')
   const { name, file } = parseAppletTail(c.req.url, id, 'views')
   if (!name) return c.text('Not found', 404)
-  return serveView(name, file, c.get('ws').path, apiBaseFor(id))
+  return serveView(name, file, c.get('ws').path, apiBaseFor(id), c.req.header('if-none-match'))
 })
 
 // Workspace file stream — an applet's `fileUrl(path)` resolves here. Streams a
@@ -126,7 +126,12 @@ one.get('/views/*', c => {
 one.get('/fs/*', c => {
   const id = c.req.param('id')
   const tail = new URL(c.req.url).pathname.split(`/api/workspaces/${id}/fs/`)[1] ?? ''
-  return serveWorkspaceFile(c.get('ws').path, tail, c.req.header('range'))
+  return serveWorkspaceFile(
+    c.get('ws').path,
+    tail,
+    c.req.header('range'),
+    c.req.header('if-none-match')
+  )
 })
 
 // Applet RPC — the home for server-function calls from a bundle. The bundle's

server/applets.ts

@@ -136,16 +136,33 @@ const CODE_FILE_RE = /\.js$/
 // can be requested; `..` is rejected separately.
 const ALLOWED_FILE_RE = /^[a-zA-Z0-9_-][a-zA-Z0-9._-]*$/
 
+// The `index.js` entry keeps a STABLE url across rebuilds; every other file in
+// the bundle dir (`chunk-<hash>.js`, `<stem>-<hash>.<ext>`) is content-hashed,
+// so its url changes whenever its bytes do.
+const APPLET_ENTRY = 'index.js'
+const JS_CONTENT_TYPE = 'text/javascript; charset=utf-8'
+// A hashed file's url is a fingerprint of its bytes, so it can never go stale —
+// cache it forever, at the edge and in the browser (mirrors the SPA chunks).
+const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable'
+
 // Serve one file from a compiled applet directory: the `index.js` entry, a code
 // chunk, or a bundled asset. `apiBase` is the workspace's `/api/workspaces/<id>`
 // prefix — substituted for the build-time sentinel in every `.js` so RPC and
 // `fileUrl` calls hit the right workspace. Assets stream untouched.
+//
+// Caching turns on the entry-vs-hashed split. The entry lives at one url across
+// rebuilds, so a shared cache (e.g. Cloudflare) that stored it once will hand
+// back a STALE bundle after the next `moi bundle` unless we force revalidation:
+// it gets an ETag (from size+mtime) + `no-cache`, so an unchanged bundle costs a
+// 304 and a rebuilt one busts. Hashed chunks/assets are immutable — their url
+// already changes with their bytes — so they cache forever.
 export async function serveApplet(
   kind: AppletKind,
   name: string,
   file: string,
   workspacePath: string,
-  apiBase: string
+  apiBase: string,
+  ifNoneMatch?: string | null
 ): Promise<Response> {
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
     return new Response('Invalid name', { status: 400 })
@@ -160,11 +177,26 @@ export async function serveApplet(
   if (!(await bunFile.exists())) {
     return new Response(`"${name}" not built. Run: moi bundle`, { status: 404 })
   }
+
+  if (file === APPLET_ENTRY) {
+    const etag = `"${bunFile.size}-${Math.trunc(bunFile.lastModified)}"`
+    const headers = { 'Content-Type': JS_CONTENT_TYPE, ETag: etag, 'Cache-Control': 'no-cache' }
+    if (ifNoneMatch === etag) return new Response(null, { status: 304, headers })
+    const swapped = (await bunFile.text()).replaceAll(APPLET_API_BASE_SENTINEL, apiBase)
+    return new Response(swapped, { headers })
+  }
   if (CODE_FILE_RE.test(file)) {
     const swapped = (await bunFile.text()).replaceAll(APPLET_API_BASE_SENTINEL, apiBase)
-    return new Response(swapped, { headers: { 'Content-Type': 'text/javascript; charset=utf-8' } })
+    return new Response(swapped, {
+      headers: { 'Content-Type': JS_CONTENT_TYPE, 'Cache-Control': IMMUTABLE_CACHE }
+    })
   }
-  return new Response(bunFile)
+  return new Response(bunFile, {
+    headers: {
+      'Content-Type': bunFile.type || 'application/octet-stream',
+      'Cache-Control': IMMUTABLE_CACHE
+    }
+  })
 }
 
 // ---- route helpers ----------------------------------------------------------
@@ -255,30 +287,45 @@ export function resolveWorkspaceMediaFile(workspaceRoot: string, tail: string):
 // Range is handled explicitly (slice the BunFile, 206 + Content-Range): Bun's
 // implicit range handling for `new Response(Bun.file())` doesn't fire once any
 // headers object is attached, and <video>/<audio> seeking needs byte ranges.
+//
+// Caching: these are the user's own workspace files — private, and rewritten in
+// place by the agent (a regenerated clip keeps its path). So they must NEVER be
+// stored by a shared/edge cache sitting in front of moi, or one user's video
+// could be served to the next, and an edited file could be served stale from a
+// stable url (the applet-bundle incident, but with private bytes). `private`
+// keeps them off the edge; an ETag (size+mtime) + `no-cache` lets the browser
+// revalidate cheaply (304) while guaranteeing a re-fetch when the file changes.
 export async function serveWorkspaceFile(
   workspaceRoot: string,
   tail: string,
-  range?: string | null
+  range?: string | null,
+  ifNoneMatch?: string | null
 ): Promise<Response> {
   const realTarget = resolveWorkspaceMediaFile(workspaceRoot, tail)
   if (realTarget instanceof Response) return realTarget
   const file = Bun.file(realTarget)
 
   const size = file.size
   const type = file.type || 'application/octet-stream'
+
+  const etag = `"${size}-${Math.trunc(file.lastModified)}"`
+  const cache = { ETag: etag, 'Cache-Control': 'private, no-cache' }
+  if (ifNoneMatch === etag) return new Response(null, { status: 304, headers: cache })
+
   const parsed = range ? parseByteRange(range, size) : null
 
   if (parsed === 'invalid') {
     return new Response('Range Not Satisfiable', {
       status: 416,
-      headers: { 'Content-Range': `bytes */${size}`, 'Accept-Ranges': 'bytes' }
+      headers: { ...cache, 'Content-Range': `bytes */${size}`, 'Accept-Ranges': 'bytes' }
     })
   }
   if (parsed) {
     const { start, end } = parsed
     return new Response(file.slice(start, end + 1), {
       status: 206,
       headers: {
+        ...cache,
         'Content-Type': type,
         'Content-Length': String(end - start + 1),
         'Content-Range': `bytes ${start}-${end}/${size}`,
@@ -287,7 +334,12 @@ export async function serveWorkspaceFile(
     })
   }
   return new Response(file, {
-    headers: { 'Content-Type': type, 'Content-Length': String(size), 'Accept-Ranges': 'bytes' }
+    headers: {
+      ...cache,
+      'Content-Type': type,
+      'Content-Length': String(size),
+      'Accept-Ranges': 'bytes'
+    }
   })
 }
 

server/test/applets.test.ts

@@ -75,6 +75,45 @@ describe('serveApplet', () => {
     expect(res.status).toBe(200)
   })
 
+  test('entry index.js revalidates: ETag + no-cache, 304 on match', async () => {
+    // The entry's url is stable across rebuilds, so an edge cache must revalidate
+    // it or it serves a stale bundle. It carries an ETag + `no-cache`; a request
+    // echoing that ETag gets a bodyless 304.
+    seedApplet('views', 'editor', { 'index.js': 'export default 1' })
+    const res = await serveApplet('view', 'editor', 'index.js', WS, BASE)
+    expect(res.status).toBe(200)
+    expect(res.headers.get('cache-control')).toBe('no-cache')
+    const etag = res.headers.get('etag')
+    expect(etag).toBeTruthy()
+
+    const revalidated = await serveApplet('view', 'editor', 'index.js', WS, BASE, etag)
+    expect(revalidated.status).toBe(304)
+    expect(revalidated.headers.get('etag')).toBe(etag)
+    expect(await revalidated.text()).toBe('')
+  })
+
+  test('a stale ETag on the entry still serves fresh bytes (200)', async () => {
+    seedApplet('views', 'editor', { 'index.js': 'export default 1' })
+    const res = await serveApplet('view', 'editor', 'index.js', WS, BASE, '"stale"')
+    expect(res.status).toBe(200)
+    expect(await res.text()).toContain('export default 1')
+  })
+
+  test('hashed chunks and assets are immutable — never revalidated', async () => {
+    // A content-hashed url is a fingerprint of its bytes, so it can be cached
+    // forever at the edge and in the browser.
+    seedApplet('widgets', 'clock', {
+      'index.js': '//',
+      'chunk-9f.js': 'export const x=1',
+      'logo-abc123.png': new Uint8Array([0x89, 0x50, 0x4e, 0x47])
+    })
+    const chunk = await serveApplet('widget', 'clock', 'chunk-9f.js', WS, BASE)
+    expect(chunk.headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
+    expect(chunk.headers.get('etag')).toBeNull()
+    const asset = await serveApplet('widget', 'clock', 'logo-abc123.png', WS, BASE)
+    expect(asset.headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
+  })
+
   test('400 for a dotfile request', async () => {
     seedApplet('views', 'editor', { 'index.js': '//' })
     expect((await serveApplet('view', 'editor', '.env', WS, BASE)).status).toBe(400)
@@ -164,6 +203,31 @@ describe('serveWorkspaceFile (fileUrl streaming)', () => {
     expect(res.headers.get('content-length')).toBe('4')
   })
 
+  test('is private + revalidated, never edge-cached (ETag + private, no-cache)', async () => {
+    seedFile('clips/a.mp4', new Uint8Array([1, 2, 3, 4]))
+    const res = await serveWorkspaceFile(WS, 'clips/a.mp4')
+    expect(res.status).toBe(200)
+    // `private` keeps the user's file off any shared/edge cache; `no-cache`
+    // forces the browser to revalidate so an agent-rewritten file isn't stale.
+    expect(res.headers.get('cache-control')).toBe('private, no-cache')
+    const etag = res.headers.get('etag')
+    expect(etag).toBeTruthy()
+
+    const revalidated = await serveWorkspaceFile(WS, 'clips/a.mp4', undefined, etag)
+    expect(revalidated.status).toBe(304)
+    expect(revalidated.headers.get('etag')).toBe(etag)
+    expect(revalidated.headers.get('cache-control')).toBe('private, no-cache')
+    expect(await revalidated.text()).toBe('')
+  })
+
+  test('a range request still carries the private cache headers', async () => {
+    seedFile('clips/a.mp4', new Uint8Array([10, 11, 12, 13, 14, 15]))
+    const res = await serveWorkspaceFile(WS, 'clips/a.mp4', 'bytes=1-3')
+    expect(res.status).toBe(206)
+    expect(res.headers.get('cache-control')).toBe('private, no-cache')
+    expect(res.headers.get('etag')).toBeTruthy()
+  })
+
   test('honors a byte range (206 + Content-Range)', async () => {
     seedFile('clips/a.mp4', new Uint8Array([10, 11, 12, 13, 14, 15, 16, 17, 18, 19]))
     const res = await serveWorkspaceFile(WS, 'clips/a.mp4', 'bytes=2-5')

server/views.ts

@@ -158,7 +158,8 @@ export function serveWidget(
   name: string,
   file: string,
   workspacePath: string,
-  apiBase: string
+  apiBase: string,
+  ifNoneMatch?: string | null
 ): Promise<Response> {
-  return serveApplet('widget', name, file, workspacePath, apiBase)
+  return serveApplet('widget', name, file, workspacePath, apiBase, ifNoneMatch)
 }