perf(headers): O(1) case-insensitive lookup in HeadersAdapter

[benfavre]

Summary

• Replace O(n) Object.keys().find() with O(1) Map.get() in the HeadersAdapter Proxy traps (get, set, has, deleteProperty)
• Build a Map<lowercase, originalKey> once in the constructor from initial headers
• Keep the map in sync on set (adds entries) and deleteProperty (removes entries)
• Handle out-of-band mutations on the underlying IncomingHttpHeaders object by falling back to a linear scan on cache miss and caching the result

Motivation

The HeadersAdapter is used on every SSR request to wrap Node.js IncomingHttpHeaders. Every call to .get(), .has(), .set(), or delete on the adapter triggers a Proxy trap that does:

Object.keys(headers).find(o => o.toLowerCase() === lowercased)

This is O(n) per access where n = number of headers. A typical HTTP request carries 10-20 headers, and during SSR rendering headers are accessed many times (cookies, content-type, accept, authorization, user-agent, x-forwarded-for, custom headers, etc.). The cumulative cost of repeated linear scans over every header key on every access adds up in high-throughput SSR scenarios.

This is the same class of optimization highlighted in the TanStack Start blog post about 5x SSR throughput — avoiding O(n) operations in hot paths is one of the most impactful patterns for SSR performance.

The fix pre-computes a Map<string, string> (lowercase -> original key) and uses Map.get() for O(1) lookups. The map is kept consistent through set/delete operations and handles the edge case where external code mutates the IncomingHttpHeaders object directly (tested in the existing test suite).

Test plan

• All 15 existing HeadersAdapter unit tests pass, including the "mutated out of band" case that validates the fallback path
• No new tests needed — this is a pure performance optimization with identical observable behavior

🤖 Generated with Claude Code

[nextjs-bot]

Allow CI Workflow Run

• approve CI run for commit: 5c3fce9

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[nextjs-bot]

Allow CI Workflow Run

• approve CI run for commit: 5c3fce9

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[benfavre]

Test Verification

• headers.test.ts: 15/15 passed (case-insensitive, sealed, out-of-band mutation)
• All existing HeadersAdapter behavior preserved

All tests run on the perf/combined-all branch against canary. Total: 203 tests across 13 suites, all passing.