fix(docs): preserve negotiated response cache headers

.github/workflows/docs-negotiation.yml

@@ -0,0 +1,63 @@
+name: docs content negotiation
+
+on:
+  pull_request:
+    paths:
+      - 'apps/docs/**'
+      - 'patches/next@*.patch'
+      - 'package.json'
+      - 'bun.lock'
+      - '.github/workflows/docs-negotiation.yml'
+  push:
+    branches: [staging]
+    paths:
+      - 'apps/docs/**'
+      - 'patches/next@*.patch'
+      - 'package.json'
+      - 'bun.lock'
+      - '.github/workflows/docs-negotiation.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-negotiation-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  http:
+    name: docs HTTP
+    runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'linux-x64-8-core' }}
+    timeout-minutes: 15
+    env:
+      DATABASE_URL: postgresql://docs_test:docs_test@127.0.0.1:1/docs_test
+      DOCS_E2E_BASE_URL: http://127.0.0.1:3001
+      DOCS_NEGOTIATION_REPORT_PATH: ${{ github.workspace }}/test-results/docs-negotiation.json
+      DOCS_HEADER_REPORT_PATH: ${{ github.workspace }}/test-results/docs-headers.json
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
+      - name: Setup workspace
+        uses: ./.github/actions/setup
+        with:
+          provider: ${{ vars.CI_PROVIDER }}
+      - name: Build production docs
+        run: bun run --cwd apps/docs build
+      - name: Verify native header edge cases
+        run: bun run --cwd apps/docs test:headers:e2e
+      - name: Verify HTTP content negotiation
+        run: |
+          mkdir -p test-results
+          bun run --cwd apps/docs start --port 3001 >test-results/docs-server.log 2>&1 &
+          DOCS_SERVER_PID=$!
+          trap 'kill "$DOCS_SERVER_PID" 2>/dev/null || true' EXIT
+          bun run --cwd apps/docs test:negotiation:e2e
+      - name: Upload HTTP regression report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: docs-negotiation-report
+          path: test-results/
+          if-no-files-found: warn
+          retention-days: 14

apps/docs/package.json

@@ -11,6 +11,8 @@
     "start": "next start",
     "postinstall": "fumadocs-mdx",
     "test": "vitest run",
+    "test:negotiation:e2e": "bun scripts/test-negotiation-e2e.ts",
+    "test:headers:e2e": "bun scripts/test-header-merge-e2e.ts",
     "type-check": "fumadocs-mdx && tsc --noEmit",
     "lint": "biome check --write --unsafe .",
     "lint:check": "biome check .",

apps/docs/scripts/test-header-merge-e2e.ts

