fix: improve static file handler (#248)

eduardoboucas · mrstork · web-flow · commit eb6c134965a1 · 2025-06-02T16:29:22.000+01:00
* fix: improve static file handler

* refactor: only apply headers to static files

* refactor: simplify

* chore: add comment

* chore: add test

* chore: fix eslint errors

* refactor: append headers in pre middleware

---------

Co-authored-by: Mateusz Bocian &lt;mrstork@users.noreply.github.com&gt;
diff --git a/packages/dev/src/main.test.ts b/packages/dev/src/main.test.ts
@@ -671,5 +671,50 @@ describe('Handling requests', () => {
 
       await fixture.destroy()
     })
+
+    test('Invoking a function that shadows a static file and introspecting the result', async () => {
+      const fixture = new Fixture()
+        .withFile(
+          'netlify.toml',
+          `[build]
+        publish = "public"
+        `,
+        )
+        .withFile(
+          'netlify/functions/greeting.mjs',
+          `export default async (req, context) => new Response(context.params.greeting + ", friend!");
+           
+           export const config = { path: "/:greeting", preferStatic: true };`,
+        )
+        .withFile('public/hello.html', '<html>Hello</html>')
+        .withStateFile({ siteId: 'site_id' })
+      const directory = await fixture.create()
+
+      await withMockApi(routes, async (context) => {
+        const dev = new NetlifyDev({
+          apiURL: context.apiUrl,
+          apiToken: 'token',
+          projectRoot: directory,
+        })
+
+        await dev.start()
+
+        const req1 = new Request('https://site.netlify/hi')
+        const res1 = await dev.handleAndIntrospect(req1)
+
+        expect(await res1?.response.text()).toBe('hi, friend!')
+        expect(res1?.type).toBe('function')
+
+        const req2 = new Request('https://site.netlify/hello')
+        const res2 = await dev.handleAndIntrospect(req2)
+
+        expect(await res2?.response.text()).toBe('<html>Hello</html>')
+        expect(res2?.type).toBe('static')
+
+        await dev.stop()
+      })
+
+      await fixture.destroy()
+    })
   })
 })
diff --git a/packages/dev/src/main.ts b/packages/dev/src/main.ts
@@ -6,7 +6,7 @@ import { resolveConfig } from '@netlify/config'
 import { ensureNetlifyIgnore, getAPIToken, mockLocation, LocalState, type Logger, HTTPServer } from '@netlify/dev-utils'
 import { EdgeFunctionsHandler } from '@netlify/edge-functions/dev'
 import { FunctionsHandler } from '@netlify/functions/dev'
-import { HeadersHandler } from '@netlify/headers'
+import { HeadersHandler, type HeadersCollector } from '@netlify/headers'
 import { RedirectsHandler } from '@netlify/redirects'
 import { StaticHandler } from '@netlify/static'
 
@@ -95,6 +95,18 @@ const notFoundHandler = async () => new Response('Not found', { status: 404 })
 
 type Config = Awaited<ReturnType<typeof resolveConfig>>
 
+interface HandleOptions {
+  /**
+   * An optional callback that will be called with every header (key and value)
+   * coming from header rules.
+   *
+   * {@link} https://docs.netlify.com/routing/headers/
+   */
+  headersCollector?: HeadersCollector
+}
+
+export type ResponseType = 'edge-function' | 'function' | 'redirect' | 'static'
+
 export class NetlifyDev {
   #apiHost?: string
   #apiScheme?: string
@@ -113,7 +125,7 @@ export class NetlifyDev {
     redirects: boolean
     static: boolean
   }
-  #headersHandler: { handle: HeadersHandler['handle'] }
+  #headersHandler?: HeadersHandler
   #logger: Logger
   #projectRoot: string
   #redirectsHandler?: RedirectsHandler
@@ -143,13 +155,16 @@ export class NetlifyDev {
       static: options.staticFiles?.enabled !== false,
     }
     this.#functionsServePath = path.join(projectRoot, '.netlify', 'functions-serve')
-    this.#headersHandler = { handle: async (_request: Request, response: Response) => response }
     this.#logger = options.logger ?? globalThis.console
     this.#server = options.serverAddress
     this.#projectRoot = projectRoot
   }
 
