net/http/internal/http2: enable SetReuseFrames in server and Transport

[ChrisLundquist]

This stack extends Framer.SetReuseFrames to cover *WindowUpdateFrame,
*HeadersFrame, and *MetaHeadersFrame (in addition to the existing
*DataFrame), then calls SetReuseFrames once on the per-connection
Framer in serverConn and Transport.newClientConn. Result: ~50% fewer
per-op allocations on the package's read-path benchmarks
(BenchmarkDownloadFrameSize, BenchmarkClientGzip), with no measurable
change on write-path benchmarks and no API change.

A new GODEBUG=http2reuseframes=0 setting is registered alongside
http2client / http2server / http2debug and reverts to the pre-CL
allocate-per-frame behavior.

Background

Framer.SetReuseFrames has shipped as an opt-in Framer method since
golang/net CL 34812 (commit bb807669, 2017-02-27, fixing golang#18502). It
was added for gRPC-Go, whose Framer profiling showed parseDataFrame
accounting for ~66% of allocations (1.4 GB of 2.2 GB) on a 64-conn /
100-stream / 900K RT/sec benchmark. gRPC-Go calls SetReuseFrames
directly on the Framer it owns.

No in-tree caller in the standard library has ever opted in, so the
cache has been effectively dead code from the stdlib's perspective
for nine years. This CL turns it on.

Prior attempts and reviewer concerns

This is the third attempt to enable frame reuse on the stdlib's
HTTP/2 server/Transport:

• Issue x/net/http2: improve frame decoding performance by reusing frames golang/go#68352 (still open, 2024-07-09): a request to improve
  frame decoding performance. neild rejected a user-facing config
  option ("There's no need for a user-configurable option here.
  If there are performance improvements that can be made to frame
  decoding in the HTTP/2 implementation, we can just make them.")
  but left the door open for internal enablement.

• golang/net CL 597455 (PR x/http/net: enable SetFrameReuse in server and client connections golang/net#216, 2024-07-10): tried to
  enable on both server and Transport unconditionally. neild's
  blocking review: "this is not correct. The server read goroutine
  (serverConn.readFrames) reads frames and delivers them to the
  main server goroutine for processing," and "Changing the HTTP/2
  server and/or transport to use the frame cache is likely to
  require some significant refactoring." Stale; never landed.

• golang/net CL 676235 (server-only, 2025-05-25): neild Hold+1 on
  2025-06-24: "this is not a safe change for the server.
  SetReuseFrames causes each frame to be invalidated by the next
  call to ReadFrame, but the server processes frames concurrently
  with ReadFrame calls." Abandoned 2025-10-24.

The blocker on both prior CLs was correctness, specifically retention
of frame data past the next ReadFrame. This CL addresses that with a
static retention audit, a race-detector test that exercises the gated
handoff, an end-to-end stress test under -race, and a GODEBUG escape
hatch in case the analysis missed something.

Stack layout

Six commits, each independently reviewable:

1. reuse *WindowUpdateFrame across ReadFrame calls
2. reuse *HeadersFrame across ReadFrame calls
3. reuse *MetaHeadersFrame across ReadFrame calls
4. add microbenchmarks for the SetReuseFrames path
5. add race-detector tests (positive control, adversarial negative
   control, end-to-end stress)
6. enable SetReuseFrames in server and Transport, register
   http2reuseframes GODEBUG

Commits 1-3 mirror the existing *DataFrame cache pattern from CL
34812: wholesale "*p = T{...}" reset at the top of each parse
function, slot in frameCache, nil-safe getFrame getter. No
behavior change without SetReuseFrames; the caches are dormant unless
opted in.

Safety analysis

Static retention audit across every code path that consumes a
reusable *Frame, plus a separate concurrency audit. Per frame type:

*DataFrame
f.Data() is copied into dataBuffer.Write
(databuffer.go:126 copy(chunk[b.w:], p)) before readMore. The
pool-allocated chunk has independent backing.

*WindowUpdateFrame
Struct has only scalar fields. Safe by construction.

*HeadersFrame
Both server and Transport set Framer.ReadMetaHeaders during init
(server.go:322, transport.go:663), so a bare *HeadersFrame never
reaches consumer code. readMetaFrame (frame.go:1868-1869) clears
headerFragBuf=nil and invalidates the embedded *HeadersFrame
before returning.

*MetaHeadersFrame
readMetaFrame:1772 does "*mh = MetaHeadersFrame{HeadersFrame: hf}",
zeroing Fields and Truncated. Append grows a fresh backing array
per parse. hpack.decodeString (vendor/.../hpack.go:509-520)
returns string(u.b) or buf.String(), both of which copy, so
Name/Value strings are independently allocated and do not alias
readBuf. Server's processHeaders / newWriterAndRequest and
Transport's handleResponse / processTrailers iterate Fields
synchronously and copy into fresh http.Header maps before
returning. No code stores *MetaHeadersFrame past dispatch.

Concurrency:

Server: serverConn.readFrames (server.go:692-711) sends each
parsed frame on readFrameCh then blocks on gate. The serve
goroutine receives, calls processFrameFromReader synchronously,
then res.readMore() (server.go:854), which releases the gate.
The single readMore call site fires only after the synchronous
dispatch returns, so the cache is never overwritten while
consumer code still references it.

Transport: clientConnReadLoop.run (transport.go:2046-2090) reads
frames in a tight loop with no per-frame gate, so each process*
function must fully consume aliased data before returning.
Verified: every byte that escapes the loop is either copied
(DataFrame -> bufPipe) or composed of immutable,
independently-allocated Go strings (Header maps populated from
hpack-decoded strings).

Spawned goroutines: runHandler (server) only sees the fresh
*ServerRequest whose Header/Trailer/URL are independently
allocated. writeFrameAsync, body-close, Shutdown, ping writers
don't touch read-side cached frames.

Defensive cleanup: GoAwayFrame.debugData is cleared after copying it
to cc.goAwayDebug in processGoAway. GoAwayFrame is not in frameCache
today so the retained cc.goAway=f pointer is safe, but the Transport
already stores a *GoAwayFrame across ReadFrame calls; clearing the
only field that aliases the read buffer prevents a future addition of
GoAwayFrame to the reuse cache from silently turning
cc.goAway.DebugData() into a use-after-overwrite.

Benchmarks

-count=10 -benchtime=1s -benchmem, linux/amd64 i7-6770HQ @ 2.60GHz,
master vs h2-frame-cache, via benchstat.

Allocations per op (the main win):

Benchmark                       master   branch   delta     p
ClientGzip                         174       71  -59.20% 0.000
DownloadFrameSize/16k           369.2k   196.7k  -46.73% 0.000
DownloadFrameSize/64k           96.32k   49.12k  -49.00% 0.000
DownloadFrameSize/128k          48.62k   24.53k  -49.55% 0.000
DownloadFrameSize/256k          24.32k   12.19k  -49.87% 0.000
DownloadFrameSize/512k          12,175    6,090  -49.98% 0.000
ClientRequestHeaders/0              50       46   -8.00% 0.000
ClientRequestHeaders/10             74       70   -5.41% 0.000
ClientResponseHeaders/0             50       46   -8.00% 0.000
ClientResponseHeaders/10           115      111   -3.48% 0.000
geomean (allocs/op)                            -19.46%

Write-side benchmarks (WriteScheduler*, WriteQueue) are unchanged
within noise; those paths don't touch ReadFrame.

Latency / throughput (sec/op):

Benchmark                       delta sec/op     p
ClientGzip                      -2.74%        0.023
ClientRequestHeaders/0          -1.04%        0.029
ClientResponseHeaders/0         -1.12%        0.019
DownloadFrameSize/* sec/op      ~ (10-54% RSD, socket noise)
Write/WriteQueue                ~ (p >= 0.22)

Per-cache attribution from microbenchmarks added in commit 4:

Cache                  Default                Reused
ParseDataFrame         115 ns / 48 B / 1 alloc   76 ns / 0 / 0
ParseWindowUpdateFrame  92 ns / 16 B / 1 alloc   74 ns / 0 / 0
ParseHeadersFrame      124 ns / 48 B / 1 alloc   82 ns / 0 / 0
ReadMetaFrame         1073 ns / 472 B / 9     951 ns / 376 / 7

The residual 7 allocations in ReadMetaFrame/Reused come from HPACK
Fields-slice growth and the SetEmitFunc closure; out of scope for
this stack.

Test plan

Tests added in commit 5 and verified against the enablement commit:

frame_reuse_race_test.go (package http2, synthetic Framer-pair tests):

• TestFrameReuseRaceCorrect: positive control. Models
  serverConn.readFrames with a reader goroutine, a channel, a
  per-frame gate, and a consumer that fully consumes payload
  before signalling done. 800 frames across DATA, WINDOW_UPDATE,
  HEADERS, HEADERS+CONTINUATION. Must PASS under -race.

• TestFrameReuseRaceAdversarial: negative control, gated behind
  H2_REUSE_RACE_NEGATIVE=1. Same plumbing, but deliberately leaks
  slices into a sidecar goroutine across the next ReadFrame. Must
  RACE under -race to verify the detector functions for this
  pattern.

frame_reuse_e2e_test.go (package http2_test, real server + Transport):

• TestFrameReuseEndToEndStress: 8 workers x 25 multiplexed
  requests through the real httptest-based HTTP/2 server and
  net/http.Transport, both running with SetReuseFrames enabled.
  Handler and client touch every byte of every header name/value
  and trailer in both directions, drain bodies. Regression test
  against future refactors of processHeaders / handleResponse /
  processTrailers / processData that fail to copy aliased data.

Validation runs (linux/amd64):

Run                                              Result
net/http/internal/http2 -race -count=30          PASS  8m13s
net/http/internal/http2 -race -count=10
    -cpu=1,2,4,8                                 PASS  6m17s
net/http -race -count=10                         PASS  ~5min
TestFrameReuseRaceCorrect -race -count=200       PASS  5s
TestFrameReuseRaceAdversarial under
    H2_REUSE_RACE_NEGATIVE=1 -race -count=10     RACE  10/10
TestFrameReuseEndToEndStress -race               PASS  0.5s
GODEBUG=http2reuseframes=0 + correct-path
    tests -race                                  PASS

GODEBUG escape hatch

Registered alongside the existing http2 GODEBUGs in
src/internal/godebugs/table.go:

Value                              Behavior
unset or http2reuseframes=1        reuse on (default)
GODEBUG=http2reuseframes=0         reuse off (pre-CL behavior)
                                   increments
                                   /godebug/non-default-behavior/
                                   http2reuseframes:events

Documented in doc/godebug.md under the Go 1.27 section. The intent is
a compat hatch, not a tuning knob: operators can disable without
recompiling if the static analysis and race coverage missed
something. This addresses the safety concerns from prior CLs while
staying consistent with the preference against user-facing
performance knobs (this is purely a safety/compat escape).

Compatibility

• No API change.
• No change in public behavior; the read loop returns the same
  parsed frame values, only the per-call heap allocation is
  elided.
• internal/http2 is unimportable from user code; the Framer type
  and SetReuseFrames method remain unreachable from outside the
  stdlib.
• The escape hatch is registered without Changed/Old version
  gating (mirroring http2client / http2server) since there is no
  language-visible behavior change to anchor to a go directive
  version.

Updates golang#18502
Updates golang#68352

[ChrisLundquist]

Superseded by golang#79634. This fork-internal PR was for pre-review