github.com/quic-go/qpack v0.5.1: 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: verify qpack.Decoder in pkg:golang/github.com/quic-go/qpack@v0.5.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/quic-go/qpack@v0.5.1
Demonstrate these symbols/APIs:
  - qpack.Decoder
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:392a8cf141dc05cfcd6f3a7cfddfaeaf62728c8ef2fe768fa5f9d326cb8a2ced","constraints":{"executionContext":"go"},"contract":["DecodeFull decodes complete QPACK header blocks into HeaderField slices preserving field names and values","DecodeFull correctly decodes pseudo-headers and identifies them via HeaderField.IsPseudo","NewDecoder with emitFunc processes incremental byte chunks passed to Write","DecodeFull returns an error when parsing invalid or malformed QPACK header data","Decoder.Close closes the decoder context cleanly on completed stream"],"goal":"verify qpack.Decoder in pkg:golang/github.com/quic-go/qpack@v0.5.1","kind":"HOW","packages":["pkg:golang/github.com/quic-go/qpack@v0.5.1"],"schemaVersion":1,"symbols":["qpack.Decoder"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","ecosystem":"golang","executionContext":"go","language":"go","moduleSystem":"go.mod","os":"linux","packageManager":"go","runtime":"go","runtimeVersion":"1.26","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.Decoder"],"verifierAdapter":"golang@1"}

package sample

import (
	"bytes"
	"fmt"
	"io"

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

// EncodeHeaders encodes a slice of HeaderFields into a QPACK header block.
func EncodeHeaders(fields []qpack.HeaderField) ([]byte, error) {
	var buf bytes.Buffer
	enc := qpack.NewEncoder(&buf)
	for _, f := range fields {
		if err := enc.WriteField(f); err != nil {
			return nil, fmt.Errorf("failed to encode field %s: %w", f.Name, err)
		}
	}
	if err := enc.Close(); err != nil {
		return nil, fmt.Errorf("failed to close encoder: %w", err)
	}
	return buf.Bytes(), nil
}

// DecodeHeaderBlock decodes a full QPACK header block into a slice of HeaderFields using DecodeFull.
func DecodeHeaderBlock(block []byte) ([]qpack.HeaderField, error) {
	dec := qpack.NewDecoder(nil)
	defer dec.Close()
	fields, err := dec.DecodeFull(block)
	if err != nil {
		return nil, fmt.Errorf("failed to decode header block: %w", err)
	}
	return fields, nil
}

// DecodeStreaming decodes QPACK header data provided across multiple byte chunks via incremental Write calls.
func DecodeStreaming(chunks [][]byte) ([]qpack.HeaderField, error) {
	var emitted []qpack.HeaderField
	dec := qpack.NewDecoder(func(f qpack.HeaderField) {
		emitted = append(emitted, f)
	})

	for _, chunk := range chunks {
		n, err := dec.Write(chunk)
		if err != nil {
			dec.Close()
			return nil, fmt.Errorf("failed writing chunk: %w", err)
		}
		if n != len(chunk) {
			dec.Close()
			return nil, io.ErrShortWrite
		}
	}

	if err := dec.Close(); err != nil {
		return nil, fmt.Errorf("failed to close decoder: %w", err)
	}

	return emitted, nil
}

module example.com/qpack-decoder

go 1.26.6

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

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

github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/quic-go/qpack v0.5.1 h1:giqksBPnT/HDtZ6VhtFKgoLOWmlyo9Ei6u9PqzIMbhI=
github.com/quic-go/qpack v0.5.1/go.mod h1:+PC4XFrEskIVkcLzpEkbLqq1uCoxPhQuvK5rH1ZgaEg=
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
golang.org/x/net v0.28.0 h1:a9JDOJc5GMUJ0+UDqmLT86WiEy7iWyIhz8gz8E4e5hE=
golang.org/x/net v0.28.0/go.mod h1:yqtgsTWOOnlGLG9GFRrK3++bGOUEkNBoHZc8MEDWPNg=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

{
  "schemaVersion": 1,
  "goal": "verify qpack.Decoder in pkg:golang/github.com/quic-go/qpack@v0.5.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/quic-go/qpack@v0.5.1"
  ],
  "symbols": [
    "qpack.Decoder"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

package test

import (
	"reflect"
	"testing"

	sample "example.com/qpack-decoder"
	"github.com/quic-go/qpack"
)

func TestDecoderContract(t *testing.T) {
	// 1. DecodeFull decodes full header blocks into expected HeaderField slices
	inputHeaders := []qpack.HeaderField{
		{Name: ":status", Value: "200"},
		{Name: ":path", Value: "/api/v1/resource"},
		{Name: "content-type", Value: "application/json"},
		{Name: "x-custom-header", Value: "custom-value-123"},
	}

	encoded, err := sample.EncodeHeaders(inputHeaders)
	if err != nil {
		t.Fatalf("failed to encode sample headers: %v", err)
	}

	decoded, err := sample.DecodeHeaderBlock(encoded)
	if err != nil {
		t.Fatalf("failed to decode header block: %v", err)
	}

	if len(decoded) != len(inputHeaders) {
		t.Fatalf("expected %d headers, got %d", len(inputHeaders), len(decoded))
	}

	for i, want := range inputHeaders {
		got := decoded[i]
		if got.Name != want.Name || got.Value != want.Value {
			t.Errorf("header %d mismatch: got %+v, want %+v", i, got, want)
		}
		if got.IsPseudo() != want.IsPseudo() {
			t.Errorf("header %d IsPseudo mismatch: got %v, want %v", i, got.IsPseudo(), want.IsPseudo())
		}
	}

	// 2. Decoder with emitFunc callback processes streamed chunks via Write
	if len(encoded) > 2 {
		chunk1 := encoded[:2]
		chunk2 := encoded[2:]
		streamed, err := sample.DecodeStreaming([][]byte{chunk1, chunk2})
		if err != nil {
			t.Fatalf("failed to decode streaming chunks: %v", err)
		}
		if !reflect.DeepEqual(streamed, inputHeaders) {
			t.Fatalf("streaming decoded headers mismatch: got %+v, want %+v", streamed, inputHeaders)
		}
	}

	// 3. DecodeFull returns an error when given invalid or corrupted QPACK byte data
	invalidData := []byte{0xff, 0xff, 0xff, 0xff}
	dec := qpack.NewDecoder(nil)
	defer dec.Close()
	_, err = dec.DecodeFull(invalidData)
	if err == nil {
		t.Fatal("expected error decoding invalid QPACK data, got nil")
	}

	// 4. Decoder.Close closes decoder cleanly
	var emittedDirect []qpack.HeaderField
	directDec := qpack.NewDecoder(func(f qpack.HeaderField) {
		emittedDirect = append(emittedDirect, f)
	})
	n, err := directDec.Write(encoded)
	if err != nil {
		t.Fatalf("unexpected error writing to decoder: %v", err)
	}
	if n != len(encoded) {
		t.Fatalf("wrote %d bytes, expected %d", n, len(encoded))
	}
	if err := directDec.Close(); err != nil {
		t.Fatalf("expected clean close on complete stream, got error: %v", err)
	}
	if len(emittedDirect) != len(inputHeaders) {
		t.Fatalf("emitted header count mismatch: got %d, want %d", len(emittedDirect), len(inputHeaders))
	}
}