This document records the boundaries of the HTTP/2 implementation in the Go
http package: how it currently behaves in ways users need to know about,
what was deliberately left out, and where it can be improved. For usage, see
the HTTP/2 section of the Go guide (Chinese).
The implementation lives in http (h2_*.go) and the
hpack package. It is written from scratch and does not depend on
golang.org/x/net.
| Side | Features |
|---|---|
| Server | TLS + ALPN (h2), cleartext with prior knowledge (h2c), HTTP/1.1 Upgrade: h2c; multiplexing, flow control in both directions, HPACK (Huffman and dynamic table), CONTINUATION, trailers, server push, 1xx interim responses, automatic 100 Continue, graceful GOAWAY on Response.Close, Request.TLS, extended CONNECT (RFC 8441) switched to a tunnel with Context.Upgrade, which is how websocket.ServerHandler.Upgrade serves WebSocket over HTTP/2; RFC 9218 urgency weights for response scheduling |
| Client | h2 over https through ALPN, cleartext prior knowledge with UnencryptedHTTP2; multiplexing on one connection, honouring the server's MAX_CONCURRENT_STREAMS, cancellation that resets only its own stream, automatic retry after GOAWAY / REFUSED_STREAM; new streams on the least-loaded connection; Expect: 100-continue waits for the 100; optional PING health check and SETTINGS acknowledgement timeout |
| Conformance | h2spec: 145 of 145 cases, over h2c and TLS |
| Interop | Go net/http client and server (TLS and h2c); curl (nghttp2) over h2, h2c and Upgrade |
The suite that checks all of this runs in CI; see Conformance testing below.
A client that resumes a TLS 1.3 session can send its first request frames with
its first flight, before the handshake is over (RFC 8446 section 2.3). Setting
Config.EarlyData turns that on for the HTTP/2 server (and for the
tls.Handler it is wrapped in, through tls.EarlyDataOptIn): a stream whose
HEADERS arrived that way carries Early-Data: 1 (RFC 8470), and only a GET,
HEAD, OPTIONS or TRACE method is served from it. Any other method is answered
425 Too Early on that stream alone, its connection and the other streams
carrying on, as HTTP/3 does; Config.EarlyDataUnsafe serves every method and
leaves the check to the handler. The TLS layer accepts a ticket's early data
once and bounds it to tls.Handler.MaxEarlyData, so a replay is turned away
before it reaches the server. It needs the handshake that runs without a
worker: with tls.Handler.Blocking, crypto/tls does it and takes none. The
client does not send HTTP/2 early data: the framing depends on the protocol
ALPN picks, which it learns only when the handshake is over.
Behaviour to be aware of when using it.
- A request body is read completely into memory before the handler runs,
unless
Config.StreamRequestBodyis set: then the handler runs as soon as the body has begun — at the HEADERS for a body with acontent-lengthpastStreamRequestBodyThreshold, and once more than the threshold of it has arrived for one without — and takes the body fromRequest.Body, a*BodyStreamread without waiting, or throughContext.OnBody, exactly as on HTTP/1 (seehttp1.md). The stream's receive window is then given back only as the handler consumes the body, so a client uploading faster than the handler takes it is paced by HTTP/2 flow control, one window (HTTP2Config.StreamWindow, 1MB by default) at most ahead, while the connection's other streams carry on.MaxStreamedBodyBytesbounds such a body in place ofMaxBodyBytes, andExpect: 100-continueis answered only once the handler asks for the body. - A response given to
WriteResponseorRespondis given all at once asResponse.Body []byte. The client buffers the whole response body before its callback. The stream keeps the slice until it is finished, until the client's windows let it go, so the handler must not change it;RespondCopyandWriteResponseCopyare the calls that copy it. A body that is the request's own buffer, asContext.Body()is, is copied by the server instead, since that buffer goes back to the pool once the handler returns, exactly as HTTP/1's send copies one; every other body, including the copyRespondCopymakes, is kept as given rather than copied again. A pooled body (the*Copycalls' copy, or one given toWriteResponseOwned) goes back to the pool once it is framed, unless the windows keep a tail of it back, which is left to the collector. - A handler may instead write its response through
Context'shttp.ResponseWritermethods (Header/WriteHeader/Write/Flush), trailers included, and handContexttohttp.ServeFileorhttp.ServeContent. A response no longer than 4KB (or with aContent-Lengthof at most 64KB) that is not flushed is still sent whole when the handler returns, with itscontent-length. A longer or flushed one streams, as on HTTP/1: HEADERS that leave the stream open, DATA frames as it is written and as the client's windows let them go, and END_STREAM or the trailers' HEADERS once the handler is done. So server-sent events, long polling and large downloads work over HTTP/2. - A handler that writes faster than the client reads waits in
Writeonce 64KB of its body is held back by flow control, until the client has taken some or the stream ends, so that memory stays bounded. It waits on the handler pool, which grows for blocked handlers; a handler the connection runs on its own reader (seeStreamPoolbelow) never waits, since that goroutine reads the WINDOW_UPDATE that would end the wait, and its body is held until the client's windows let it go. A body shorter than theContent-Lengththe handler set resets the stream rather than ending it. - Package
grpcserves gRPC, streaming included, through this (Server.ServeHTTP), besides its own HTTP/2 transport. - Memory bound: on the server, a body over
MaxBodyBytesgets 413, and one connection holds at mostHTTP2.MaxBufferedBodyBytes(4 ×MaxBodyBytes, 64MB by default) of the bodies it reads whole; a stream whose DATA would go past it is reset withREFUSED_STREAM. A streamed body costs a stream window. On the client, one response is bounded byMaxResponseBodyBytes. A whole response is kept as the handler's body, with only the frames the windows admit queued, so a stalled reader costs about one stream window rather than the body; see Load testing. - A
CONNECTrequest that names no:protocol(RFC 9113 section 8.5) is switched to a tunnel on its stream withContext.Connect;fibhttp.ConnectProxyserves CONNECT this way over HTTP/1.x, HTTP/2 and HTTP/3.
- A connection's frames are processed in order, and a request that is complete
goes to the engine's handler pool (
fib.Engine.HandlerPool), asConfig.StreamPooldescribes, so the requests one client has open on a connection are served concurrently and a handler that blocks holds up only itself. - The engine's workers read and frame the connections, with
IOPollersor without, and the handler pool is one of its own for each engineConfig.Name, called<Name>-streams(fib-streamsby default), shared by every HTTP/2 and HTTP/3 server whose connections come from engines of that name and never by an engine: an engine worker submits each request it frames, and were the queue it submits to its own, every worker could end up waiting for room that none is left to make. Its ceiling is twice the widest engine pool of that name running, orfib.DefaultStreamPoolSizingwhile none is, and its floor is zero, so an idle one keeps no worker. It stops once the last engine of its name closes, without waiting for handlers still running. StreamPool.MaxConcurrentHandlersbounds how many of one connection's requests are served at once. The last of the N runs on the goroutine reading the connection, which reads nothing further until it returns, so the limit is paid for by the peer's flow control rather than by a queue of requests on the server. 1, likeStreamPool.Disable, serves every request on the reader, one at a time, which is how the server behaved before the pool existed (application-level head-of-line blocking).Pushruns the handler of the pushed request synchronously, on the goroutine that called it, and returns only when it does, so a slow pushed handler delays the parent response.- Responses are queued and written by a flush the first of them sends to the
handler pool, behind the requests already handed to it, so a burst of
responses leaves in one write rather than one each, and none waits for a
slow handler's. Over TLS the burst is also sealed as one record, up to
16 KB, rather than a record a frame: the TLS layer holds what is sent while
the connection is corked and seals it when the flush uncorks it
(
fib.CorkHolder). That took a fixed response over h2 on 7 CPUs from 1.64M to 3.52M requests a second, against 3.82M over h2c. - A stream, with the
*http.Request,Header,URLand*Contextit holds, is recycled once its response is finished and its handler has returned and released everyRetain, underConfig.ReuseRequestsand its siblings, which are on by default, as an HTTP/1 request's objects are: a handler must not keep them past that (see the HTTP/1 notes). Streams whose body streams and extended CONNECT tunnels are not recycled: their body callbacks can outlive the response, which a recycled stream cannot carry. A pushed stream is recycled too, itsRequest,URLandContextwith it. On 64 CPUs these took HttpArena's baseline-h2c from 3.9M requests a second to 18.5M.
- Do not call
Context.Conn.Sendor similar on an HTTP/2 connection: raw bytes break the framing. All output must go throughContext.
Config.HTTP2 sets what a server's connections let their clients send, and
ClientConfig.HTTP2 the same for a client's connections. Both are
http.HTTP2Config, whose zero value is the defaults in the table below.
| Field | Default | What it sets |
|---|---|---|
StreamWindow |
1MB | SETTINGS_INITIAL_WINDOW_SIZE: the receive window each stream is granted, given back after half is consumed. A streamed body is bounded by it; raising it lets one stream move more per round trip. Kept between 65535 and 2^31-1. |
ConnWindow |
16MB | The connection's receive window, shared by its streams, given back after half is consumed. Kept between 65535 and 2^31-1. |
MaxFrameSize |
16384 | The advertised SETTINGS_MAX_FRAME_SIZE: the largest frame payload the peer may send. A larger one lets a body arrive in fewer frames, for as much more memory per read. Kept between 16384 and 2^24-1. What this side sends is still framed to what the peer allows. |
HeaderTableSize |
4096 | The HPACK dynamic table each direction may use: the size this side advertises in SETTINGS_HEADER_TABLE_SIZE and the most its encoder uses when the peer allows that much. Negative turns the table off. The encoder caps it at hpack.MaxEncoderTableSize (1MB). |
AdaptiveWindow |
off | Grow the windows to the connection's bandwidth-delay product, as gRPC does, by measuring DATA between a PING and its acknowledgement and doubling a window that the peer fills within a round trip. The PINGs are at least 25ms apart, the windows never shrink, and the stream window is bounded by MaxAdaptiveWindow. |
MaxAdaptiveWindow |
16MB | The bound on the stream window AdaptiveWindow grows. |
InitialMaxStreams |
100 | How many streams a client opens on a new connection before the server's SETTINGS_MAX_CONCURRENT_STREAMS arrives. Ignored by a server. |
MaxBufferedBodyBytes |
4 × MaxBodyBytes (64MB) |
What one connection may hold of the request bodies it collects whole before their handlers run, together with what its tunnels hold for handlers not ready for it. A stream whose DATA would go past it is reset with REFUSED_STREAM (a tunnel with ENHANCE_YOUR_CALM); a body's last frame always passes. Never below MaxBodyBytes; negative turns it off. Ignored by a client. |
config := fibhttp.DefaultConfig()
config.HTTP2 = fibhttp.HTTP2Config{
StreamWindow: 4 << 20, // a long, high-latency download moves 4MB per round trip
ConnWindow: 32 << 20,
MaxFrameSize: 32 << 10, // fewer frames per body, more memory per read
HeaderTableSize: 16 << 10, // more of a repeated header kept per connection
AdaptiveWindow: true, // or let the connection measure its own path
}
server, err := fib.New(fibConfig, fib.Binding{Addr: ":443", Handler: fibhttp.NewHandlerWithConfig(config, handler)})A client sets the same fields in fibhttp.ClientConfig.HTTP2, which describe
what its server may send to it. The windows are the flow control that a
streamed body is bounded by, the frame size what a peer may send at once, and
the table what either side's HPACK encoder may keep between header blocks.
- Priority: PRIORITY frames and the priority fields in HEADERS are
validated and ignored, and the priority tree of RFC 7540 is not implemented:
RFC 9113 deprecates it. A request's RFC 9218
priorityheader is honoured instead: its urgency (u, 0 to 7, 3 by default) sets how many frames the response may send when its turn at the connection's window comes, 8 for urgency 0, 4 for urgency 1, 2 for urgency 2, and the single frame a turn every stream gets for the default urgency 3 and every less urgent one, so a client that sends no priority, or the default urgency, sees the round robin unchanged. The incremental hint (i) is ignored, and PRIORITY_UPDATE is not implemented. The turns stay in the order the streams began to wait, and no stream is starved: every waiting stream gets its turn, and one the connection's window cuts short keeps its place, and the frames left of its turn, until more of the window comes. A stream its own window holds back gives its turn up, and a stream with nothing ahead of it sends at once. - The peer's
SETTINGS_MAX_HEADER_LIST_SIZE: both sides keep within the limit the peer announces. A response header or trailer that would not fit resets its stream rather than going out, an interim response or a pushed request's header that would not fit is left out, and the client fails a request whose header is too large before it opens a stream, and resets one whose streamed body's trailer turns out to be. - Engine shutdown:
Engine.Shutdownsends GOAWAY and closes each connection once its streams have finished.Engine.Stopon its own leaves connections open, andEngine.Closewrites GOAWAY on each HTTP/2 connection before it cuts it, in one non-blocking write: the peer learns that the server is going where the socket can take the frame, while a connection already backed up with output may still be cut with it queued.Engine.Shutdownremains the graceful path. - TCP RST on close: a connection the server retires itself (idle, a
response's
Close, a shutdown, a peer's GOAWAY or a connection error) half-closes after its GOAWAY and drains what the client is still sending, forlingerTimeout(500ms) at most, so the client reads the GOAWAY rather than a reset. A connectionEngine.Closecuts does not linger, and one with unread input may still be reset. - Idle and keep-alive: the server retires a connection that has carried
no stream for
Config.IdleTimeout(ReadTimeoutwhen it is not set; 2 minutes inDefaultConfig), or for what a handler set withContext.SetIdleTimeout, with GOAWAYNO_ERROR. WithConfig.PingIntervalit also pings a connection that has sent nothing for an interval, and closes one that answers nothing withinConfig.PingTimeout; the default sends no PING. The client's PING health check is described under Client. - SETTINGS acknowledgement timeout: the server ends a connection with
GOAWAY(SETTINGS_TIMEOUT) when the client has not acknowledged its SETTINGS
within
Config.SettingsTimeout(10 seconds by default). The client times a server out the same way, withClientConfig.SettingsTimeout: a server that has not acknowledged the client's SETTINGS by then has its connection closed, and the requests on it fail withErrSettingsTimeout, or go again on another connection by the retry rule below.
- Until the first connection to an https host has revealed its protocol, only
one connection to it is dialed at a time (as in
net/http), so the first burst of requests to an HTTP/1.1-only https server waits one extra TLS handshake. - Among several HTTP/2 connections to a host, a new stream goes to the one
with the most streams to spare, by each connection's own
MAX_CONCURRENT_STREAMS, so the load spreads over them rather than piling onto the first; a tie goes to the earlier one. A second connection is only dialed once every one is full, and once there are several they all stay in use while requests keep them busy, closing once the host goes quiet forIdleConnTimeout. - Health check: with
ClientConfig.ReadIdleTimeoutset, a connection that has heard nothing from the server for that long sends it a PING, and one that then hears nothing at all, acknowledgement or other frame, forPingTimeout(15 seconds by default) is taken for dead and closed. Its requests fail withErrPingTimeout, or go again on another connection by the rule below. Names and defaults are x/net/http2's;ReadIdleTimeout's zero, the default, leaves the check off. - SETTINGS timeout: with
ClientConfig.SettingsTimeout(10 seconds by default; below zero, no limit) a connection whose server does not acknowledge the client's SETTINGS in time is taken for wedged and closed, and its requests fail withErrSettingsTimeout, or go again on another connection by the retry rule below. This finds a server that has stopped processing what it reads, which the PING health check cannot: that one only looks at a connection that went quiet, and this server's socket may still take what is written to it. - Retries: a request whose connection breaks after any of its response
has arrived fails with the connection's error and is not sent again,
whatever its method. This is deliberate, and what
net/httpand x/net/http2 do: the server has begun to answer, so it has acted on the request, and repeating a POST would act twice; even for an idempotent method, the callback of a streaming response may already have passed part of the body on, which a second response cannot be stitched to, and the second response may differ. A request that received nothing goes again, once, on another connection when its method is idempotent (GET, HEAD, OPTIONS, TRACE) and its body can be read again (GetBody, for one that streams); one that GOAWAY or REFUSED_STREAM marks unprocessed goes again whatever its method, since the server says it did nothing with it. A caller that knows a request is safe to repeat after a partial answer can send it again itself. Expect: 100-continue: a request with a body and this header sends its HEADERS alone and its DATA once the server answers 100, or onceClientConfig.ExpectContinueTimeout(1 second inDefaultClientConfig; zero sends the body at once) has passed. A final response that comes first is the answer: the body is never sent, and the stream is reset once the response is complete. HTTP/1 and HTTP/3 requests do the same.- Cleartext HTTP/2 is prior knowledge only; the client does not upgrade from
HTTP/1.1 with
Upgrade: h2c.
The complete list, including the HTTP/1, HTTP/3, engine and test-infrastructure items, is in the roadmap, with the reason, the rough cost and when each is worth reconsidering.
| Feature | Reason |
|---|---|
| Receiving server push in the client | Chrome and Firefox have removed push, and Go's net/http client never supported it. The client sends ENABLE_PUSH=0; the server's push support remains for clients that still want it. For preloading, 103 Early Hints (Context.WriteInterim) is the recommended replacement. |
| RFC 9218's incremental hint and PRIORITY_UPDATE | The priority header's urgency is used for send scheduling (see Protocol details); the incremental hint i is ignored, and the update frame is not implemented. The RFC 7540 priority tree is deprecated by RFC 9113 and is not implemented either. |
Upgrade: h2c initiated by the client |
RFC 9113 deprecates this upgrade; cleartext HTTP/2 uses prior knowledge (UnencryptedHTTP2). The server still accepts the upgrade for compatibility with curl and others. |
Upgrade: h2c over TLS |
The RFCs allow switching protocols over TLS only through ALPN. |
| 1xx interim responses to HTTP/1.0 requests | HTTP/1.0 clients do not understand 1xx; WriteInterim returns http.ErrNotSupported. |
| Pushing from a pushed request | The protocol only allows PUSH_PROMISE on client-initiated streams. |
http/http2_conformance_test.go holds the suite, every test named
TestHTTP2Conformance…, and CI runs it on Linux, macOS and Windows in the
HTTP/2 conformance job. The peers are the standard library and tools the
runners already have or install as tools, so the module itself gains no
dependency:
| Peer | What it checks |
|---|---|
h2spec v2.2.1, installed with go install as staticcheck is |
The server against RFC 9113 and RFC 7541 case by case: framing, stream states, flow control, HPACK and error codes. 145 of 145 cases pass over h2c and over TLS |
net/http's HTTP/2 client and server |
Methods, bodies past the flow-control windows, HEAD, bodiless statuses, trailers both ways, 1xx, 100-continue, multiplexing 50 requests on one connection |
| curl (nghttp2) | The three ways a client starts HTTP/2: prior knowledge, Upgrade: h2c, and ALPN over TLS |
| A raw frame server in the test | What the client does that no ordinary server would show: its preface and settings, REFUSED_STREAM and GOAWAY retries, RST_STREAM, flow control against a small window (the raw server rejects a single byte past what it granted), the server's concurrency limit, CONTINUATION, PING, trailers, and a server that pushes although push is disabled |
| A raw frame client in the test | Stream states, server push, h2c upgrade, graceful GOAWAY, and the HTTP/2-only mode |
h2spec is run against a server with Config.HTTP2Only set, since it speaks
nothing but HTTP/2: a sniffing server would answer its deliberately invalid
preface with an HTTP/1 response, which h2spec cannot read.
go test ./http -run '^$' -bench '^BenchmarkH2Server' -benchmem -count 5
drives one connection with 100 requests in flight, each answered as it ends
with a new one, as h2load does. One op is one request; client and server
share the process, so compare runs with each other rather than with a load
generator's numbers. The host is a shared 16-thread Ryzen 7 7800X3D, whose
load moved ns/op by a few percent between runs; the allocation counts are
exact, and only the two changes below moved time outside that noise. The
hpack package has its own encode and decode benchmarks.
| Benchmark | ns/op | B/op | allocs/op |
|---|---|---|---|
| GET | 2230 | 10 | 0 |
| POST | 3136 | 145 | 2 |
| Static 1KB | 2480 | 9 | 0 |
| Static 16KB | 5630 | 28 | 0 |
| Static 64KB | 15503 | 126 | 0 |
| Static TLS 1KB | 3026 | 12 | 0 |
| Static TLS 16KB | 9191 | 53 | 1 |
| Static TLS 64KB | 22612 | 131 | 1 |
| Streamed POST | 5976 | 6425 | 13 |
| Push | 5032 | 233 | 4 |
Pushed-stream recycling took Push from 8 allocations and 1954 bytes a
request to 4 and 233, and its time from 5364 to 5032 ns/op (medians of four
interleaved runs against main). The one-frame send path
took POST from 3452 to 3226 ns/op and static 16KB from 5833 to 5519 in an
A/B of the branch with and without it (medians of three interleaved pairs);
the 64KB bodies, which take several frames, did not move outside noise, and
neither did TLS, where the layer seals what it is handed into one record
anyway. A profiler run over these shows the send path waiting on the socket
(syscalls, and AES-GCM over TLS) far more than it copies: memmove was 2.5% of
the samples, which is why the copy removed below is worth a few percent.
The client and the test harness account for most of the remaining
allocations (the task pool's ring, timers, and the benchmark's own reads).
BenchmarkH2ServerLarge answers with whole bodies of 64KB to 4MB, over h2c
and TLS, and reports their bytes a second. Profiled on Linux (Docker, 14
arm64 CPUs), the multi-frame h2c path spent a quarter of its samples in
memmove: half framing the body, half copying the frames into the
connection's queue. Sending the body beside its frames instead (medians of
10 runs, before and after):
| Benchmark | before | after |
|---|---|---|
| Large h2c 64KB | 7.55 µs | 4.99 µs (-34%) |
| Large h2c 256KB | 28.4 µs | 19.2 µs (-32%) |
| Large h2c 1MB | 112.5 µs | 60.6 µs (-46%) |
| Large h2c 4MB | 430 µs | 252 µs (-42%) |
| Static 64KB | 7.74 µs | 5.85 µs (-24%) |
| Large TLS 64KB-4MB | within ±3%, unchanged path |
Static 1KB and 16KB, which take the one-frame path, did not move outside
noise. End to end, h2load (8 connections x 16 streams, 4 threads, pinned
apart from the server) against benchmark/loadtest's /big in the same
container, three interleaved 10-second pairs per case, the h2c request rate
rose with every pair: medians 65,801 to 84,401 a second at 64KB (a noisy
case), 80,444 to 85,123 at 256KB, 21,523 to 25,476 at 1MB and 5,210 to 6,814
at 4MB. Over TLS the rates stayed within the noise of each other.
benchmark/loadtest drives the server for 30 seconds at a time with 512
streams over four connections and with 512 streams over 64 connections, and
runs a slow and a stalled subset beside the fast load. Medians of three
interleaved rounds: h2c 1,199,024 requests a second at 4 x 128 and 2,836,822
at 64 x 8; HTTP/2 over TLS 1,092,137 and 2,404,461; no request failed, errored
or timed out. HTTP/2 scales with connection count, and a stalled reader costs
it about one stream window rather than the response body. The method, the
HTTP/3 comparison and the memory cost of the whole-body paths are in
Load testing.
In order of priority.
Done. Besides MaxConcurrentStreams, MaxHeaderBytes, MaxBodyBytes and the
flow-control windows, the server ends a connection with
GOAWAY(ENHANCE_YOUR_CALM) when its client:
- resets streams while they are open, or makes the server reset them with
stream errors, past a burst of 1000 refilled at 100 a second (Rapid Reset,
CVE-2023-44487), which
Config.StreamResetBurstandStreamResetRateset; - sends PING, SETTINGS (after the first), or DATA and CONTINUATION frames that
are empty without ending anything, past a budget of the same size, which
bounds the acknowledgements the server queues too, and which
Config.ControlFrameBurstandControlFrameRateset; - sends one header block in more than 1000 CONTINUATION frames
(
Config.MaxContinuationFrames), or takes longer thanReadHeaderTimeout(ReadTimeoutwhen it is not set) to finish one.
PRIORITY frames, and WINDOW_UPDATE or RST_STREAM frames for a stream that has
ended, cost no more than their bytes and are not counted, since a client may
send them in flight. Each limit left at zero takes the default above
(DefaultStreamResetBurst and the like), and one set below zero is lifted. A
gRPC client cancels a call by resetting its stream, and deadlines or hedged
calls cancel many at once, so a server or proxy in front of busy gRPC clients
may need a higher reset rate than the default.
The client holds a server to the same control-frame budget and CONTINUATION
bound, with the defaults: a server that floods it with PING or SETTINGS
frames, each of which the client acknowledges, or with empty DATA or
CONTINUATION frames, has its connection ended with GOAWAY(ENHANCE_YOUR_CALM),
and the requests on it fail with that *H2ConnError. A server resetting the
client's streams costs the client nothing, so it has no reset budget.
Done: see Conformance testing. Parsing HTTP/1
requests, reading HTTP/2 frames and coding HPACK all have fuzz targets
(http/fuzz_test.go and hpack/fuzz_test.go), which the
Fuzz the parsers CI job runs for 20 seconds each. The load-oriented check
is done as well: the campaign in Load testing drove h2load and
fib's HTTP/3 client for 30 seconds per configuration, over a billion requests
in all, without a failed request, a reset storm or a GOAWAY. What it did
expose is the memory cost of a whole response to a stalled reader, on HTTP/1
and HTTP/3 more than on HTTP/2. A longer soak and a lossy network path are
still open.
- Streamed request bodies are done, with window updates that follow the
handler's consumption, and so are streamed responses, paced by the
client's windows; a body read whole still has its window replenished on
receipt. The client streams a response body to its callback under
ClientConfig.StreamResponseBody, and buffers it whole otherwise. - Bidirectional streaming is done:
Context.ServeDuplexruns aDuplexHandleron a goroutine of its own, withDuplex.Readwaiting for the request body whileDuplex.WriteandDuplex.Flushwrite the response, so a handler can drive both directions at once. It works the same on HTTP/3, and over HTTP/1.1 as described in the guide; the request body streams underConfig.StreamRequestBody, and at most 1 MiB of it is held for a handler that falls behind.
- HPACK Huffman decoding is done: it takes four bits a step from a table.
- HPACK encoder dynamic-table index is done: past 16 entries it finds a
field through a hash index of names and name-value pairs instead of
searching the table, and the table grows to what
HeaderTableSizeand the peer allow. - Benchmarks are done:
http/h2_benchmark_test.godrives one connection with 100 requests in flight, as h2load does, over h2c and TLS, for GET, POST, static bodies of 1KB, 16KB and 64KB, whole bodies of 64KB to 4MB, streamed uploads and server push;hpackhas encode and decode benchmarks. See Benchmarks above. - Pushed streams are done: a pushed stream and the
Request,URLandContextit holds come from the same recycling as a client's stream's. A stream whose body streams still allocates, since its callbacks can outlive the response. - Copies on the send path are done over h2c: a whole response's body
larger than 4KB is not copied at all. The connection keeps it as the
handler gave it, as HTTP/1 keeps a large body, and writes each DATA
frame's header and payload as separate parts of one
writev; a body that fits one frame goes beside its frames the same way. See Benchmarks for what it gained. A body that is the request's own buffer, a*Copycall's pooled copy, and a response that streams throughResponseWriterare still copied into their frames, since their bytes do not outlive the call. Over TLS the body is still copied into the frames and then sealed: the layer seals each send into records of its own, so a frame header and its payload handed over apart would cost a second record per frame, and AES-GCM, not the copy, is what that path spends its time on.
- Done: the client sends request trailers, both for a body sent whole and for
one that streams (
Request.Trailer, the values as they stand when the body has been read), and the server hands them to the handler inRequest.Trailer, as for a chunked HTTP/1 request. See Client.