@@ -0,0 +1,206 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import { createRequire } from 'node:module'
+import { dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { toRecord } from '@sim/utils/object'
+import { patchSetHeaderWithCookieSupport } from 'next/dist/server/lib/patch-set-header'
+import { addRequestMeta } from 'next/dist/server/request-meta'
+
+const logger = createLogger('DocsHeaderMergeE2E')
+const reportPath = process.env.DOCS_HEADER_REPORT_PATH
+if (!reportPath) throw new Error('DOCS_HEADER_REPORT_PATH is required')
+
+interface HeaderCase {
+  name: string
+  header: string
+  before?: string | string[]
+  value: string | string[]
+  expected?: string[]
+  rejected?: boolean
+  middlewareCookies?: string[]
+}
+
+const cases: HeaderCase[] = [
+  {
+    name: 'existing Vary survives a later write',
+    header: 'Vary',
+    before: 'Origin',
+    value: 'RSC',
+    expected: ['origin', 'rsc'],
+  },
+  {
+    name: 'array fields survive a later write',
+    header: 'Vary',
+    before: ['Accept', 'rSc'],
+    value: ['RSC', 'Next-Url'],
+    expected: ['accept', 'rsc', 'next-url'],
+  },
+  {
+    name: 'mixed casing does not duplicate fields',
+    header: 'Vary',
+    before: 'Accept, rSc',
+    value: 'RSC, aCcEpT, Next-Url, RSC',
+    expected: ['accept', 'rsc', 'next-url'],
+  },
+  {
+    name: 'wildcard remains the only field',
+    header: 'Vary',
+    before: '*',
+    value: 'RSC',
+    expected: ['*'],
+  },
+  {
+    name: 'invalid bytes cannot be trimmed away',
+    header: 'Vary',
+    value: 'RSC\r\n',
+    rejected: true,
+  },
+  {
+    name: 'wildcard cannot hide invalid array bytes',
+    header: 'Vary',
+    value: ['*', 'bad\r\nheader'],
+    rejected: true,
+  },
+  {
+    name: 'other headers retain replacement behavior',
+    header: 'X-Probe',
+    before: 'old',
+    value: 'new',
+    expected: ['new'],
+  },
+  {
+    name: 'middleware cookies remain present',
+    header: 'Set-Cookie',
+    value: ['probe_b=2'],
+    middlewareCookies: ['probe_a=1'],
+    expected: ['probe_a=1', 'probe_b=2'],
+  },
+]
+
+const require = createRequire(import.meta.url)
+const esmPath = require.resolve('next/dist/esm/server/lib/patch-set-header.js')
+const imported: unknown = await import(pathToFileURL(esmPath).href)
+const esmPatch = toRecord(imported).patchSetHeaderWithCookieSupport
+if (typeof esmPatch !== 'function') throw new Error('The ESM header merger is unavailable')
+
+const variants: Array<{
+  name: string
+  apply: (req: IncomingMessage, res: ServerResponse) => void
+}> = [
+  { name: 'CommonJS', apply: patchSetHeaderWithCookieSupport },
+  {
+    name: 'ESM',
+    apply: (req, res) => {
+      esmPatch(req, res)
+    },
+  },
+]
+const checks: Array<{
+  name: string
+  status: 'passed' | 'failed'
+  durationMs: number
+  error?: string
+}> = []
+
+const suiteStarted = performance.now()
+try {
+  for (const variant of variants) {
+    const server = createServer((req, res) => {
+      const entry = cases[Number(req.url?.slice(1))]
+      if (!entry) {
+        res.writeHead(404).end()
+        return
+      }
+      try {
+        variant.apply(req, res)
+        if (entry.middlewareCookies)
+          addRequestMeta(req, 'middlewareCookie', entry.middlewareCookies)
+        if (entry.before) res.setHeader(entry.header, entry.before)
+      } catch (error) {
+        res.statusCode = 500
+        res.end(JSON.stringify({ error: getErrorMessage(error) }))
+        return
+      }
+      try {
+        res.setHeader(entry.header, entry.value)
+        res.end(JSON.stringify({ accepted: true }))
+      } catch (error) {
+        res.statusCode = 400
+        res.end(JSON.stringify({ rejected: true, code: toRecord(error).code }))
+      }
+    })
+    await new Promise<void>((resolve, reject) => {
+      server.once('error', reject)
+      server.listen(0, '127.0.0.1', resolve)
+    })
+    try {
+      const address = server.address()
+      if (!address || typeof address === 'string')
+        throw new Error('No loopback listener is available')
+      for (const [index, entry] of cases.entries()) {
+        const started = performance.now()
+        let error: string | undefined
+        try {
+          const response = await fetch(`http://127.0.0.1:${address.port}/${index}`, {
+            signal: AbortSignal.timeout(5000),
+          })
+          const payload: unknown = await response.json()
+          if (entry.rejected) {
+            const body = toRecord(payload)
+            if (
+              response.status !== 400 ||
+              body.rejected !== true ||
+              body.code !== 'ERR_INVALID_CHAR'
+            )
+              throw new Error('Invalid header bytes were accepted')
+          } else {
+            const fields =
+              entry.header === 'Set-Cookie'
+                ? response.headers.getSetCookie()
+                : (response.headers.get(entry.header) ?? '')
+                    .split(',')
+                    .map((field) => field.trim().toLowerCase())
+            const expected = [...(entry.expected ?? [])].sort()
+            if (
+              response.status !== 200 ||
+              new Set(fields).size !== fields.length ||
+              JSON.stringify([...fields].sort()) !== JSON.stringify(expected)
+            )
+              throw new Error(`Unexpected response fields: ${JSON.stringify(fields)}`)
+          }
+        } catch (caught) {
+          error = getErrorMessage(caught)
+        }
+        checks.push({
+          name: `${variant.name}: ${entry.name}`,
+          status: error ? 'failed' : 'passed',
+          durationMs: Math.round(performance.now() - started),
+          ...(error ? { error } : {}),
+        })
+      }
+    } finally {
+      await new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve()))
+      )
+    }
+  }
+} catch (error) {
+  checks.push({
+    name: 'Header suite lifecycle',
+    status: 'failed',
+    durationMs: Math.round(performance.now() - suiteStarted),
+    error: getErrorMessage(error),
+  })
+} finally {
+  await mkdir(dirname(reportPath), { recursive: true })
+  await writeFile(reportPath, `${JSON.stringify({ checks }, null, 2)}\n`)
+}
+
+const failures = checks.filter((check) => check.status === 'failed')
+if (failures.length) {
+  logger.error('Native header regression checks failed', { failures })
+  process.exitCode = 1
+} else logger.info('Native header regression checks passed', { checks: checks.length })

