For HTTP/3, I’m doing the opposite and building from the sky, down.

HTTP/3 doesn’t use TCP. It runs over QUIC, which is built on UDP and implements its own encryption (TLS 1.3) and streams. If we started with a raw UDP socket today, we would have to write a lot of QUIC packet and crypto code before we could send a single HTTP request. I didn’t want to spend two or three posts on UDP plumbing before even touching HTTP/3.

Instead, we’re going to start at the top using quic-go for the QUIC streams in Part 1 and Part 2 while we build our HTTP/3 framing, QPACK encoder/decoder, server, and client. Once our HTTP/3 implementation works against curl and browsers, we’ll come back in Part 3, remove quic-go, and write a basic QUIC layer over UDP sockets.

All of the code for this post is in Go and is linked on GitHub at the bottom of the page.

Sending Bytes Over QUIC

Okay, let’s get some bytes moving. Before we build HTTP/3, we’ll give QUIC a quick test drive with an echo server. It is going to be the foundation of everything we build here, after all. Accept a connection, accept a stream, and send back whatever comes in:

conn, _ := listener.Accept(ctx)
stream, _ := conn.AcceptStream(ctx)

data, _ := io.ReadAll(stream)
stream.Write(append([]byte("echo: "), data...))
stream.Close()

Dialing from the client works the same way. As I wrote about in gRPC Over HTTP/3, QUIC always uses TLS 1.3 and checks the ALPN string (tls.Config.NextProtos) during the handshake, so we pass a tls.Config into quic.DialAddr, open a stream, write our bytes, and read back the response:

conn, _ := quic.DialAddr(ctx, addr, tlsConf, nil)
defer conn.CloseWithError(0, "done")

stream, _ := conn.OpenStreamSync(ctx)
stream.Write([]byte("Hello over QUIC!"))
stream.Close()

reply, _ := io.ReadAll(stream)

Notice that the client calls stream.Close() before calling io.ReadAll(stream). In quic-go, closing a stream only closes our write side (sending a FIN bit on that stream), so we can still read the server’s response afterward. Because QUIC streams already have their own FIN bit, HTTP/3 frames don’t need an END_STREAM flag like HTTP/2 had.

The server also needs to leave the connection open long enough for the client to read the reply. Calling conn.CloseWithError right after writing can cut that short. For this echo server, we close the stream and wait on <-conn.Context().Done() until the client disconnects.

Reusing HTTP/2 Framing

When you open RFC 9114 (HTTP/3), you get a strong sense of déjà vu if you’ve read the HTTP/2 spec.

In HTTP/2 From Scratch: Part 2, we built a parser for HTTP/2’s 9-byte frame header (Length, Type, Flags, and Stream ID). All of those frames shared a single TCP connection, so HTTP/2 had to keep track of the streams itself. In HTTP/3, each request gets its own QUIC stream. With QUIC handling more of the bookkeeping, our frame header gets a lot smaller: just Type and Length:

The remaining frame types keep the same numeric values we used in HTTP/2:

const (
	FrameData     uint64 = 0x00
	FrameHeaders  uint64 = 0x01
	FrameSettings uint64 = 0x04
	FrameGoAway   uint64 = 0x07
)

type Frame struct {
	Type    uint64
	Payload []byte
}

Several frame types from HTTP/2 (PRIORITY, RST_STREAM, PUSH_PROMISE, and PING) are gone here. Stream resets and pings moved into QUIC itself, and priority frames and Server Push were removed.

The main difference in the wire format is that Type and Length use QUIC variable-length integers instead of fixed-width integers. In gRPC From Scratch: Part 3, we covered Protobuf varints, which use the most significant bit of each byte as a continuation flag. Instead of checking a continuation bit on every byte, a QUIC varint uses the top two bits of the first byte to encode whether the integer is 1, 2, 4, or 8 bytes long. This approach ends up being faster to process than the protobuf version.

In ReadVarint, we read that first byte, shift its top two bits down with first[0] >> 6, and use 1 << prefix to figure out how many bytes to read:

func ReadVarint(r io.Reader) (uint64, error) {
	var first [1]byte
	if _, err := io.ReadFull(r, first[:]); err != nil {
		return 0, err
	}

	prefix := first[0] >> 6
	length := 1 << prefix

	val := uint64(first[0] & 0x3f)
	if length == 1 {
		return val, nil
	}

	rest := make([]byte, length-1)
	_, err := io.ReadFull(r, rest)
	for _, b := range rest {
		val = (val << 8) | uint64(b)
	}
	return val, err
}

Once we can read and write varints, ReadFrame is just two varint reads followed by io.ReadFull for the payload (in frame.go I also cap length at 16 MB so a bogus 62-bit varint doesn’t try to allocate terabytes of memory):

func ReadFrame(r io.Reader) (Frame, error) {
	fType, err := ReadVarint(r)
	if err != nil {
		return Frame{}, err
	}
	length, err := ReadVarint(r)
	if err != nil {
		return Frame{}, err
	}
	payload := make([]byte, length)
	_, err = io.ReadFull(r, payload)
	return Frame{Type: fType, Payload: payload}, err
}

From HPACK to QPACK

In HTTP/2 From Scratch: Part 3 and Part 4, we wrote an HPACKDecoder and HPACKEncoder (RFC 7541). Why couldn’t the HTTP/3 authors just reuse HPACK as-is and let us all go home early?

The issue is HPACK’s dynamic table. In HTTP/2, every HEADERS frame that inserts a new header into the dynamic table is sent over the same underlying TCP connection. Because TCP delivers all bytes strictly in order, the decoder is guaranteed to see table insertions in the exact order the encoder sent them, even across different streams.

With QUIC, packets on different streams can arrive out of order. If a packet on Stream 0 gets dropped on the network while a packet on Stream 4 arrives, QUIC can deliver Stream 4 right away. But if Stream 4’s headers referenced a dynamic table entry that was supposed to be created by Stream 0’s lost packet, the decoder wouldn’t be able to read Stream 4 until Stream 0 was retransmitted. We’d be right back to head-of-line blocking.

To get around this, HTTP/3 uses QPACK (RFC 9204). In QPACK, any dynamic table updates happen on separate unidirectional streams instead of inside the request streams, and every HEADERS frame starts with a 2-byte prefix (Required Insert Count and Delta Base). The static table is also bigger than HPACK’s (99 entries starting at index 0, compared to 61 entries starting at index 1 in HPACK) and adds full name/value pairs like content-type: application/json.

We’ll keep our implementation simple and encode headers using only the static table and string literals. With no dynamic table to synchronize, we can skip the encoder/decoder streams and set the header block prefix to two zero bytes.

We also get to reuse some code! QPACK keeps HPACK’s integer encoding and Huffman table (RFC 9204 Section 4.1), so we can bring over those helpers from our HTTP/2 package, including Huffman decoding from golang.org/x/net/http2/hpack. We just need to adjust the bitmasks that identify each kind of field line:

const (
	maskQPACKIndexed     = 0x80
	flagQPACKIndexedStat = 0x40

	maskQPACKLiteralNameRef     = 0xc0
	patternQPACKLiteralNameRef  = 0x40
	flagQPACKLiteralNameRefStat = 0x10

	maskQPACKLiteral    = 0xe0
	patternQPACKLiteral = 0x20
)

func (d *QPACKDecoder) Decode(payload []byte) ([]HeaderField, error) {
	r := bytes.NewReader(payload)
	_, _ = decodeInt(0, r, 8)
	_, _ = decodeInt(0, r, 7)

	var headers []HeaderField
	for r.Len() > 0 {
		b, _ := r.ReadByte()
		switch {
		case b&(maskQPACKIndexed|flagQPACKIndexedStat) == maskQPACKIndexed|flagQPACKIndexedStat:
			index, _ := decodeInt(b, r, 6)
			headers = append(headers, QPACKStaticTable[index])

		case b&(maskQPACKLiteralNameRef|flagQPACKLiteralNameRefStat) == patternQPACKLiteralNameRef|flagQPACKLiteralNameRefStat:
			index, _ := decodeInt(b, r, 4)
			val, _ := decodeString(r)
			headers = append(headers, HeaderField{Name: QPACKStaticTable[index].Name, Value: val})

		case b&maskQPACKLiteral == patternQPACKLiteral:
			name, _ := decodeNameString(b, r)
			val, _ := decodeString(r)
			headers = append(headers, HeaderField{Name: name, Value: val})
		}
	}
	return headers, nil
}

