HTTP/1.1 → 2 → 3

The 30-second version

That's the key to this whole page. A GET /users/7 that returns 200 OK with some JSONJSONJavaScript Object Notation: a text format for data — {"id": 7, "tags": ["a"]}. Readable by humans and every language; the default body format for web APIs. is the same request in all three versions. Your handler codeHTTP handlerThe code that answers one HTTP request. In Go it's anything with a ServeHTTP(w, r) method (the http.Handler interface): r is the incoming request, w is where you write the response. doesn't change. What changes is the plumbing underneath — and the plumbing decides how fast a page with 80 files loads on a train with bad signal.

Here are the three versions loading the same four files. Each row is one network connection; the colored blocks are files arriving.

What each version fixed

The map of this page

1. §02–§03: what an HTTP message actually looks like, and a tiny server and client in Go and Node — with the timeoutsTimeoutA limit on how long to wait for something (a connection, a response) before giving up with an error, so a slow or dead peer can't hang your program forever. almost everyone forgets.
2. §04–§07: the story of 1.1 → 2 → 3, each with an animation you can poke at.
3. §08: caching and retries — the parts of HTTP that save you the most traffic.
4. §09–§11: using HTTP/2 and HTTP/3 from Go and Node, then the production knobs: connection pools, timeouts, proxies.
5. §12–§14: pitfalls, a quiz, and a cheat sheet.

What an HTTP message looks like

Where the message travels

Before any HTTP is sent, the clientClient / serverThe client is the program that starts a conversation and asks for something (your browser, your Go program calling an API); the server is the program that waits for requests and answers them. opens a TCPTCPTransmission Control Protocol: delivers a stream of bytes between two programs reliably and in order, resending anything lost. HTTP/1.1, HTTP/2 and most databases run on it. connection to the server: think of it as a phone line that carries bytes reliably and in order between two programs. The server is found by its IP addressIP addressThe number that identifies a machine on a network, like a postal address: 93.184.216.34 (IPv4) or 2606:2800:220:1::248 (IPv6). and a portPortA number from 0 to 65535 that picks which program on a machine should get the traffic — like an apartment number after the street address. HTTPS servers usually listen on port 443. — 80 for plain HTTP, 443 for HTTPSHTTPSHTTP sent through an encrypted TLS connection — the padlock in your browser. Same requests and responses as HTTP, but private and tamper-proof.. HTTP/1.1 then simply writes its text message into that line, and reads the reply back out. (How TCP keeps the line reliable is another page.)

That split is the idea this whole page rests on. HTTP rides on a transportTransport (protocol)The layer under HTTP that actually moves bytes between two machines: TCP for HTTP/1.1 and HTTP/2, QUIC for HTTP/3. The transport gets the bytes there; HTTP decides what they mean. — TCP, or QUIC in HTTP/3. The transport moves bytes; HTTP gives them meaning. Watch one request travel down the layers, across the network as packetsPacketOne small chunk of data sent across a network on its own, with a header saying where it's from and where it's going. Big messages are split into many packets., and back up — then flip to HTTP/3 and see that only the plumbing changes:

A real exchange, captured with curl

curlcurlA command-line HTTP client. curl -v prints the exact request and response headers; curl -I fetches headers only; --http2 / --http3 pick a version. is a command-line HTTP client. With -v ("verbose") it prints everything it sends (lines starting >) and receives (<). This is real output from the tiny Go server that §03 builds (the ← notes are added):