-  private async handleInEphemeralDirectory(request: Request, destPath: string) {
+  private async handleInEphemeralDirectory(
+    request: Request,
+    destPath: string,
+    options: HandleOptions = {},
+  ): Promise<{ response: Response; type: ResponseType } | undefined> {
     // Try to match the request against the different steps in our request chain.
     //
     // https://docs.netlify.com/platform/request-chain/
@@ -158,7 +173,7 @@ export class NetlifyDev {
     //    with both modes of cache (manual and off) by running them serially.
     const edgeFunctionResponse = await this.#edgeFunctionsHandler?.handle(request.clone())
     if (edgeFunctionResponse) {
-      return edgeFunctionResponse
+      return { response: edgeFunctionResponse, type: 'edge-function' }
     }
 
     // 2. Check if the request matches a function.
@@ -171,12 +186,15 @@ export class NetlifyDev {
 
         if (staticMatch) {
           const response = await staticMatch.handle()
-          return this.#headersHandler.handle(request, response)
+
+          await this.#headersHandler?.apply(request, response, options.headersCollector)
+
+          return { response, type: 'static' }
         }
       }
 
       // Let the function handle the request.
-      return functionMatch.handle(request)
+      return { response: await functionMatch.handle(request), type: 'function' }
     }
 
     // 3. Check if the request matches a redirect rule.
@@ -187,33 +205,40 @@ export class NetlifyDev {
       // we'll follow the redirect rule.
       const functionMatch = await this.#functionsHandler?.match(new Request(redirectMatch.target), destPath)
       if (functionMatch && !functionMatch.preferStatic) {
-        return functionMatch.handle(request)
+        return { response: await functionMatch.handle(request), type: 'function' }
       }
 
       const response = await this.#redirectsHandler?.handle(
         request,
         redirectMatch,
         async (maybeStaticFile: Request) => {
           const staticMatch = await this.#staticHandler?.match(maybeStaticFile)
-
-          if (!staticMatch) return
+          if (!staticMatch) {
+            return
+          }
 
           return async () => {
             const response = await staticMatch.handle()
-            return this.#headersHandler.handle(new Request(redirectMatch.target), response)
+
+            await this.#headersHandler?.apply(new Request(redirectMatch.target), response, options.headersCollector)
+
+            return response
           }
         },
       )
       if (response) {
-        return response
+        return { response, type: 'redirect' }
       }
     }
 
     // 4. Check if the request matches a static file.
     const staticMatch = await this.#staticHandler?.match(request)
     if (staticMatch) {
       const response = await staticMatch.handle()
-      return this.#headersHandler.handle(request, response)
+
+      await this.#headersHandler?.apply(request, response, options.headersCollector)
+
+      return { response, type: 'static' }
     }
   }
 
@@ -236,7 +261,13 @@ export class NetlifyDev {
     return config
   }
 
