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

Call Framer.SetReuseFrames once on the per-connection Framer in both
serverConn (serveConn) and Transport (newClientConn) so the parsed
*DataFrame, *WindowUpdateFrame, *HeadersFrame, and *MetaHeadersFrame
structs returned by ReadFrame are reused across calls instead of
being heap-allocated each time. SetReuseFrames has shipped as an
opt-in Framer method since CL 34812 (golang/net, 2017) but no in-tree
caller previously opted in, so the cache was effectively dead code
from the standard library's perspective; this CL turns it on.

A new GODEBUG setting, http2reuseframes, is registered as a compat
escape hatch in line with the existing http2client / http2server /
http2debug settings:

  - default (or http2reuseframes=1): reuse on, this CL's behavior.
  - GODEBUG=http2reuseframes=0:      reuse disabled, pre-CL behavior.

If a deployment encounters an issue the static audit and -race
coverage didn't catch, operators can flip the setting without
recompiling.

Per-frame allocation savings, microbench numbers (linux/amd64, from
the BenchmarkParse* and BenchmarkReadMetaFrame benchmarks added
earlier in this stack):

  bench                            Default            Reused
  ParseDataFrame                   48 B, 1 alloc      0 B, 0 alloc
  ParseWindowUpdateFrame           16 B, 1 alloc      0 B, 0 alloc
  ParseHeadersFrame                48 B, 1 alloc      0 B, 0 alloc
  ReadMetaFrame                    472 B, 9 allocs    376 B, 7 allocs

End-to-end allocation reductions on the package's existing read-path
benchmarks (-count=10, benchstat master vs branch):

  bench                       allocs/op delta   p
  ClientGzip                  -59.20%           0.000
  DownloadFrameSize/16k       -46.73%           0.000
  DownloadFrameSize/64k       -49.00%           0.000
  DownloadFrameSize/128k      -49.55%           0.000
  DownloadFrameSize/256k      -49.87%           0.000
  DownloadFrameSize/512k      -49.98%           0.000
  ClientRequestHeaders/0      -8.00%            0.000
  ClientResponseHeaders/0     -8.00%            0.000
  ClientRequestHeaders/10     -5.41%            0.000
  ClientResponseHeaders/10    -3.48%            0.000
  geomean (allocs/op)         -19.46%

Write-side benchmarks (WriteScheduler*, WriteQueue) are unchanged, as
expected; those paths do not exercise ReadFrame. ClientGzip latency
also improves by -2.74% (p=0.023). The remaining allocations in
ReadMetaFrame come from HPACK Fields-slice growth and the
SetEmitFunc closure, which this CL does not address.

Reuse safety, by frame type:

  DataFrame
    serverConn.processData and clientConnReadLoop.processData read
    Length, StreamID, StreamEnded, and the Data() slice synchronously
    before returning. The bytes from Data() flow through
    {server,client}Conn.body / cs.bufPipe -> dataBuffer.Write, which
    copies into a pool-allocated chunk; no slice retained past
    ReadFrame.

  WindowUpdateFrame
    serverConn.processWindowUpdate and clientConnReadLoop.processWindowUpdate
    read only the scalar StreamID and Increment fields. The struct
    type has no slice fields, so there is nothing to alias the read
    buffer.

  HeadersFrame
    Both server and Transport set Framer.ReadMetaHeaders during init,
    so a bare *HeadersFrame is never delivered to consumer code; the
    Framer always returns *MetaHeadersFrame on a HEADERS frame.
    readMetaFrame clears MetaHeadersFrame.HeadersFrame.headerFragBuf
    and calls invalidate() on the embedded *HeadersFrame before
    returning. The aliased frag buf is therefore not exposed past
    readMetaFrame.

  MetaHeadersFrame
    The Fields slice is freshly allocated per parse: readMetaFrame
    does *mh = MetaHeadersFrame{HeadersFrame: hf} (Fields zeroed to
    nil), then the HPACK emit callback grows it via append, so each
    returned MetaHeadersFrame has its own backing array. HPACK
    Name/Value strings are independently allocated by the decoder
    (hpack.decodeString returns string(u.b) / buf.String(), both of
    which copy), so no string aliases the read buffer.
    serverConn.processHeaders / processTrailerHeaders and
    clientConnReadLoop.processHeaders / handleResponse / processTrailers
    iterate Fields synchronously on the read-loop / serve goroutine
    and copy strings into a fresh http.Header before returning.
    No code stores *MetaHeadersFrame past the dispatch.