apps/docs/scripts/test-negotiation-e2e.ts

@@ -0,0 +1,87 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { sleep } from '@sim/utils/helpers'
+
+const logger = createLogger('DocsNegotiationE2E')
+const origin = process.env.DOCS_E2E_BASE_URL
+const reportPath = process.env.DOCS_NEGOTIATION_REPORT_PATH
+if (!origin || !reportPath) {
+  throw new Error('DOCS_E2E_BASE_URL and DOCS_NEGOTIATION_REPORT_PATH are required')
+}
+const url = new URL('/introduction', origin)
+if (!['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+  throw new Error('The documentation server must use a loopback origin')
+}
+
+interface CheckResult {
+  name: string
+  status: 'passed' | 'failed'
+  durationMs: number
+  contentType?: string
+  vary?: string
+  error?: string
+}
+
+const cases = [
+  { name: 'HTML advertises its representation and router cache dimensions', accept: 'text/html' },
+  { name: 'Markdown negotiates at the same URL', accept: 'text/markdown' },
+  { name: 'HTML remains available after a Markdown request', accept: 'text/html' },
+] as const
+
+for (let attempt = 0; attempt < 20; attempt += 1) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(1000) })
+    await response.body?.cancel()
+    if (response.ok) break
+  } catch {}
+  await sleep(250)
+}
+
+const checks: CheckResult[] = []
+for (const entry of cases) {
+  const started = performance.now()
+  const result: CheckResult = { name: entry.name, status: 'failed', durationMs: 0 }
+  try {
+    const response = await fetch(url, {
+      headers: { Accept: entry.accept },
+      signal: AbortSignal.timeout(10000),
+    })
+    await response.body?.cancel()
+    result.contentType = response.headers.get('Content-Type') ?? ''
+    result.vary = response.headers.get('Vary') ?? ''
+    const fields = result.vary.split(',').map((field) => field.trim().toLowerCase())
+    if (!response.ok) throw new Error(`Unexpected HTTP status ${response.status}`)
+    if (!result.contentType.startsWith(entry.accept)) {
+      throw new Error(`Expected ${entry.accept}; received ${result.contentType}`)
+    }
+    if (!fields.includes('accept')) throw new Error('The response lost Vary: Accept')
+    if (entry.accept === 'text/html') {
+      for (const field of [
+        'rsc',
+        'next-router-state-tree',
+        'next-router-prefetch',
+        'next-router-segment-prefetch',
+      ]) {
+        if (!fields.includes(field)) throw new Error(`The response lost Vary: ${field}`)
+      }
+    }
+    if (fields.length !== new Set(fields).size) throw new Error('Vary contains duplicate fields')
+    result.status = 'passed'
+  } catch (error) {
+    result.error = getErrorMessage(error)
+  }
+  result.durationMs = Math.round(performance.now() - started)
+  checks.push(result)
+}
+
+await mkdir(dirname(reportPath), { recursive: true })
+await writeFile(reportPath, `${JSON.stringify({ checks }, null, 2)}\n`)
+const failures = checks.filter((check) => check.status === 'failed')
+if (failures.length) {
+  logger.error('Documentation negotiation failed', { failures })
+  process.exitCode = 1
+} else {
+  logger.info('Documentation negotiation passed', { checks: checks.length })
+}

package.json

@@ -212,6 +212,7 @@
     "drizzle-kit@0.31.10": "patches/drizzle-kit@0.31.10.patch",
     "postgres@3.4.9": "patches/postgres@3.4.9.patch",
     "oracledb@7.0.1": "patches/oracledb@7.0.1.patch",
-    "echarts@6.1.0": "patches/echarts@6.1.0.patch"
+    "echarts@6.1.0": "patches/echarts@6.1.0.patch",
+    "next@16.4.0": "patches/next@16.4.0.patch"
   }
 }