github.com/quic-go/qpack v0.5.1: encode and decode HTTP/3 header fields with QPACK encoder and decoder

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: encode and decode HTTP/3 header fields with QPACK encoder and decoder
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/quic-go/qpack@v0.5.1
Demonstrate these symbols/APIs:
  - qpack.HeaderField
  - qpack.NewDecoder
  - qpack.NewEncoder
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.6
  - runtime: go@1.26.6

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:c40b201cb9029eb3371f55918815f045490a12971534d369a9d7c321e2cec16f","contract":["HeaderField.IsPseudo returns true for pseudo headers starting with colon and false otherwise","NewEncoder writes HeaderField sequence to bytes.Buffer and closes cleanly","NewDecoder.DecodeFull decodes byte buffer back into matching HeaderField slice","NewDecoder with emit callback incrementally decodes written header block"],"goal":"encode and decode HTTP/3 header fields with QPACK encoder and decoder","kind":"HOW","packages":["pkg:golang/github.com/quic-go/qpack@v0.5.1"],"schemaVersion":1,"symbols":["qpack.HeaderField","qpack.NewDecoder","qpack.NewEncoder"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/quic-go/qpack@v0.5.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/quic-go/qpack@v0.5.1","symbols":["qpack.HeaderField","qpack.NewDecoder","qpack.NewEncoder"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.22

require github.com/quic-go/qpack v0.5.1

require golang.org/x/net v0.28.0 // indirect

github.com/quic-go/qpack v0.5.1 h1:giqksBPnT/HDtZ6VhtFKgoLOWmlyo9Ei6u9PqzIMbhI=
github.com/quic-go/qpack v0.5.1/go.mod h1:+PC4XFrEskIVkcLzpEkbLqq1uCoxPhQuvK5rH1ZgaEg=
golang.org/x/net v0.28.0 h1:a9JDOJc5GMUJ0+UDqmLT86WiEy7iWyIhz8gz8E4e5hE=
golang.org/x/net v0.28.0/go.mod h1:yqtgsTWOOnlGLG9GFRrK3++bGOUEkNBoHZc8MEDWPNg=

package main

import (
	"bytes"
	"fmt"

	"github.com/quic-go/qpack"
)

func main() {
	headers := []qpack.HeaderField{
		{Name: ":method", Value: "GET"},
		{Name: ":path", Value: "/index.html"},
		{Name: ":scheme", Value: "https"},
		{Name: ":authority", Value: "example.com"},
		{Name: "custom-header", Value: "custom-value"},
	}

	var buf bytes.Buffer
	encoder := qpack.NewEncoder(&buf)
	for _, hf := range headers {
		if err := encoder.WriteField(hf); err != nil {
			panic(err)
		}
	}
	if err := encoder.Close(); err != nil {
		panic(err)
	}

	decoder := qpack.NewDecoder(nil)
	decoded, err := decoder.DecodeFull(buf.Bytes())
	if err != nil {
		panic(err)
	}

	for _, hf := range decoded {
		fmt.Printf("%s: %s (pseudo=%t)\n", hf.Name, hf.Value, hf.IsPseudo())
	}
}

{
  "schemaVersion": 1,
  "goal": "encode and decode HTTP/3 header fields with QPACK encoder and decoder",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/quic-go/qpack@v0.5.1"
  ],
  "symbols": [
    "qpack.HeaderField",
    "qpack.NewDecoder",
    "qpack.NewEncoder"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.6",
    "runtime": "go@1.26.6"
  }
}

package main

import (
	"bytes"
	"fmt"
	"os"
	"reflect"

	"github.com/quic-go/qpack"
)

func main() {
	headers := []qpack.HeaderField{
		{Name: ":method", Value: "GET"},
		{Name: ":path", Value: "/index.html"},
		{Name: ":scheme", Value: "https"},
		{Name: ":authority", Value: "example.com"},
		{Name: "custom-header", Value: "custom-value"},
	}

	if !headers[0].IsPseudo() || !headers[1].IsPseudo() || !headers[2].IsPseudo() || !headers[3].IsPseudo() {
		fmt.Fprintln(os.Stderr, "Contract failure: pseudo headers must return IsPseudo() == true")
		os.Exit(1)
	}
	if headers[4].IsPseudo() {
		fmt.Fprintln(os.Stderr, "Contract failure: normal headers must return IsPseudo() == false")
		os.Exit(1)
	}

	var buf bytes.Buffer
	encoder := qpack.NewEncoder(&buf)
	for _, hf := range headers {
		if err := encoder.WriteField(hf); err != nil {
			fmt.Fprintf(os.Stderr, "Contract failure: WriteField failed: %v\n", err)
			os.Exit(1)
		}
	}
	if err := encoder.Close(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract failure: encoder.Close failed: %v\n", err)
		os.Exit(1)
	}

	encoded := buf.Bytes()
	if len(encoded) == 0 {
		fmt.Fprintln(os.Stderr, "Contract failure: encoded bytes must not be empty")
		os.Exit(1)
	}

	decoder := qpack.NewDecoder(nil)
	decoded, err := decoder.DecodeFull(encoded)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Contract failure: DecodeFull failed: %v\n", err)
		os.Exit(1)
	}
	if !reflect.DeepEqual(headers, decoded) {
		fmt.Fprintf(os.Stderr, "Contract failure: decoded fields mismatch: got %+v, want %+v\n", decoded, headers)
		os.Exit(1)
	}

	var emitted []qpack.HeaderField
	emitDecoder := qpack.NewDecoder(func(f qpack.HeaderField) {
		emitted = append(emitted, f)
	})
	n, err := emitDecoder.Write(encoded)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Contract failure: emitDecoder.Write failed: %v\n", err)
		os.Exit(1)
	}
	if n != len(encoded) {
		fmt.Fprintf(os.Stderr, "Contract failure: emitDecoder.Write short write: got %d, want %d\n", n, len(encoded))
		os.Exit(1)
	}
	if err := emitDecoder.Close(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract failure: emitDecoder.Close failed: %v\n", err)
		os.Exit(1)
	}
	if !reflect.DeepEqual(headers, emitted) {
		fmt.Fprintf(os.Stderr, "Contract failure: emitted fields mismatch: got %+v, want %+v\n", emitted, headers)
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed successfully.")
	os.Exit(0)
}