Server-side gating: readFrames -> readFrameCh -> serve calls
processFrameFromReader synchronously and only then invokes
readMore(), which unblocks readFrames for the next ReadFrame. So
even though the server consumes frames on a different goroutine
from the one calling ReadFrame, every frame is fully consumed
before the cache is overwritten.

Transport-side gating: clientConnReadLoop.run consumes each frame
synchronously on the read-loop goroutine before the next
ReadFrame, and what escapes to the RoundTrip / response-body
goroutines is either copied (DataFrame -> bufPipe) or composed of
immutable, independently-allocated Go strings (Header maps).

While here, defensively clear GoAwayFrame.debugData after copying
it to cc.goAwayDebug in processGoAway. GoAwayFrame is not in
frameCache today so the retained cc.goAway pointer is safe, but
this 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.

Verification:

  net/http/internal/http2: go test -race -count=30   PASS  (8m13s)
  net/http/internal/http2: go test -race -count=10 -cpu=1,2,4,8
                                                    PASS  (6m17s)
  net/http:                go test -race -count=5    PASS  (2m15s)
  TestFrameReuseRaceCorrect  -race -count=200        PASS  (5s)
  TestFrameReuseRaceAdversarial under
    H2_REUSE_RACE_NEGATIVE=1 -race -count=10         RACE  (10/10)
  TestFrameReuseEndToEndStress -race                 PASS
  GODEBUG=http2reuseframes=0 -race
    (TestFrameReuseEndToEndStress, TestFrameReuseRaceCorrect)
                                                    PASS

The adversarial test deliberately violates the reuse contract and
asserts the race detector fires; the other runs validate the
production code paths both with reuse on (the default) and with
reuse disabled via GODEBUG.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Change-Id: I9d6d0c2e761b0901314c25f362c99062260b31a7

Author: ChrisLundquist

doc/godebug.md

@@ -188,6 +188,14 @@ Setting `x509sslcertoverrideplatform=0` disables this behavior in favor of using
 the platform certificate store instead of honoring the environment variables. We
 plan to remove this setting in Go 1.31.
 
+Go 1.27 added a new `http2reuseframes` setting that controls whether the
+net/http HTTP/2 server and Transport opt in to `Framer.SetReuseFrames`,
+which reuses parsed `*DataFrame`, `*WindowUpdateFrame`, `*HeadersFrame`,
+and `*MetaHeadersFrame` structs across `ReadFrame` calls to reduce
+per-frame heap allocation. The default is reuse on. Setting
+`http2reuseframes=0` reverts to allocating each parsed frame fresh,
+matching the pre-Go 1.27 behavior.
+
 ### Go 1.26
 
 Go 1.26 added a new `httpcookiemaxnum` setting that controls the maximum number

src/internal/godebugs/table.go