$ curl -v "http://localhost:8080/hello?name=ada"
*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080
> GET /hello?name=ada HTTP/1.1          ← request line: method, path, version
> Host: localhost:8080                   ← headers, one per line
> User-Agent: curl/8.5.0
> Accept: */*
>                                        ← empty line: "headers are done"
< HTTP/1.1 200 OK                        ← status line: version, code, reason
< Content-Type: text/plain; charset=utf-8
< Date: Fri, 30 Oct 2026 10:32:14 GMT
< Content-Length: 26                     ← the body is exactly 26 bytes
<
hi ada, you sent HTTP/1.1                ← the body
* Connection #0 to host localhost left intact

The parts, in order:

• Request lineRequest lineThe first line of an HTTP/1.1 request: method, path and version, e.g. GET /users/7 HTTP/1.1. — GET /hello?name=ada HTTP/1.1. The methodHTTP methodThe verb at the start of an HTTP request saying what you want to do: GET (read), POST (create/submit), PUT/PATCH (update), DELETE (remove). (what to do), the path (which thing; the ?name=ada part is the query string), and the protocol version.
• HeadersHTTP headerA Name: value line sent before the body of an HTTP request or response, carrying metadata — Content-Type: application/json, Authorization: Bearer …, Cache-Control: max-age=60. — metadata. Host says which website you want (one server can host many); Accept says what formats you'd like back.
• An empty line. Strictly, every line ends with two invisible characters, carriage return + line feed (written \r\n, or "CRLF"). An empty line is just \r\n on its own.
• Status lineStatus lineThe first line of an HTTP/1.1 response: version, status code and a short reason, e.g. HTTP/1.1 404 Not Found. — HTTP/1.1 200 OK. The status codeHTTP status codeThe 3-digit number at the start of every HTTP response: 2xx = success (200 OK), 3xx = go elsewhere (301), 4xx = your request was wrong (404 Not Found, 429 Too Many Requests), 5xx = the server failed (500, 503). is the number; "OK" is a human-readable reason that programs ignore.
• Content-LengthContent-LengthA header giving the body's exact size in bytes, so the receiver knows where this message ends and the next one begins. — tells the reader exactly where the body ends, so it knows when the message is complete.

Build one yourself

Change the method and the cookie, and watch both messages change. Click any line to see what it does. Turn on "show invisible characters" to see the \r\n at every line end.

GET /api/users/7 HTTP/1.1
Host: api.example.com
Accept: application/json
(empty line)

HTTP/1.1 200 OK
Cache-Control: max-age=60
Content-Type: application/json
Date: Fri, 30 Oct 2026 10:32:14 GMT
Content-Length: 21
(empty line)
{"id":7,"name":"Ada"}

Typing HTTP by hand

Because HTTP/1.1 is just text, you can talk to a server with ncnc (netcat)A command-line tool that opens a raw TCP connection and sends whatever you type, printing whatever comes back. Perfect for typing HTTP/1.1 by hand., which opens a TCP connection and sends exactly what you give it:

$ printf 'GET /hello?name=nc HTTP/1.1\r\nHost: localhost\r\n\r\n' | nc localhost 8080
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Fri, 30 Oct 2026 10:32:14 GMT
Content-Length: 25

hi nc, you sent HTTP/1.1

printf prints its argument and turns each \r\n into the real two invisible characters. The | ("pipe") feeds that output into nc. Note the two \r\n at the end: one finishes the Host line, the second is the empty line that says "my headers are done". Leave it out and the server waits forever for more headers.

Methods: what you want to do

The last column is about being idempotentIdempotentDoing it twice has the same effect as doing it once. “Set balance to 50” is idempotent; “add 50 to balance” is not — so only the first is safe to retry blindly.: doing it twice has the same effect as doing it once. It matters a lot when a request times out and you're not sure whether it arrived — we'll come back to it in §08.

Status codes: how it went

The first digit is the class; you can usually stop reading there.

HTTP forgets you between requests

HTTP is statelessStateless (HTTP)Each request stands alone: the server doesn't automatically remember anything about your previous request. Anything it needs (who you are, what's in your cart) has to be sent again each time, usually in a cookie or a header.: every request stands alone. The server doesn't remember that the request a second ago came from you. So how does a site keep you logged in? With a cookieCookieA small name=value string a server asks the browser to store (with a Set-Cookie response header). The browser then sends it back on every later request to that site in a Cookie header — that's how a stateless protocol remembers you're logged in.:

# 1. You log in. The response asks the browser to store a cookie:
< HTTP/1.1 200 OK
< Set-Cookie: session=abc123; HttpOnly; Secure; SameSite=Lax

# 2. From now on, the browser attaches it to every request to that site:
> GET /cart HTTP/1.1
> Host: shop.example
> Cookie: session=abc123

The server looks up abc123 in its own storage to find out who you are. The flags matter: HttpOnly hides the cookie from JavaScript on the page (so injected scripts can't steal it), Secure only sends it over HTTPS, and SameSite=Lax stops other sites from making your browser send it in most cross-site requests — e.g. a hidden form on evil.example that posts to your bank, hoping your login cookie rides along.

Your first server and client — with timeouts

A server

Both servers below answer GET /hello?name=ada with hi ada, you sent HTTP/1.1 — the server from the curl capture in §02.

package main

import (
    "fmt"
    "log"
    "net/http"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /hello", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        fmt.Fprintf(w, "hi %s, you sent %s\n", r.URL.Query().Get("name"), r.Proto)
    })

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second, // ← drop clients that send headers too slowly (§11)
    }
    log.Fatal(srv.ListenAndServe())
}

A client

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
    "time"
)

// One client for the whole program — it reuses connections (§10).
var client = &http.Client{Timeout: 5 * time.Second} // ← the whole request must finish in 5 s

func main() {
    resp, err := client.Get("http://localhost:8080/hello?name=ada")
    if err != nil {
        log.Fatal(err) // network failure or timeout — NOT a 404 or 500
    }
    defer resp.Body.Close() // ← always close the body (§12 explains why)

    if resp.StatusCode != http.StatusOK {
        log.Fatalf("unexpected status: %s", resp.Status)
    }
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(string(body))
}

Why the timeout isn't optional

Picture a server that accepts your connection and then never answers — it's overloaded, or stuck, or a network device in between silently dropped the connection. Without a timeout:

• Go: http.DefaultClient (what http.Get uses) has Timeout: 0, which means no limit. The goroutineGoroutineA very lightweight task in Go, started with the go keyword. The Go runtime runs thousands of them on just a few OS threads. making the call waits forever. In a server, every incoming request that calls the stuck service adds one more stuck goroutine, until you run out of memory.
• Node: fetch has internal default limits of 300 seconds to receive the headers, and 300 seconds of silence while reading the body (in Node 18+) — so a body that trickles in slowly can take far longer than that. Five minutes is "forever" to a user, and long enough for thousands of requests to pile up.
• Browsers: fetch has no timeout you can rely on.

With the 5-second limits above, you get a clear error instead. Real output when the server takes too long:

# Go
Get "http://127.0.0.1:35577": context deadline exceeded (Client.Timeout exceeded while awaiting headers)
# Node (err.name | err.message)
TimeoutError | The operation was aborted due to timeout

HTTP/1.1: keep-alive, and the six-connection hack

What a new connection costs

Before the first byte of HTTP can be sent, two handshakesHandshakeA short exchange of messages at the start of a connection where both sides agree it's open and settle the details (versions, keys, starting numbers) before any real data flows. have to happen:

1. TCP: client and server exchange three small messages to agree the connection is open. That costs one RTTRound-trip time (RTT)How long it takes for a message to go from one machine to another and for the reply to come back. Roughly 1 ms inside a data center, 70–150 ms across an ocean. (round-trip time: how long a message takes to get there and the reply to come back). TCP vs UDP shows it step by step.
2. TLS (for HTTPS): they agree on encryption keys and the server proves its identity. With TLS 1.3 that's one more RTT; the older TLS 1.2 needs two. TLS & HTTPS covers it.

Let's put numbers on it. Say your user is far from your server and 1 RTT = 100 ms (a typical cross-continent figure; it's about 1 ms inside a data center). Fetching one file over a fresh HTTPS connection costs 100 ms (TCP) + 100 ms (TLS) + 100 ms (request goes out, response comes back) = 300 ms, before counting the time to actually transfer the bytes.

HTTP/1.0: hang up after every file

In HTTP/1.0, the server closed the connection after each response. A page with 10 files fetched one after another meant 10 × 300 ms = 3 seconds — and two thirds of that is handshakes. HTTP/1.1 made the connection stay open by default (keep-aliveKeep-alive (connection reuse)Leaving a connection open after a request finishes so the next request can reuse it, skipping the cost of a new handshake.), so only the first file pays for the handshakes: 200 ms + 10 × 100 ms = 1.2 s.

A connection stays open until one side decides to close it: either side can send the header Connection: close, and servers close connections that sit idle too long (Node's default is 5 seconds, Go's is unlimited unless you set IdleTimeout).

Knowing where a response ends

Keep-alive creates a new problem. In HTTP/1.0, "the server hung up" meant "the response is complete". With the connection staying open, the client needs another way to know where one response ends and the next begins. Two options:

• Content-Length: 26 — "the body is exactly 26 bytes". Easy, but the server must know the size before sending anything.
• Chunked transfer encodingChunked transfer encodingAn HTTP/1.1 way to send a body whose size isn't known up front: the body goes out in pieces, each prefixed with its size in hex, and a zero-size piece marks the end. — for bodies whose size isn't known yet (a page being generated, a live log). Each piece is sent with its size first, and a zero-size piece means "done". Real bytes from a Node server that wrote part1 and, 100 ms later, part2 (the Date and Connection headers are trimmed; the blank lines are real — every chunk's data is followed by \r\n):

$ printf 'GET / HTTP/1.1\r\nHost: x\r\n\r\n' | nc localhost 8085
HTTP/1.1 200 OK
Transfer-Encoding: chunked

6            ← next piece is 6 bytes (the size is written in hex)
part1        ← "part1" + a newline = 6 bytes

6
part2

0            ← zero-size piece: the body is finished

Sizes are in hexadecimal (base 16), so a 25-byte piece would start with 19 (1×16 + 9 = 25). You never write this format yourself. Go and Node switch to chunked automatically when the body is streamed in several writes, or is too big to buffer. For a small body written in one go, both compute Content-Length for you — that's why §02's capture has one.

One server, many websites: the Host header

HTTP/1.0 requests didn't say which website they wanted — only the path. So one IP addressIP addressThe number that identifies a machine on a network, like a postal address: 93.184.216.34 (IPv4) or 2606:2800:220:1::248 (IPv6). could only serve one site. HTTP/1.1 made the Host headerHost headerThe request header naming which website you want (Host: example.com). Required since HTTP/1.1, it lets one server at one IP address host many sites. required: Host: shop.example lets a single server at a single address host thousands of sites ("virtual hosting"). It's why curl always sends one.

The limit: one request at a time

Keep-alive saved the handshakes, but on each connection the client still has to wait for the whole response before sending the next request. If style.css takes 2 seconds to generate, logo.png waits behind it on that connection, even though it's ready instantly. That's head-of-line blockingHead-of-line blockingOne slow item at the front of a queue holds up everything behind it, even items that would be quick.: the item at the front of the line holds up everything behind it.

PipeliningPipelining (HTTP/1.1)Sending several requests on one connection without waiting for each response. Responses must still come back in order, so one slow response blocks the rest. Browsers never turned it on. tried to fix it: send all the requests at once, without waiting. But HTTP/1.1 has no way to label which response belongs to which request — responses must come back in the same order the requests went out. So the slow style.css still blocks logo.png behind it, just on the server side now. Add buggy proxiesProxy (network)A server that sits between a client and the real server, passing requests along — to cache, filter, log, or hide who's really talking. that mixed up pipelined responses, and every major browser left pipelining switched off.

The workaround: six connections

Browsers gave up on squeezing more out of one connection and opened several connections per hostname — 6 in all major browsers. Six requests run truly in parallel; the seventh waits for one of them to finish. Watch 12 files load over HTTP/1.1. Each row is one file; the label says which of the 6 connections carries it:

Notice the two waves: files 7–12 sit in striped grey ("queued") until a connection frees up, and then each still pays a full round trip before its first byte arrives — its time to first byteTime to first byte (TTFB)How long from sending a request until the first byte of the response arrives. At minimum one round trip, plus however long the server thinks. can never be less than one RTT.

Web developers piled hacks on top:

• Domain shardingDomain shardingAn old HTTP/1.1 trick: spread a site's files over several hostnames (img1.example.com, img2.example.com…) so the browser opens 6 connections to each. Counter-productive with HTTP/2. — serve images from img1.example.com, img2.example.com… to get 6 connections per name.
• Bundling and sprites — glue all JavaScript into one file, all icons into one image, so there are fewer requests to queue.
• Inlining — paste small CSS or images straight into the HTML.

HTTP/2: many streams on one connection

Same meaning, new wire format

HTTP/2 is a binary protocolBinary protocolA protocol whose messages are laid out as numbers in fixed positions (like “bytes 0–2 are the length”), rather than human-readable text lines. Faster and less ambiguous for computers to parse; you need a tool to read it.: instead of text lines, every frame starts with a 9-byte header in fixed positions — how long the frame is, what type it is, some flags, and the stream ID. A streamStream (HTTP/2, HTTP/3)One request/response exchange inside a shared connection, identified by a number (stream ID). Every frame carries its stream ID, so the receiver can sort interleaved frames back into separate responses. is one request/response pair; every frame belongs to exactly one stream.

The meaning is unchanged. The request line is split into special "pseudo-headers" that start with a colon, and header names are lowercase. curl -v --http2-prior-knowledge shows them translated back into something readable:

$ curl -v --http2-prior-knowledge http://localhost:8082/
> GET / HTTP/2                 ← curl's display; on the wire it's :method GET, :path /
> Host: localhost:8082         ← sent as the pseudo-header :authority
> User-Agent: curl/8.5.0
< HTTP/2 200                   ← really the pseudo-header :status 200; no "OK" text any more
< content-type: text/plain; charset=utf-8
< content-length: 19

(--http2-prior-knowledge means "I know this server speaks HTTP/2 without encryption, just start" — §09 explains when that's allowed.)

Watch the frames interleave

Three requests, one connection. Step through and watch frames from different streams share the wire, then get sorted back into separate files. The code panel is the frame header every frame starts with:

1// Every HTTP/2 frame starts with this 9-byte header
2// (like FrameHeader in golang.org/x/net/http2)
3type FrameHeader struct {
4    Length   uint32 // 24 bits: payload size
5    Type     uint8  // DATA, HEADERS, SETTINGS…
6    Flags    uint8  // e.g. END_STREAM
7    StreamID uint32 // which request it's part of
8}
9// …followed by Length bytes of payload

Two details from the stepper are worth remembering:

• Client-started streams get odd numbers: 1, 3, 5… Node's http2 module shows it plainly: three requests on one connection print stream 1, stream 3, stream 5.
• END_STREAM is a flag on the last frame of a stream. That's how the receiver knows a response is complete — no Content-Length or chunking needed.

The race: HTTP/1.1 vs HTTP/2

Same 12 files, same network as the §04 animation. HTTP/2 sends all 12 requests the moment its one connection is ready, and the responses share the bandwidth (the overlapping bars):

HTTP/2 wins here because it never has a second wave: no request sits queued, and no request pays an extra round trip waiting for a free connection. (The model is simplified, and all numbers are approximate — but the shape matches what you'd see in your browser's network tab.)

HPACK: stop sending the same headers 80 times

Every request carries headers, and they're mostly identical: the same user-agent, the same accept, often a cookie of several hundred bytes. A page with 80 requests and 600 bytes of headers each sends 48 KB of almost-identical text.

HPACKHPACKHTTP/2's header compression. Both sides keep a table of headers already sent; repeating one costs a byte or two (its table index) instead of the full text. fixes this. Both sides keep a table of headers already seen on this connection. The first time, cookie: session=… is sent in full and added to the table; after that it's sent as "entry 62" — a byte or two instead of hundreds. Common headers like :method: GET have permanent entries from the start.

Flow control: don't drown the reader

If one stream is a 2 GB download and the app reading it is slow, the sender shouldn't fill the receiver's memory with it. Flow controlFlow control (HTTP/2)Each side tells the other how many body bytes it's willing to receive per stream and per connection (a “window”), and grows it with WINDOW_UPDATE frames as it reads. Stops a fast sender from flooding a slow reader. gives each stream (and the connection as a whole) a "window": the number of body bytes the sender may send before waiting. The default starting window is 65,535 bytes. As the receiving app reads data, its side sends WINDOW_UPDATE frames saying "you may send N more". Your code never sees this — Go and Node do it for you — but it's why a stream whose reader stops reading eventually pauses, instead of buffering forever.

Server push: a feature that didn't work out

HTTP/2 let a server send files the browser hadn't asked for yet ("you asked for index.html; you'll want style.css too, here it is"). In practice server pushServer pushAn HTTP/2 feature that let a server send files the browser hadn't asked for yet. Rarely helped in practice; Chrome removed support in 2022 and Firefox in 2024. often pushed files the browser already had cached, wasting bandwidth, and it was hard to get right. Chrome removed it in 2022 and Firefox in 2024. Don't build on it. The replacement is a hint the browser can act on: a 103 Early Hints response or a Link: </style.css>; rel=preload header. Both say "you'll need style.css" and let the browser decide whether to fetch it — so it won't refetch a file it already has cached.

How the two sides agree to speak HTTP/2

Browsers only use HTTP/2 over HTTPS. During the TLS handshake, the client lists what it speaks (h2, http/1.1) and the server picks one. That's called ALPNALPNApplication-Layer Protocol Negotiation: inside the TLS handshake the client lists the protocols it speaks (h2, http/1.1) and the server picks one. That's how a browser and server agree on HTTP/2 without an extra round trip., and it costs no extra round trip. If the server doesn't pick h2, everyone falls back to HTTP/1.1 — which is why turning on HTTP/2 rarely breaks anything.

Where HTTP/2 still hurts: TCP head-of-line blocking

TCP only knows about one stream of bytes

To the operating system, an HTTP/2 connection is a single TCPTCPTransmission Control Protocol: delivers a stream of bytes between two programs reliably and in order, resending anything lost. HTTP/1.1, HTTP/2 and most databases run on it. connection: one long, ordered stream of bytes. TCP has no idea that bytes 1000–2000 belong to style.css and bytes 2000–3000 to logo.png. Its one promise is: the application receives every byte, in the original order.

So when a packetPacketOne small chunk of data sent across a network on its own, with a header saying where it's from and where it's going. Big messages are split into many packets. goes missing — packet lossPacket lossWhen a packet never arrives (a congested router dropped it, Wi-Fi interference). Reliable protocols notice and send it again, which costs at least one round trip. happens all the time on Wi-Fi and mobile networks — TCP must wait for the resend before it can hand over anything that came after it. The later packets have already arrived; they just sit in a buffer inside the operating system. Noticing the loss and getting the resend takes at least one round trip, often more.

Toggle between the two transports and see which packets the application is allowed to read. Each packet carries frames from one stream (the colors):

On TCP, packet 3 belongs to stream C — but streams A and B, whose data has fully arrived, wait too. That's head-of-line blocking at the transport layer, and no HTTP/2 feature can work around it, because the waiting happens below HTTP.

Now race them with packet loss

Turn on packet loss. One packet of file 2 is lost shortly after the downloads start, and the red striped bars show who has to wait for the resend:

With loss on:

• HTTP/1.1 has 6 separate TCP connections. Only the connection carrying file 2 stalls; the other five keep going.
• HTTP/2 has one TCP connection. Every stream that hasn't finished stalls for the whole round trip.

Fixing this means replacing TCP — but you can't just change TCP. It's built into every operating system and every network device between you and the server, many of which drop traffic they don't recognize. The next section shows the clever way around that.

HTTP/3 and QUIC

Why build on UDP?

The obvious fix for §06 would be "change TCP so it understands streams". But TCP lives inside every operating system, and between you and any server sit dozens of routersRouterA device that forwards packets between networks, choosing the next hop toward each packet's destination address. Your home Wi-Fi box is one; the internet is thousands of them., firewallsFirewallA filter that allows or blocks network traffic by rules — e.g. “only port 443 from the internet”. and NATNATNetwork Address Translation: a router rewrites private addresses (like 192.168.1.20) to its one public address on the way out, and back on the way in. Why your laptop isn't directly reachable from the internet. boxes that inspect TCP traffic and often drop anything that looks unfamiliar. A new TCP would take decades to roll out. (People call this "ossification": the network has set like bone around the protocols it already knows.)

UDP, on the other hand, is a nearly empty envelope: "deliver this packet to that port, maybe". Networks already let it through, because DNS, video calls and games use it. So QUIC is built on top of UDP, and all the hard parts — reliable delivery, ordering per stream, congestion control, encryption — live inside the QUIC library that ships with your browser or server. That also means QUIC can improve with an app update instead of an OS update. And because QUIC encrypts almost all of its own headers, middleboxesMiddleboxAny device in the path that does more than forward packets: firewalls, NAT boxes, load balancers, corporate proxies. They often look inside TCP or even HTTP, which is why new protocols are hard to deploy. (those routers, firewalls and NAT boxes) can't peek at them and start depending on them — so it should stay changeable.

Loss only stalls its own stream

Each QUIC stream is delivered in order on its own. If a packet carrying stream C's data is lost, streams A and B keep handing data to the application; only C waits for the resend. That's the "QUIC" setting of the packets widget in §06. HTTP/3 even had to replace HPACK with QPACKQPACKHTTP/3's version of HPACK, redesigned so a lost packet on one stream can't block header decoding on the others., because HPACK assumed headers arrive in strict order across all streams — exactly the assumption QUIC removes.

One round trip to start, sometimes zero

With HTTP/2, the client needs a TCP handshake, then a TLS handshake, before it can send a request. QUIC does the transport and the TLS 1.3 handshake together in the same packets. And when reconnecting to a server it has talked to recently, the client can even send its request in the very first packet — 0-RTT0-RTT (early data)A TLS 1.3 option where a resuming client sends its first request together with its ClientHello, before any reply. Saves one round trip, but that early data can be replayed by an attacker..

With our 100 ms round trip: the first response arrives after about 300 ms on HTTP/2 over TLS 1.3, 200 ms on HTTP/3, and 100 ms with 0-RTT.

Connection migration: Wi-Fi → cellular without a hiccup

A TCP connection is identified by four numbers: your IP address and port, and the server's IP address and port. Walk out of the house, your phone switches from Wi-Fi to cellular, your IP address changes — and every TCP connection is dead. The app has to reconnect: new handshakes, and requests in flight fail or restart.

QUIC puts a random connection IDConnection ID (QUIC)A random ID that QUIC puts in every packet to say which connection it belongs to, instead of relying on the sender's IP address and port. in every packet. When packets with a known connection ID start arriving from a new address, the server checks that the new path really works and carries on. That's connection migrationConnection migrationQUIC's ability to keep a connection alive when your IP address changes (Wi-Fi → cellular), because packets are matched by connection ID, not by address.: the video keeps streaming as you walk out the door. (In practice clients support it better than servers and load balancers do so far — a load balancer has to route by connection ID instead of by address for it to work.)

How the browser finds out a server speaks HTTP/3

A browser can't know in advance that a server speaks QUIC on UDP. The usual flow:

1. The first visit uses HTTP/2 (or 1.1) over TCP, as normal.
2. The response includes an Alt-SvcAlt-SvcA response header (Alt-Svc: h3=":443") where a server says “I also speak HTTP/3 on this port”. Browsers try HTTP/3 on later connections. A DNS HTTPS record can advertise the same thing before the first connection. header, for example alt-svc: h3=":443"; ma=86400 — "I also speak HTTP/3 on UDP port 443; remember this for 86,400 seconds (a day)".
3. Later connections try HTTP/3. If UDP is blocked (some corporate networks block it), the browser quietly falls back to TCP.

Newer setups also publish the same hint in a DNSDNSThe Domain Name System: the internet's phone book that turns a name like example.com into an IP address your computer can connect to. record of type HTTPS, so even the first connection can go straight to HTTP/3.

The full race

All three versions, same 12 files. Try it with and without loss:

HTTP/3 starts a round trip earlier (the shorter setup), and with loss on, only file 2 waits.

Adoption: honest numbers

• Browsers: all major browsers support HTTP/3.
• Servers: most big CDNsCDNContent Delivery Network: servers spread around the world that keep copies of your files close to users, so they're served from a nearby city instead of your origin server. and large sites (Google, Meta, Cloudflare's customers) have it on. Roughly a third of websites advertise HTTP/3 support (survey figures from 2025 — check current numbers, they're moving). Popular self-hosted servers have added support more slowly.
• Not everywhere it helps: inside a data center, round trips are ~1 ms and loss is rare, so TCP + HTTP/2 or even HTTP/1.1 between your own services is perfectly fine.
• It costs CPU: QUIC runs in a normal program instead of inside the operating system itself (the kernelOperating system (OS) / kernelThe core program (Linux, macOS, Windows) that manages hardware, memory, threads, files and network connections for every other program. The kernel is its innermost part.) and can't yet use all the network-card tricks TCP has, so serving the same traffic takes noticeably more CPU.

Caching, conditional requests and safe retries

A cacheCacheA small, fast store of answers you already computed or fetched, so the next request for the same thing skips the slow work. The hard part is knowing when a cached answer is out of date. is a store of answers you already have. Browsers, CDNsCDNContent Delivery Network: servers spread around the world that keep copies of your files close to users, so they're served from a nearby city instead of your origin server. and proxies all keep HTTP caches. The server decides what they may do with each response, using headers.

Cache-Control: how long a copy stays fresh

Cache-ControlCache-ControlThe response header that tells browsers, CDNs and proxies whether and how long they may reuse a response: max-age=3600, no-cache, no-store, private… is a response header with a few instructions you'll see constantly:

ETag: "has it changed since this version?"

When a stored copy needs checking, re-downloading it every time would waste the cache. Instead the server labels each version with an ETagETagA response header holding a version label for the content (often a hash), e.g. ETag: "v42". The client sends it back in If-None-Match to ask “has it changed since this version?”. (often a hash of the content). The client sends the label back in a conditional requestConditional requestA request with a condition header like If-None-Match: "v42". The server only sends the full body if the condition holds — otherwise it answers 304 Not Modified with no body.: If-None-Match: "v42" — "send it only if your current version is not v42". If nothing changed, the server answers 304 Not Modified304 Not ModifiedA response with no body meaning “the copy you already have is still current — use it”. Saves sending the same bytes again., with headers but no body.

1# First visit
2GET /users/7 HTTP/1.1
3 
4HTTP/1.1 200 OK
5ETag: "v42"
6Cache-Control: no-cache
7Content-Length: 21
8 
9{"id":7,"name":"Ada"}
10 
11# Later: is my copy still current?
12GET /users/7 HTTP/1.1
13If-None-Match: "v42"
14 
15HTTP/1.1 304 Not Modified
16ETag: "v42"

Here's the server side, by hand so you can see every step:

var (
    body = []byte(`{"id":7,"name":"Ada"}`)
    etag = fmt.Sprintf(`"%x"`, sha256.Sum256(body)) // version label = hash of the content
)

func user(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("ETag", etag)
    w.Header().Set("Cache-Control", "no-cache") // "check with me every time"

    if r.Header.Get("If-None-Match") == etag {
        w.WriteHeader(http.StatusNotModified) // ← 304, no body
        return
    }
    w.Header().Set("Content-Type", "application/json")
    w.Write(body)
}

In real code you rarely hand-roll this: Go's http.ServeContent and http.FileServer, Express's res.send, and every static-file server handle ETag, Last-Modified and If-None-Match for you — including the details skipped above, like a client sending several ETags at once. Last-Modified / If-Modified-Since is the older, date-based version of the same idea.

Retries: which requests can you safely send twice?

Networks fail halfway all the time. Your request timed out — did the server receive it and act on it, or not? You can't know. Whether it's safe to just send it again depends on the method:

• Safe methodsSafe methodAn HTTP method that only reads and should never change anything on the server: GET, HEAD, OPTIONS. Safe methods are also idempotent. (GET, HEAD, OPTIONS) only read. Retrying is always fine.
• idempotentIdempotentDoing it twice has the same effect as doing it once. “Set balance to 50” is idempotent; “add 50 to balance” is not — so only the first is safe to retry blindly. methods (PUT, DELETE, plus the safe ones) give the same end result if repeated. "Set the name to Ada" twice is still "Ada". Retrying is fine.
• POST and most PATCH are neither. Retrying "charge the card €50" may charge it twice.

To make a POST safely retryable, the client sends a unique ID with it, usually an Idempotency-Key: 8c1f… header — an idempotency keyIdempotency keyA unique ID the client sends with a request (e.g. an Idempotency-Key header) so the server can recognise a repeat and do the work only once.. The server remembers which keys it has already processed and returns the stored result for a repeat instead of doing the work again. Payment APIs do exactly this.

When you retry yourself, wait a little longer each time and add randomness, and cap the total — retries with backoff and jitter shows the code, and a retry budgetRetry budgetA cap on how much extra load retries may add (say, 10% of normal traffic), so retries can't multiply an outage. stops retries from multiplying an outage.

HTTP/2 and HTTP/3 in Go and Node

Go: HTTP/2 is automatic over TLS

Serve with TLS and Go negotiates HTTP/2 with every client that offers it (that's the ALPNALPNApplication-Layer Protocol Negotiation: inside the TLS handshake the client lists the protocols it speaks (h2, http/1.1) and the server picks one. That's how a browser and server agree on HTTP/2 without an extra round trip. step from §05). Your handlers don't change; r.Proto tells you what was used.

srv := &http.Server{
    Addr:              ":8443",
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,
}
// cert.pem / key.pem: your TLS certificate and private key (see the TLS topic)
log.Fatal(srv.ListenAndServeTLS("cert.pem", "key.pem")) // ← h2 and http/1.1, chosen per client

The client side is automatic too: http.Client uses HTTP/2 with any HTTPS server that supports it — unless you customize the transport.

ForceAttemptHTTP2 = false → HTTP/1.1
ForceAttemptHTTP2 = true  → HTTP/2.0

tr := &http.Transport{
    TLSClientConfig:   &tls.Config{RootCAs: myCAs},
    ForceAttemptHTTP2: true, // ← without this line: HTTP/1.1 only
}
client := &http.Client{Transport: tr, Timeout: 10 * time.Second}

Go: HTTP/2 without TLS (h2c)

Browsers never speak HTTP/2 without encryption. But between your own services, or in tests, plain-text HTTP/2 — h2ch2cHTTP/2 over plain TCP without TLS (“cleartext”). Browsers don't support it; it's used between internal services and in tests. — can make sense. Since Go 1.24, the standard library supports it through http.Protocols:

var p http.Protocols
p.SetHTTP1(true)
p.SetUnencryptedHTTP2(true) // ← accept h2c as well as HTTP/1.1

srv := &http.Server{Addr: ":8082", Handler: mux, Protocols: &p, ReadHeaderTimeout: 5 * time.Second}

That's the server curl --http2-prior-knowledge talked to in §05. A Go client opts in the same way, with Protocols on its http.Transport. (Before Go 1.24 you'd use the golang.org/x/net/http2/h2c package.)

Node: the http2 module

Node keeps HTTP/2 in its own module, node:http2. Setting allowHTTP1: true lets old clients use HTTP/1.1 on the same port, and the "request" event gives you the familiar (req, res) handler:

import http2 from "node:http2";
import { readFileSync } from "node:fs";

const server = http2.createSecureServer({
  key: readFileSync("key.pem"),
  cert: readFileSync("cert.pem"),
  allowHTTP1: true, // ← HTTP/1.1 clients still work
});

server.on("request", (req, res) => {
  res.writeHead(200, { "content-type": "text/plain" });
  res.end(`you spoke HTTP/${req.httpVersion}\n`); // "2.0" or "1.1"
});
server.listen(8443);

curl -k https://localhost:8443/ prints you spoke HTTP/2.0; with --http1.1 it prints you spoke HTTP/1.1. (-k skips certificate checking — fine for a self-signed test certificate, never for real traffic.) For the stream-level API, listen to the "stream" event instead; http2.connect() is the matching low-level client.

On the client side, Node's built-in fetch uses HTTP/1.1 by default (as of Node 22). The undici package it's built on can enable HTTP/2 with an Agent option (allowH2: true); check the version you run, because this has been changing.

HTTP/3 support today

Connection pools and the timeout taxonomy

How Go's client reuses connections

A Go http.Client hands the real work to its http.Transporthttp.Transport (Go)The part of Go's HTTP client that actually opens, pools and reuses connections. An http.Client wraps one; http.DefaultTransport is shared by default.. When a request finishes and its body has been read and closed, the Transport puts the connection into an idle pool, keyed by host. The next request to that host takes an idle connection instead of paying for new handshakes. How many connections it keeps is set by a few fields:

The trap: MaxIdleConnsPerHost = 2

Most backend services call one host — their database API, a payment provider, another internal service — with dozens of requests at once. Say 10 requests run concurrently. Go opens 10 connections (MaxConnsPerHost is unlimited). When they finish, it may only keep 2 of them; the other 8 are closed. The next burst opens 8 new connections, with fresh TCP and TLS handshakes, and closes 8 again afterward. Press the button a few times and compare the pool sizes:

Every closed connection costs twice. The next request pays the handshakes again — 2 round tripsRound-trip time (RTT)How long it takes for a message to go from one machine to another and for the reply to come back. Roughly 1 ms inside a data center, 70–150 ms across an ocean. or more. And the side that closed the connection keeps a TIME_WAITTIME_WAITThe state the side that closes a TCP connection first stays in for a while afterwards (60 seconds on Linux). It remembers the old connection so a stray late packet can't be mistaken for part of a new one. record of it for about a minute. At a few hundred requests per second you can pile up tens of thousands of them and run out of local portsPortA number from 0 to 65535 that picks which program on a machine should get the traffic — like an apartment number after the street address. HTTPS servers usually listen on port 443. for new outgoing connections. Your error logs then fill with connect: cannot assign requested address.

The fix is one line: set MaxIdleConnsPerHost to roughly your peak concurrency toward that host. Here is a client configured for production — every phase bounded, the pool sized:

func newClient() *http.Client {
    tr := http.DefaultTransport.(*http.Transport).Clone() // keeps HTTP/2, proxy settings…
    tr.DialContext = (&net.Dialer{
        Timeout:   2 * time.Second, // TCP connect
        KeepAlive: 30 * time.Second,
    }).DialContext
    tr.TLSHandshakeTimeout = 3 * time.Second   // TLS handshake
    tr.ResponseHeaderTimeout = 5 * time.Second // request sent → response headers arrive
    tr.IdleConnTimeout = 90 * time.Second      // unused connections leave the pool after this
    tr.MaxIdleConns = 200                      // pool size, all hosts together
    tr.MaxIdleConnsPerHost = 100               // ← the default is 2!
    tr.MaxConnsPerHost = 200                   // optional hard cap per host (0 = unlimited)

    return &http.Client{
        Transport: tr,
        Timeout:   10 * time.Second, // everything, including reading the body
    }
}

With HTTP/2 the pool matters less — one connection carries many requests at once — but Go still opens extra connections when a server's limit on simultaneous streams (often 100–250) is reached, so the pool settings still apply.

Node: Agent for http/https, a separate pool for fetch

Node's http and https modules use an http.Agenthttp.Agent (Node)The object in Node's http/https modules that manages and reuses connections for outgoing requests, like Go's Transport. http.globalAgent is used unless you pass your own.. Since Node 19, the global agent has keep-alive on by default, with no limit on sockets per host (maxSockets: Infinity) and up to 256 idle sockets kept per host. For a service that should cap its outgoing connections, create your own:

import http from "node:http";

export const agent = new http.Agent({
  keepAlive: true,
  maxSockets: 100,     // at most 100 connections per host; further requests queue
  maxFreeSockets: 100, // idle connections kept per host
  timeout: 60_000,     // close a socket that has been idle for 60 s
});

http.get("http://users.internal/users/7", { agent, signal: AbortSignal.timeout(10_000) }, (res) => {
  res.resume(); // read (and here, discard) the body so the socket returns to the pool
});

fetch does not use http.Agent. It's built on the undici library, which has its own pool (also keep-alive by default) and its own timeouts: 10 s to connect, and the 300 s header and body limits from §03. To tune it, install the undici package and pass a new Agent({ connections, headersTimeout, bodyTimeout, … }) as fetch's dispatcher option. Since installed and built-in versions can differ, check their compatibility first.

One timeout per phase

"The request timed out" can mean very different things. Every request goes through the same phases, and each phase fails in its own way:

In production: server timeouts, proxies and httptrace

Slowloris: an attack made of patience

A server can't run your handler until it has read the request headers. A slowlorisSlowlorisAn attack where a client opens many connections and sends request headers extremely slowly (one byte every few seconds), so a server without a header timeout ties up a connection — and memory — for each one, forever. client opens a connection and sends headers one byte every few seconds, never finishing. Each such connection costs the server memory (and in thread-per-connection servers, a whole thread). A few thousand of them, from one laptop, and real users can't get in.

Go's http.Server has no timeouts by default. Set them:

srv := &http.Server{
    Addr:              ":8080",
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,   // ← the anti-slowloris one: whole header block
    ReadTimeout:       30 * time.Second,  // headers + body (uploads)
    WriteTimeout:      30 * time.Second,  // from end of headers until the response is written
    IdleTimeout:       120 * time.Second, // keep-alive: close idle connections after this
    MaxHeaderBytes:    1 << 20,           // 1 MB (this is also the default)
}

1 << 20 shifts the number 1 left by 20 binary places: 2²⁰ = 1,048,576 bytes. Linters like gosec flag a server without ReadHeaderTimeout.

Node has safer defaults (checked on Node 22): server.headersTimeout is 60 s (time allowed to receive the headers), server.requestTimeout is 300 s (time allowed to receive the entire request), and server.keepAliveTimeout is 5 s (an idle keep-alive connection is closed after this).

The mysterious 502: keep-alive timeouts behind a load balancer

A classic production bug. Your Node app sits behind a cloud load balancerLoad balancerA component that spreads incoming requests or connections across several servers, so no single one is overloaded and a dead one can be skipped. that keeps idle connections to your app open for 60 s. Node closes idle connections after 5 s. Sometimes the load balancer sends a new request on a connection at the same moment Node closes it. The request is lost, and the user gets a 502 Bad Gateway — rare, random, impossible to reproduce locally.

The rule: the app's idle timeout must be longer than the proxy's. If the load balancer's is 60 s, set server.keepAliveTimeout = 65_000 in Node (and keep headersTimeout above it — older Node versions required that), or IdleTimeout: 75 * time.Second in Go. Then the proxy always closes first, and closing first is safe for it.

HTTP/2 at the edge, HTTP/1.1 behind it

Real traffic usually looks like this:

browser ──h3 / h2 over TLS──▶ CDN / load balancer ──HTTP/1.1 (or h2c)──▶ your Go/Node app
          (the internet: long RTT, loss)            (data center: ~1 ms RTT, no loss)

The proxy at the edge does TLS terminationTLS terminationDecrypting TLS at a proxy or load balancer in front of your app, so the app behind it receives plain HTTP (or a second, separate TLS connection). (it decrypts HTTPS) and speaks whatever the browser prefers. Behind it, HTTP/1.1 with keep-alive is fine: round trips are short, loss is rare, and the proxy keeps a pool of connections open to each backend. This is exactly why HTTP/3's benefits rarely need to reach your app.

Things that bite at this boundary:

• The client's real address. Your app sees the proxy's IP address. The original one arrives in a header like X-Forwarded-For (or the standard Forwarded), and the original scheme in X-Forwarded-Proto: https. Only trust these headers when they're set by your proxy — a client can send them too.
• HTTP/2 between proxy and app breaks naive balancing. With HTTP/1.1, a load balancer spreads requests across connections. A single long-lived HTTP/2 connection carries all of one client's requests to one backend, so a balancer that only picks a backend when a connection opens leaves the load lopsided. It matters most for gRPC, which always uses HTTP/2 — see Load balancing and gRPC.
• Timeouts are layered. The edge has its own idle and request timeouts. A 60 s proxy request timeout makes your 120 s handler limit irrelevant — users see a 504 Gateway Timeout first.

Measure, don't guess: httptrace

When a request is slow, find out which phase was slow. Go's httptracenet/http/httptraceA Go standard-library package that lets you register callbacks for each step of an outgoing request: DNS lookup, connect, TLS handshake, connection reused or not, first response byte. package calls your functions at each step of an outgoing request:

start := time.Now()
since := func() time.Duration { return time.Since(start).Round(100 * time.Microsecond) }

trace := &httptrace.ClientTrace{
    DNSDone:              func(httptrace.DNSDoneInfo) { fmt.Println(since(), "DNS done") },
    ConnectDone:          func(network, addr string, err error) { fmt.Println(since(), "TCP connected to", addr) },
    TLSHandshakeDone:     func(tls.ConnectionState, error) { fmt.Println(since(), "TLS handshake done") },
    GotConn:              func(i httptrace.GotConnInfo) { fmt.Println(since(), "got conn, reused:", i.Reused) },
    GotFirstResponseByte: func() { fmt.Println(since(), "first response byte") },
}
req, err := http.NewRequest("GET", url, nil)
if err != nil {
    return err
}
req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace)) // ← attach the callbacks
resp, err := client.Do(req)

Real output for two requests to a local HTTPS server that takes 20 ms to answer:

--- first request
100µs DNS done
300µs TCP connected to 127.0.0.1:36427
1.9ms TLS handshake done
2ms got conn, reused: false
22.5ms first response byte        ← 20 ms of server thinking
--- second request
0s got conn, reused: true         ← keep-alive: no DNS, TCP or TLS at all
20.4ms first response byte

If reused is always false in production, you're paying handshakes on every request — check the pool size (§10) and that bodies are drained (§12). Without writing code, curl -w prints the same phases:

$ curl -s -o /dev/null -w "dns %{time_namelookup}s  connect %{time_connect}s  tls %{time_appconnect}s  first-byte %{time_starttransfer}s  total %{time_total}s\n" https://api.example.com/health

Each number is the time since the start, so the TLS handshake took tls − connect, and the server's thinking time is roughly first-byte − tls. In browsers, the Network tab's "Timing" panel shows the same breakdown, and its "Protocol" column (right-click the header row to add it) shows http/1.1, h2 or h3 per request. For tracing across many services, these phases become spansTracing / spanDistributed tracing records the path of one request through your code and services. Each timed step (one middleware, one DB query) is a span, so you can see where the time went. in a tracing system.

Pitfalls gallery

resp, err := http.Get(url) // waits forever if the server never answers

var client = &http.Client{Timeout: 5 * time.Second}

resp, err := client.Get(url)

resp, err := client.Get(url)
if err != nil {
    return err
}
if resp.StatusCode != http.StatusOK {
    return fmt.Errorf("status %d", resp.StatusCode) // ← body never closed
}
defer resp.Body.Close()

resp, err := client.Get(url)
if err != nil {
    return err
}
defer resp.Body.Close() // ← right after the error check, before anything else

if resp.StatusCode != http.StatusOK {
    return fmt.Errorf("status %d", resp.StatusCode)
}

close only:        reused=false reused=false reused=false
drain 64 KB:       reused=false reused=false reused=false
drain, then close: reused=false reused=true reused=true

defer resp.Body.Close()
var u User
err = json.NewDecoder(resp.Body).Decode(&u)
// the decoder may stop before the end of the body

defer func() {
    io.Copy(io.Discard, resp.Body) // read the rest…
    resp.Body.Close()              // …now reusable
}()
var u User
err = json.NewDecoder(resp.Body).Decode(&u)

func getUser(id string) (*User, error) {
    c := &http.Client{Transport: &http.Transport{}} // new pool every call
    resp, err := c.Get(base + "/users/" + id)
    // …
}

var client = newClient() // once, at startup (§10)

func getUser(id string) (*User, error) {
    resp, err := client.Get(base + "/users/" + id)
    // …
}

const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
const user = await res.json(); // 500? parses the error page, or throws a confusing SyntaxError

const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
if (!res.ok) throw new Error(`GET ${url}: ${res.status}`); // ok = status 200–299
const user = await res.json();

Check yourself

Commit to an answer before you click. If you miss one, the explanation points back to the section that covers it.

resp, err := http.Get("https://api.example.com/report")
if err != nil {
    log.Fatal(err)
}

client := &http.Client{Timeout: 5 * time.Second}
for i := 0; i < 3; i++ {
    resp, err := client.Get(url)
    if err != nil {
        return err
    }
    resp.Body.Close() // body never read
}

Cheat sheet