-  async handle(request: Request) {
+  async handle(request: Request, options: HandleOptions = {}) {
+    const result = await this.handleAndIntrospect(request, options)
+
+    return result?.response
+  }
+
+  async handleAndIntrospect(request: Request, options: HandleOptions = {}) {
     const requestID = generateRequestID()
 
     request.headers.set('x-nf-request-id', requestID)
@@ -246,7 +277,7 @@ export class NetlifyDev {
     const destPath = await fs.mkdtemp(path.join(this.#functionsServePath, `${requestID}_`))
 
     try {
-      return await this.handleInEphemeralDirectory(request, destPath)
+      return await this.handleInEphemeralDirectory(request, destPath, options)
     } finally {
       try {
         await fs.rm(destPath, { force: true, recursive: true })
diff --git a/packages/headers/src/main.test.ts b/packages/headers/src/main.test.ts
@@ -13,6 +13,7 @@ describe('constructor', () => {
     const projectDir = await fixture.create()
 
     const handler = new HeadersHandler({
+      logger: console,
       projectDir,
       publishDir: '.', // resolves to the same path as `projectDir`
       configHeaders: [{ for: '/test-*', values: { 'X-Config-Header': 'config-value' } }],
@@ -24,12 +25,13 @@ describe('constructor', () => {
   })
 })
 
-describe('handle', () => {
+describe('apply', () => {
   test('sets response headers matching rules in provided `configHeaders`', async () => {
     const fixture = new Fixture()
     const projectDir = await fixture.create()
 
     const handler = new HeadersHandler({
+      logger: console,
       projectDir,
       configHeaders: [{ for: '/test-*', values: { 'X-Config-Header': 'config-value' } }],
     })
@@ -39,10 +41,11 @@ describe('handle', () => {
         'Existing-Header': 'existing-value',
       },
     })
-    const result = await handler.handle(request, response)
+    const result = await handler.apply(request, response)
 
-    expect(result.headers.get('X-Config-Header')).toBe('config-value')
-    expect(result.headers.get('Existing-Header')).toBe('existing-value')
+    expect(result).toStrictEqual({ 'X-Config-Header': 'config-value' })
+    expect(response.headers.get('X-Config-Header')).toBe('config-value')
+    expect(response.headers.get('Existing-Header')).toBe('existing-value')
 
     await fixture.destroy()
   })
@@ -53,6 +56,7 @@ describe('handle', () => {
     })
     const projectDir = await fixture.create()
     const handler = new HeadersHandler({
+      logger: console,
       projectDir,
       configHeaders: undefined,
     })
@@ -63,10 +67,11 @@ describe('handle', () => {
         'Existing-Header': 'existing-value',
       },
     })
-    const result = await handler.handle(request, response)
+    const result = await handler.apply(request, response)
 
-    expect(result.headers.get('X-Project-Dir-Header')).toBe('project-dir-value')
-    expect(result.headers.get('Existing-Header')).toBe('existing-value')
+    expect(result).toStrictEqual({ 'X-Project-Dir-Header': 'project-dir-value' })
+    expect(response.headers.get('X-Project-Dir-Header')).toBe('project-dir-value')
+    expect(response.headers.get('Existing-Header')).toBe('existing-value')
 
     await fixture.destroy()
   })
@@ -79,6 +84,7 @@ describe('handle', () => {
     const projectDir = await fixture.create()
 
     const handler = new HeadersHandler({
+      logger: console,
       projectDir,
       publishDir: 'my-dist',
       configHeaders: undefined,
@@ -89,10 +95,11 @@ describe('handle', () => {
         'Existing-Header': 'existing-value',
       },
     })
-    const result = await handler.handle(request, response)
+    const result = await handler.apply(request, response)
 
-    expect(result.headers.get('X-Publish-Dir-Header')).toBe('publish-dir-value')
-    expect(result.headers.get('Existing-Header')).toBe('existing-value')
+    expect(result).toStrictEqual({ 'X-Publish-Dir-Header': 'publish-dir-value' })
+    expect(response.headers.get('X-Publish-Dir-Header')).toBe('publish-dir-value')
+    expect(response.headers.get('Existing-Header')).toBe('existing-value')
 
     await fixture.destroy()
   })
@@ -108,6 +115,7 @@ describe('handle', () => {
       })
     const projectDir = await fixture.create()
     const handler = new HeadersHandler({
+      logger: console,
       projectDir,
       publishDir: 'my-dist',
       configHeaders: [{ for: '/test-pa*', values: { 'X-Config-Header': 'config-value' } }],
@@ -119,12 +127,22 @@ describe('handle', () => {
         'Existing-Header': 'existing-value',
       },
     })
-    const result = await handler.handle(request, response)
+    const expected = {
+      'X-Project-Dir-Header': 'project-dir-value',
+      'X-Publish-Dir-Header': 'publish-dir-value',
+      'X-Config-Header': 'config-value',
+    }
+    const collected: Record<string, string> = {}
+    const result = await handler.apply(request, response, (key, value) => {
+      collected[key] = value
+    })
 
-    expect(result.headers.get('X-Project-Dir-Header')).toBe('project-dir-value')
-    expect(result.headers.get('X-Publish-Dir-Header')).toBe('publish-dir-value')
-    expect(result.headers.get('X-Config-Header')).toBe('config-value')
-    expect(result.headers.get('Existing-Header')).toBe('existing-value')
+    expect(result).toStrictEqual(expected)
+    expect(collected).toStrictEqual(expected)
+    expect(response.headers.get('X-Project-Dir-Header')).toBe('project-dir-value')
+    expect(response.headers.get('X-Publish-Dir-Header')).toBe('publish-dir-value')
+    expect(response.headers.get('X-Config-Header')).toBe('config-value')
+    expect(response.headers.get('Existing-Header')).toBe('existing-value')
 
     await fixture.destroy()
   })
@@ -135,6 +153,7 @@ describe('handle', () => {
     })
     const projectDir = await fixture.create()
     const handler = new HeadersHandler({
+      logger: console,
       projectDir,
       configHeaders: [{ for: '/no-match', values: { 'X-Config-Header': 'no-match-value' } }],
     })
@@ -146,9 +165,10 @@ describe('handle', () => {
       },
     })
     const originalHeaders = new Headers(response.headers)
-    const result = await handler.handle(request, response)
+    const result = await handler.apply(request, response)
 
-    expect(result.headers).toEqual(originalHeaders)
+    expect(result).toStrictEqual({})
+    expect(response.headers).toEqual(originalHeaders)
 
     await fixture.destroy()
   })
diff --git a/packages/headers/src/main.ts b/packages/headers/src/main.ts
@@ -7,6 +7,8 @@ import { headersForPath } from './lib/headersForPath.js'
 
 const HEADERS_FILE_NAME = '_headers'
 
+export type HeadersCollector = (key: string, value: string) => void
+
 interface HeadersHandlerOptions {
   configPath?: string | undefined
   configHeaders?: ConfigHeader[] | undefined
@@ -45,7 +47,7 @@ export class HeadersHandler {
     return this.#headersFiles
   }
 
-  async handle(request: Request, response: Response) {
+  async apply(request: Request, response?: Response, collector?: HeadersCollector) {
     const headerRules = await parseHeaders({
       headersFiles: this.#headersFiles,
       configPath: this.#configPath,
@@ -55,9 +57,11 @@ export class HeadersHandler {
     const matchingHeaderRules = headersForPath(headerRules, new URL(request.url).pathname)
 
     for (const [key, value] of Object.entries(matchingHeaderRules)) {
-      response.headers.set(key, value)
+      response?.headers.set(key, value)
+
+      collector?.(key, value)
     }
 
-    return response
+    return matchingHeaderRules
   }
 }
diff --git a/packages/vite-plugin/src/main.ts b/packages/vite-plugin/src/main.ts