@@ -42,6 +42,7 @@ var All = []Info{
 	{Name: "htmlmetacontenturlescape", Package: "html/template"},
 	{Name: "http2client", Package: "net/http"},
 	{Name: "http2debug", Package: "net/http", Opaque: true},
+	{Name: "http2reuseframes", Package: "net/http"},
 	{Name: "http2server", Package: "net/http"},
 	{Name: "httpcookiemaxnum", Package: "net/http", Changed: 24, Old: "0"},
 	{Name: "httplaxcontentlength", Package: "net/http", Changed: 22, Old: "1"},

src/net/http/internal/http2/frame.go

@@ -9,6 +9,7 @@ import (
 	"encoding/binary"
 	"errors"
 	"fmt"
+	"internal/godebug"
 	"io"
 	"log"
 	"slices"
@@ -22,6 +23,12 @@ import (
 	"golang.org/x/net/http/httpguts"
 )
 
+// http2reuseframes controls whether the per-connection Framer in the
+// stdlib server and Transport opts in to SetReuseFrames. Default is
+// reuse on; GODEBUG=http2reuseframes=0 reverts to allocating each
+// parsed frame fresh, matching the pre-CL behavior.
+var http2reuseframes = godebug.New("http2reuseframes")
+
 const frameHeaderLen = 9
 
 var padZeros = make([]byte, 255) // zeros for padding

src/net/http/internal/http2/server.go

@@ -322,6 +322,11 @@ func (s *Server) serveConn(c net.Conn, opts *ServeConnOpts, newf func(*serverCon
 	fr.ReadMetaHeaders = hpack.NewDecoder(uint32(conf.MaxDecoderHeaderTableSize), nil)
 	fr.MaxHeaderListSize = sc.maxHeaderListSize()
 	fr.SetMaxReadFrameSize(uint32(conf.MaxReadFrameSize))
+	if http2reuseframes.Value() == "0" {
+		http2reuseframes.IncNonDefault()
+	} else {
+		fr.SetReuseFrames()
+	}
 	sc.framer = fr
 
 	if tc, ok := c.(connectionStater); ok {

src/net/http/internal/http2/transport.go

@@ -662,6 +662,11 @@ func (t *Transport) newClientConn(c net.Conn, singleUse bool, internalStateHook
 	maxHeaderTableSize := uint32(conf.MaxDecoderHeaderTableSize)
 	cc.fr.ReadMetaHeaders = hpack.NewDecoder(maxHeaderTableSize, nil)
 	cc.fr.MaxHeaderListSize = t.maxHeaderListSize()
+	if http2reuseframes.Value() == "0" {
+		http2reuseframes.IncNonDefault()
+	} else {
+		cc.fr.SetReuseFrames()
+	}
 
 	cc.henc = hpack.NewEncoder(&cc.hbuf)
 	cc.henc.SetMaxDynamicTableSizeLimit(uint32(conf.MaxEncoderHeaderTableSize))
@@ -2626,6 +2631,13 @@ func (rl *clientConnReadLoop) processGoAway(f *GoAwayFrame) error {
 	if cc.goAwayDebug == "" {
 		cc.goAwayDebug = string(f.DebugData())
 	}
+	// debugData aliases the Framer's read buffer. SetReuseFrames does
+	// not cache GoAwayFrame today, so cc.goAway = f is safe, but we
+	// retain the *GoAwayFrame across ReadFrame calls; clear the only
+	// field that aliases the read buffer so a future addition of
+	// GoAwayFrame to frameCache cannot turn cc.goAway.DebugData() into
+	// a use-after-overwrite.
+	f.debugData = nil
 	if old != nil && old.ErrCode != ErrCodeNo {
 		cc.goAway.ErrCode = old.ErrCode
 	}

src/runtime/metrics/doc.go

@@ -311,6 +311,11 @@ Below is the full list of supported metrics, ordered lexicographically.
 		The number of non-default behaviors executed by the net/http
 		package due to a non-default GODEBUG=http2client=... setting.
 
+	/godebug/non-default-behavior/http2reuseframes:events
+		The number of non-default behaviors executed by the net/http
+		package due to a non-default GODEBUG=http2reuseframes=...
+		setting.
+
 	/godebug/non-default-behavior/http2server:events
 		The number of non-default behaviors executed by the net/http
 		package due to a non-default GODEBUG=http2server=... setting.