feat: add support for headers config

Author: serhalp

.release-please-manifest.json

@@ -4,6 +4,7 @@
   "packages/dev": "2.3.0",
   "packages/dev-utils": "2.2.0",
   "packages/functions": "3.1.9",
+  "packages/headers": {},
   "packages/otel": "1.1.0",
   "packages/redirects": "1.1.4",
   "packages/runtime": "2.2.2",

package-lock.json

@@ -8,6 +8,7 @@
     "packages/blobs",
     "packages/cache",
     "packages/functions",
+    "packages/headers",
     "packages/redirects",
     "packages/runtime",
     "packages/static",

package.json

@@ -1,6 +1,7 @@
 import { exec } from 'node:child_process'
 import { promises as fs } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { EOL } from 'node:os'
+import path, { dirname, join } from 'node:path'
 import { promisify } from 'node:util'
 
 import tmp from 'tmp-promise'
@@ -88,6 +89,24 @@ export class Fixture {
     return this
   }
 
+  withHeadersFile({
+    headers = [],
+    pathPrefix = '',
+  }: {
+    headers?: { headers: string[]; path: string }[]
+    pathPrefix?: string
+  }) {
+    const dest = path.join(pathPrefix, '_headers')
+    const contents = headers
+      .map(
+        ({ headers: headersValues, path: headerPath }) =>
+          `${headerPath}${EOL}${headersValues.map((header) => `  ${header}`).join(EOL)}`,
+      )
+      .join(EOL)
+
+    return this.withFile(dest, contents)
+  }
+
   withStateFile(state: object) {
     this.files['.netlify/state.json'] = JSON.stringify(state)
 

packages/dev-utils/src/test/fixture.ts

@@ -57,6 +57,7 @@
     "@netlify/config": "^23.0.4",
     "@netlify/dev-utils": "2.2.0",
     "@netlify/functions": "3.1.9",
+    "@netlify/headers": "^0.0.0",
     "@netlify/redirects": "1.1.4",
     "@netlify/runtime": "2.2.2",
     "@netlify/static": "1.1.4"

packages/dev/package.json

@@ -88,6 +88,158 @@ describe('Handling requests', () => {
       await fixture.destroy()
     })
 
+    test('Headers rules matching a static file are applied', async () => {
+      const fixture = new Fixture()
+        .withFile(
+          'netlify.toml',
+          `[build]
+           publish = "public"
+           [[headers]]
+           for = "/hello.txt"
+           [headers.values]
+           "Vary" = "User-Agent"
+           `,
+        )
+        .withHeadersFile({
+          pathPrefix: 'public',
+          headers: [{ path: '/hello.txt', headers: ['Cache-Control: max-age=42'] }],
+        })
+        .withFile('public/hello.txt', 'Hello from hello.txt')
+        .withFile('public/another-path.txt', 'Hello from another-path.txt')
+      const directory = await fixture.create()
+      const req = new Request('https://site.netlify/hello.txt')
+      const dev = new NetlifyDev({
+        projectRoot: directory,
+      })
+      await dev.start()
+
+      const matchRes = await dev.handle(req)
+
+      expect(await matchRes?.text()).toBe('Hello from hello.txt')
+      expect(Object.fromEntries(matchRes?.headers?.entries() ?? [])).toMatchObject({
+        'cache-control': 'max-age=42',
+        vary: 'User-Agent',
+      })
+
+      const noMatchRes = await dev.handle(new Request('https://site.netlify/another-path.txt'))
+      expect(await noMatchRes?.text()).toBe('Hello from another-path.txt')
+      expect(Object.fromEntries(noMatchRes?.headers?.entries() ?? [])).not.toMatchObject({
+        'cache-control': 'max-age=42',
+        vary: 'User-Agent',
+      })
+
+      await fixture.destroy()
+    })
+
+    test('Headers rules matching target of a rewrite to a static file are applied', async () => {
+      const fixture = new Fixture()
+        .withFile(
+          'netlify.toml',
+          `[build]
+           publish = "public"
+           [[headers]]
+           for = "/from"
+           [headers.values]
+           "X-Custom" = "value for from rule"
+           "X-Custom-From" = "another value for from rule"
+           [[headers]]
+           for = "/to.txt"
+           [headers.values]
+           "X-Custom" = "value for to rule"
+           `,
+        )
+        .withFile('public/_redirects', `/from  /to.txt  200`)
+        .withFile('public/to.txt', `to.txt content`)
+      const directory = await fixture.create()
+      const dev = new NetlifyDev({
+        projectRoot: directory,
+      })
+      await dev.start()
+
+      const directRes = await dev.handle(new Request('https://site.netlify/to.txt'))
+      expect(await directRes?.text()).toBe('to.txt content')
+      expect(directRes?.headers.get('X-Custom')).toBe('value for to rule')
+      expect(directRes?.headers.get('X-Custom-From')).toBeNull()
+
+      const rewriteRes = await dev.handle(new Request('https://site.netlify/from'))
+      expect(await rewriteRes?.text()).toBe('to.txt content')
+      expect(rewriteRes?.headers.get('X-Custom')).toBe('value for to rule')
+      expect(rewriteRes?.headers.get('X-Custom-From')).toBeNull()
+
+      await fixture.destroy()
+    })
+
+    test('Headers rules matching a static file that shadows a function are applied', async () => {
+      const fixture = new Fixture()
+        .withFile(
+          'netlify.toml',
+          `[build]
+           publish = "public"
+           [[headers]]
+           for = "/shadowed-path.html"
+           [headers.values]
+           "X-Custom-Header" = "custom-value"
+           `,
+        )
+        .withFile('public/shadowed-path.html', 'Hello from the static file')
+        .withFile(
+          'netlify/functions/shadowed-path.mjs',
+          `export default async () => new Response("Hello from the function");
+           export const config = { path: "/shadowed-path.html", preferStatic: true };
+          `,
+        )
+      const directory = await fixture.create()
+      const req = new Request('https://site.netlify/shadowed-path.html')
+      const dev = new NetlifyDev({
+        projectRoot: directory,
+      })
+      await dev.start()
+
+      const res = await dev.handle(req)
+      expect(await res?.text()).toBe('Hello from the static file')
+      expect(Object.fromEntries(res?.headers?.entries() ?? [])).toMatchObject({
+        'x-custom-header': 'custom-value',
+      })
+
+      await fixture.destroy()
+    })
+
+    test('Headers rules matching an unshadowed function on a custom path are not applied', async () => {
+      const fixture = new Fixture()
+        .withFile(
+          'netlify.toml',
+          `[build]
+           publish = "public"
+           [[headers]]
+           for = "/hello.html"
+           [headers.values]
+           "X-Custom-Header" = "custom-value"
+           `,
+        )
+        .withFile('public/hello.html', 'Hello from the static file')
+        .withFile(
+          'netlify/functions/hello.mjs',
+          `export default async () => new Response("Hello from the function");
+           export const config = { path: "/hello.html" };
+          `,
+        )
+      const directory = await fixture.create()
+      const req = new Request('https://site.netlify/hello.html')
+      const dev = new NetlifyDev({
+        projectRoot: directory,
+      })
+      await dev.start()
+
+      const res = await dev.handle(req)
+      expect(await res?.text()).toBe('Hello from the function')
+      expect(res?.headers.get('x-custom-header')).toBeNull()
+
+      await fixture.destroy()
+    })
+
+    // TODO(FRB-1834): Implement this test when edge functions are supported
+    test.todo('Headers rules matching a path are not applied to edge function responses')
+
     test('Invoking a function, updating its contents and invoking it again', async () => {
       let fixture = new Fixture()
         .withFile(

packages/dev/src/main.test.ts

@@ -5,6 +5,7 @@ import process from 'node:process'
 import { resolveConfig } from '@netlify/config'
 import { ensureNetlifyIgnore, getAPIToken, LocalState, type Logger } from '@netlify/dev-utils'
 import { FunctionsHandler } from '@netlify/functions/dev'
+import { HeadersHandler } from '@netlify/headers'
 import { RedirectsHandler } from '@netlify/redirects'
 import { StaticHandler } from '@netlify/static'
 
@@ -40,6 +41,15 @@ export interface Features {
     enabled: boolean
   }
 
+  /**
+   * Configuration options for Netlify response headers.
+   *
+   * {@link} https://docs.netlify.com/routing/headers/
+   */
+  headers?: {
+    enabled: boolean
+  }
+
   /**
    * Configuration options for Netlify redirects and rewrites.
    *
@@ -78,6 +88,7 @@ export class NetlifyDev {
     blobs: boolean
     environmentVariables: boolean
     functions: boolean
+    headers: boolean
     redirects: boolean
     static: boolean
   }
@@ -99,6 +110,7 @@ export class NetlifyDev {
       blobs: options.blobs?.enabled !== false,
       environmentVariables: options.environmentVariables?.enabled !== false,
       functions: options.functions?.enabled !== false,
+      headers: options.headers?.enabled !== false,
       redirects: options.redirects?.enabled !== false,
       static: options.staticFiles?.enabled !== false,
     }
@@ -123,6 +135,16 @@ export class NetlifyDev {
         })
       : null
 
+    // Headers
+    const headers = this.#features.headers
+      ? new HeadersHandler({
+          configPath: this.#config?.configPath,
+          configHeaders: this.#config?.config.headers,
+          projectDir: this.#projectRoot,
+          publishDir: this.#config?.config.build.publish ?? undefined,
+        })
+      : null
+
     // Redirects
     const redirects = this.#features.redirects
       ? new RedirectsHandler({
@@ -155,7 +177,8 @@ export class NetlifyDev {
         const staticMatch = await staticFiles?.match(request)
 
         if (staticMatch) {
-          return staticMatch.handle()
+          const response = await staticMatch.handle()
+          return headers != null ? headers.handle(request, response) : response
         }
       }
 
@@ -177,7 +200,12 @@ export class NetlifyDev {
       const response = await redirects?.handle(request, redirectMatch, async (maybeStaticFile: Request) => {
         const staticMatch = await staticFiles?.match(maybeStaticFile)
 
-        return staticMatch?.handle
+        if (!staticMatch) return
+
+        return async () => {
+          const response = await staticMatch.handle()
+          return headers != null ? headers.handle(new Request(redirectMatch.target), response) : response
+        }
       })
       if (response) {
         return response
@@ -187,7 +215,8 @@ export class NetlifyDev {
     // 3. Check if the request matches a static file.
     const staticMatch = await staticFiles?.match(request)
     if (staticMatch) {
-      return staticMatch.handle()
+      const response = await staticMatch.handle()
+      return headers != null ? headers.handle(request, response) : response
     }
   }
 

packages/dev/src/main.ts

@@ -0,0 +1 @@
+dist

packages/headers/.gitignore

@@ -0,0 +1 @@
+# Changelog