Modeling Requests and Responses

Now that we can encode QPACK headers and read/write HTTP/3 frames, sending an HTTP request or response over a QUIC stream looks a lot like HTTP/2. We still have the same lowercase header names and pseudo-headers (:method, :scheme, :authority, :path on requests, and :status on responses). In WriteRequest, we QPACK-encode the headers into a HEADERS frame (0x01) and then write the request body into a DATA frame (0x00):

func WriteRequest(w io.Writer, req *http.Request) error {
	headers := []HeaderField{
		{Name: ":method", Value: req.Method},
		{Name: ":scheme", Value: req.URL.Scheme},
		{Name: ":authority", Value: req.URL.Host},
		{Name: ":path", Value: req.URL.RequestURI()},
	}

	enc := NewQPACKEncoder()
	WriteFrame(w, FrameHeaders, enc.Encode(headers))

	if req.Body != nil {
		bodyBytes, _ := io.ReadAll(req.Body)
		if len(bodyBytes) > 0 {
			WriteFrame(w, FrameData, bodyBytes)
		}
	}
	return nil
}

To read the message on the other side, we call ReadFrame in a loop until io.EOF:

for {
	frame, err := ReadFrame(r)
	if errors.Is(err, io.EOF) {
		break
	}
	switch frame.Type {
	case FrameHeaders:
		fields, _ := dec.Decode(frame.Payload)
		applyHeaders(req, fields)
	case FrameData:
		bodyBuf.Write(frame.Payload)
	}
}

What About HTTP Trailers?

In HTTP/3, how do you send HTTP trailers (like grpc-status at the end of a gRPC call)? Because there are no flags on HTTP/3 frames, trailers are simply sent as a second HEADERS frame after the DATA frames, right before closing the stream.

Are we going to implement HTTP trailers in our from-scratch server and client?

Nah. I’m not implementing trailers in this walkthrough.

If you really want to see how trailers work in HTTP/3, you can reference my PRs to quic-go (#4581, #4630, #4639, #4656) where I added trailer support to the quic-go HTTP/3 implementation, or read my gRPC Over HTTP/3 and gRPC Over HTTP/3: Followup articles. If a second HEADERS frame shows up after DATA, we’re just going to ignore it.

Running the Demo

In main.go, I wired up the raw QUIC echo test followed by an HTTP/3 request and response over a QUIC stream:

$ go run .
=== Step 1: Raw QUIC Echo Demo ===
[Echo Client] Sending on stream 0: "Hello over QUIC!"
[Echo Server] Received on stream 0: "Hello over QUIC!"
[Echo Client] Got reply: "echo: Hello over QUIC!"

=== Step 2: HTTP/3 Framing & QPACK Over a QUIC Stream ===
[H3 Server] Decoded POST /hello (Host: kmcd.dev, User-Agent: kmcd-h3/0.1, Body: "ping from h3")
[H3 Client] Status: 200 OK
[H3 Client] Content-Type: text/plain; charset=utf-8, Server: kmcd-h3-scratch
[H3 Client] Body: Hello over HTTP/3! You sent 12 bytes.

That’s our first real *http.Request encoded into QPACK headers and HTTP/3 HEADERS + DATA frames, sent across a QUIC stream, and answered with a QPACK-encoded *http.Response.

What’s Next?

If you pointed curl --http3 or Chrome at our listener right now, they would hang up on us immediately. Real HTTP/3 peers expect both sides to open a one-way Control Stream (0x00) as soon as the connection starts and swap SETTINGS frames (0x04). Plus, browsers need a way to find out that your server speaks HTTP/3 over UDP in the first place.

In Part 2, we’ll look at how browsers discover HTTP/3 (Alt-Svc and DNS HTTPS records), how to convince Chrome and curl to talk HTTP/3 to localhost, and wrap our framing code into a proper http.Handler server and Client.

See all of the code mentioned in this article in http3-from-scratch-part-1/go.