improvement(files): answer a file revalidation with 304 instead of the whole body

A response the browser is told to revalidate carried no validator, so every check
re-sent the entire file. That is the cost a document compiled against other files
now pays on each window focus: it cannot be given a cache lifetime, because its
bytes really may have changed, so the only way to make the check cheap is to let
the client prove what it already holds.

Authorized serves now carry an ETag — the digest of the bytes about to be sent,
which is exact by construction however those bytes were produced — and answer 304
to a matching If-None-Match. Matching is weak, per RFC 9110, so a cache that
stored a weak validator still revalidates.

Kept out of createFileResponse deliberately: digesting costs a pass over the
buffer, up to the 100MB transfer ceiling, and a response served as immutable is
never revalidated, so it would pay that pass and never collect. Public assets and
the assistant-image path are unchanged.

Author: waleedlatif1

apps/sim/app/api/files/serve/[...path]/route.test.ts

@@ -36,6 +36,7 @@ const {
   mockFindLocalFile,
   mockReadLocalFileWithinLimit,
   mockCreateFileResponse,
+  mockCreateConditionalFileResponse,
   mockCreateErrorResponse,
   FileNotFoundError,
   serveLogger,
@@ -64,6 +65,7 @@ const {
     mockFindLocalFile: vi.fn(),
     mockReadLocalFileWithinLimit: vi.fn(),
     mockCreateFileResponse: vi.fn(),
+    mockCreateConditionalFileResponse: vi.fn(),
     mockCreateErrorResponse: vi.fn(),
     FileNotFoundError: FileNotFoundErrorClass,
   }
@@ -129,6 +131,7 @@ vi.mock('@/lib/copilot/tools/server/files/doc-compile', () => ({
 vi.mock('@/app/api/files/utils', () => ({
   FileNotFoundError,
   createFileResponse: mockCreateFileResponse,
+  createConditionalFileResponse: mockCreateConditionalFileResponse,
   createErrorResponse: mockCreateErrorResponse,
   getContentType: mockGetContentType,
   extractStorageKey: vi.fn().mockImplementation((path: string) => path.split('/').pop()),
@@ -192,6 +195,11 @@ describe('File Serve API Route', () => {
         })
       }
     )
+    // Delegates so the existing assertions on the response payload — including its
+    // Cache-Control — read the same call list whichever helper the route reached for.
+    mockCreateConditionalFileResponse.mockImplementation((file: unknown) =>
+      mockCreateFileResponse(file)
+    )
     mockCreateErrorResponse.mockImplementation((error: Error) => {
       return new Response(JSON.stringify({ error: error.name, message: error.message }), {
         status: error.name === 'FileNotFoundError' ? 404 : 500,

apps/sim/app/api/files/serve/[...path]/route.ts

@@ -30,6 +30,7 @@ import { isSimPageSource, SIM_PAGE_CONTENT_TYPE } from '@/lib/workspace-files/pa
 import { renderSimPageDocumentWithAssets } from '@/lib/workspace-files/page-document.server'
 import { type KnowledgeFileAccess, verifyFileAccess } from '@/app/api/files/authorization'
 import {
+  createConditionalFileResponse,
   createErrorResponse,
   createFileResponse,
   FileNotFoundError,
@@ -66,6 +67,8 @@ interface ServeOptions {
   preview: boolean
   /** `v=<updatedAt>` — the caller asserts the URL addresses one fixed content revision. */
   versioned: boolean
+  /** The request's `If-None-Match`, so a revalidation can be answered 304 instead of re-sending. */
+  ifNoneMatch: string | null
 }
 
 /**
@@ -327,6 +330,7 @@ export const GET = withRouteHandler(
         raw: query.raw === '1',
         preview: query.preview === '1',
         versioned: query.v != null,
+        ifNoneMatch: request.headers.get('if-none-match'),
       }
 
       if (workspacePrincipal) {
@@ -427,12 +431,15 @@ async function handleWorkspaceFile(
     workspaceId,
     size: resolved.buffer.length,
   })
-  return createFileResponse({
-    buffer: resolved.buffer,
-    contentType: resolved.contentType,
-    filename: file.name,
-    cacheControl: resolveServeCacheControl(options.versioned, 'workspace', resolved.cacheability),
-  })
+  return createConditionalFileResponse(
+    {
+      buffer: resolved.buffer,
+      contentType: resolved.contentType,
+      filename: file.name,
+      cacheControl: resolveServeCacheControl(options.versioned, 'workspace', resolved.cacheability),
+    },
+    options.ifNoneMatch
+  )
 }
 
 async function handleLocalFile(
@@ -489,12 +496,15 @@ async function handleLocalFile(
 
     logger.info('Local file served', { userId, filename, size: fileBuffer.length })
 
-    return createFileResponse({
-      buffer: fileBuffer,
-      contentType,
-      filename: displayName,
-      cacheControl: resolveServeCacheControl(options.versioned, context, cacheability),
-    })
+    return createConditionalFileResponse(
+      {
+        buffer: fileBuffer,
+        contentType,
+        filename: displayName,
+        cacheControl: resolveServeCacheControl(options.versioned, context, cacheability),
+      },
+      options.ifNoneMatch
+    )
   } catch (error) {
     logServeFailure('Error reading local file:', error)
     throw error
@@ -565,12 +575,15 @@ async function handleCloudProxy(
       context,
     })
 
-    return createFileResponse({
-      buffer: fileBuffer,
-      contentType,
-      filename: displayName,
-      cacheControl: resolveServeCacheControl(options.versioned, context, cacheability),
-    })
+    return createConditionalFileResponse(
+      {
+        buffer: fileBuffer,
+        contentType,
+        filename: displayName,
+        cacheControl: resolveServeCacheControl(options.versioned, context, cacheability),
+      },
+      options.ifNoneMatch
+    )
   } catch (error) {
     logServeFailure('Error downloading from cloud storage:', error)
     throw error

apps/sim/app/api/files/utils.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import {
+  createConditionalFileResponse,
   createFileResponse,
   encodeFilenameForHeader,
   extractFilename,
@@ -508,3 +509,61 @@ describe('findLocalFile - Path Traversal Security Tests', () => {
     )
   })
 })
+
+describe('createConditionalFileResponse', () => {
+  const file = {
+    buffer: Buffer.from('compiled-document-bytes'),
+    contentType: 'application/pdf',
+    filename: 'report.pdf',
+    cacheControl: 'private, no-cache, must-revalidate',
+  }
+
+  function etagOf(ifNoneMatch: string | null = null): string {
+    return createConditionalFileResponse(file, ifNoneMatch).headers.get('ETag') as string
+  }
+
+  it('sends the body with a strong validator when the client holds nothing', () => {
+    const response = createConditionalFileResponse(file, null)
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('ETag')).toMatch(/^"[A-Za-z0-9_-]+"$/)
+    expect(response.headers.get('Cache-Control')).toBe('private, no-cache, must-revalidate')
+  })
+
+  it('answers 304 without a body when the client already holds these bytes', async () => {
+    const response = createConditionalFileResponse(file, etagOf())
+
+    expect(response.status).toBe(304)
+    expect(await response.text()).toBe('')
+    // Repeated so the stored response is refreshed with this request's lifetime.
+    expect(response.headers.get('Cache-Control')).toBe('private, no-cache, must-revalidate')
+  })
+
+  it('sends the body when the client holds a validator for different bytes', () => {
+    const stale = createConditionalFileResponse(
+      { ...file, buffer: Buffer.from('an-earlier-render') },
+      null
+    ).headers.get('ETag') as string
+
+    expect(createConditionalFileResponse(file, stale).status).toBe(200)
+  })
+
+  it('matches weakly, so a cache that stored a weak validator still revalidates', () => {
+    expect(createConditionalFileResponse(file, `W/${etagOf()}`).status).toBe(304)
+  })
+
+  it('matches one entry out of a list, and the wildcard', () => {
+    expect(createConditionalFileResponse(file, `"other", ${etagOf()}`).status).toBe(304)
+    expect(createConditionalFileResponse(file, '*').status).toBe(304)
+  })
+
+  it('gives bytes that differ only in one byte different validators', () => {
+    const a = etagOf()
+    const b = createConditionalFileResponse(
+      { ...file, buffer: Buffer.from('compiled-document-byteS') },
+      null
+    ).headers.get('ETag')
+
+    expect(a).not.toBe(b)
+  })
+})

apps/sim/app/api/files/utils.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import { createLogger } from '@sim/logger'
 import { NextResponse } from 'next/server'
 import {
@@ -267,6 +268,56 @@ export function createFileResponse(file: FileResponse): NextResponse {
   return new NextResponse(file.buffer as BodyInit, { status: 200, headers })
 }
 
+/**
+ * Whether an `If-None-Match` header claims the client already holds `etag`.
+ *
+ * Compared weakly, per RFC 9110: a cache that stored the response under a weak validator sends
+ * `W/"…"` back, and that still identifies the same bytes for a GET.
+ */
+function ifNoneMatchHolds(header: string | null, etag: string): boolean {
+  if (!header) return false
+  if (header.trim() === '*') return true
+  return header.split(',').some((candidate) => candidate.trim().replace(/^W\//, '').trim() === etag)
+}
+
+/**
+ * A file response carrying a strong validator, answering 304 when the client already holds
+ * exactly these bytes.
+ *
+ * For responses the browser is told to revalidate, the alternative is re-sending the whole body on
+ * every check — and a document resolved against other files is re-resolved per request precisely
+ * BECAUSE its bytes may have changed, so it cannot be given a cache lifetime instead. The
+ * validator is the digest of the bytes about to be sent, which makes it exact by construction: it
+ * cannot claim freshness for a body that differs, however the body was produced.
+ *
+ * This is deliberately NOT folded into {@link createFileResponse}. Digesting costs a pass over the
+ * buffer — up to the full transfer ceiling — which is worth it only where a 304 can actually be
+ * returned. A response already served as immutable is never revalidated, so it would pay the pass
+ * and never collect.
+ */
+export function createConditionalFileResponse(
+  file: FileResponse,
+  ifNoneMatch: string | null
+): NextResponse {
+  const etag = `"${createHash('sha256').update(file.buffer).digest('base64url')}"`
+
+  if (ifNoneMatchHolds(ifNoneMatch, etag)) {
+    // A 304 repeats the headers that govern caching, so the stored response is refreshed with the
+    // lifetime this request would have granted it rather than keeping the one it was stored with.
+    return new NextResponse(null, {
+      status: 304,
+      headers: {
+        ETag: etag,
+        'Cache-Control': file.cacheControl || 'private, no-cache',
+      },
+    })
+  }
+
+  const response = createFileResponse(file)
+  response.headers.set('ETag', etag)
+  return response
+}
+
 export function createErrorResponse(error: Error, status = 500): NextResponse {
   const statusCode =
     error instanceof FileNotFoundError