ClientIPFromXFF: zero-allocation lazy right-to-left walk

middleware.ClientIPFromXFF sits in the request hot path of any chi server
running behind a proxy fleet. Per the #967 review, "each allocation counts" —
at high RPS the per-request mergeXFF allocations are small individually but
show up in GC pressure across many handlers.

The previous implementation built a fully materialized merged XFF slice via
mergeXFF, then walked it right-to-left and returned at the first non-trusted
entry. In the common case — one trusted hop, the rightmost XFF entry IS the
client — we paid to allocate and populate the whole chain only to inspect
the last cell.

Replace it with a lazy walker that iterates headers right-to-left and, within
each header, iterates comma-separated entries right-to-left via
strings.LastIndexByte. Substrings alias the original header storage, no
copies. The walker returns at the first parseable non-trusted entry without
ever materializing a slice.

Per-request allocation impact (XFF present, typical "1 header, 3 IPs,
1 trusted hop"):

  Before:  ~4 small allocations
           - initial mergeXFF backing array
           - strings.Split's []string per header value
           - 2 regrowths of the result slice as it fills
  After:   0 allocations
           - returns on the first iteration; nothing materialized

Worst case (entire chain inside trusted prefixes, walker scans all entries):
still 0 allocations.

Correctness validated three independent ways:

  - Algorithm conformance: every requirement of the PR's rightmost-
    untrusted spec maps line-by-line to the new walker — multi-header
    merge, empty/whitespace drop, parse-failure skip, trust-prefix skip,
    normalization via parseHeaderAddr (Unmap + zone strip).

  - Iteration-order equivalence: walking headers in reverse and each
    header's entries in reverse via LastIndexByte yields exactly the
    same sequence as mergeXFF's flat list walked right-to-left.

  - All existing ClientIPFromXFF tests pass: multi-header merge,
    rightmost-untrusted spoofing scenarios, CIDR boundary membership,
    v4-mapped folding, IPv6 zone stripping, security regression pins.

  - Brute-force equivalence fuzz against the original mergeXFF-based
    walker over 200k random inputs (valid IPs, garbage, v4-mapped,
    zoned, whitespace, leading/trailing/double commas, empty headers):
    zero divergences.

mergeXFF is unchanged and still used by ClientIPFromXFFTrustedProxies, which
genuinely needs the total count for slot indexing.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Vojtech Vitek 2026-05-21 00:32:43 +02:00
parent 3e98c2dc75
commit 09ddca984a
No known key found for this signature in database

View file

@ -192,17 +192,34 @@ func mergeXFF(headers []string) []string {
return out
}
// rightmostUntrustedXFF walks merged XFF right-to-left, skipping IPs that
// match trustedPrefixes (and unparseable entries), and returns the first
// remaining valid IP.
// rightmostUntrustedXFF walks all X-Forwarded-For header values right-to-left
// across the merged chain, skipping IPs that match trustedPrefixes (and
// unparseable / empty entries), and returns the first remaining valid IP.
//
// Walks the headers lazily rather than calling [mergeXFF] so the common case
// — one trusted hop, the rightmost entry is the client — returns on the very
// first iteration without materializing the full chain. Zero allocations
// beyond what [netip.ParseAddr] does internally.
func rightmostUntrustedXFF(headers []string, trustedPrefixes []netip.Prefix) (netip.Addr, bool) {
xff := mergeXFF(headers)
for i := len(xff) - 1; i >= 0; i-- {
ip, ok := parseHeaderAddr(xff[i])
if !ok || inAnyPrefix(ip, trustedPrefixes) {
continue
for hi := len(headers) - 1; hi >= 0; hi-- {
h := headers[hi]
for h != "" {
var v string
if i := strings.LastIndexByte(h, ','); i >= 0 {
v, h = h[i+1:], h[:i]
} else {
v, h = h, ""
}
v = strings.TrimSpace(v)
if v == "" {
continue
}
ip, ok := parseHeaderAddr(v)
if !ok || inAnyPrefix(ip, trustedPrefixes) {
continue
}
return ip, true
}
return ip, true
}
return netip.Addr{}, false
}