github.com/klauspost/compress v1.20.0: huff0

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 github.com/klauspost/compress/huff0 in pkg:golang/github.com/klauspost/compress@v1.20.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/klauspost/compress@v1.20.0
Demonstrate these symbols/APIs:
  - github.com/klauspost/compress/huff0

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:f527293c75c9becd24fd61007b99cdee3171ed2c320592504a2b95c118c4baaa","contract":["huff0.Compress1X compresses compressible byte sequences and huff0.ReadTable with Scratch.Decompress1X restores original data","huff0.Scratch.Decoder returns a Decoder whose Decompress1X method decodes into a preallocated destination slice","huff0.Decoder returns a 'no table loaded' error when Decompress1X is called before loading a table","huff0.Compress4X compresses data into 4 streams and Decoder.Decompress4X restores original data","huff0.Compress1X returns ErrIncompressible for high-entropy incompressible data and ErrUseRLE for repeated bytes","huff0.Scratch.MaxDecodedSize limits maximum decoded size and returns ErrMaxDecodedSizeExceeded when exceeded"],"goal":"verify github.com/klauspost/compress/huff0 in pkg:golang/github.com/klauspost/compress@v1.20.0","kind":"HOW","packages":["pkg:golang/github.com/klauspost/compress@v1.20.0"],"schemaVersion":1,"symbols":["github.com/klauspost/compress/huff0"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/klauspost/compress@v1.20.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/klauspost/compress@v1.20.0","symbols":["github.com/klauspost/compress/huff0"],"verifierAdapter":"golang@1"}

module example.com/huff0sample

go 1.25

require github.com/klauspost/compress v1.20.0

github.com/klauspost/compress v1.20.0 h1:a3C1ke2ohxFymNlb2HWAHjDeKCI90scRskErZkR0ezA=
github.com/klauspost/compress v1.20.0/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=

package huff0codec

import (
	"bytes"
	"errors"
	"fmt"

	"github.com/klauspost/compress/huff0"
)

// Compress1X compresses input data using huff0.Compress1X.
func Compress1X(data []byte, s *huff0.Scratch) ([]byte, bool, error) {
	if s == nil {
		s = &huff0.Scratch{}
	}
	return huff0.Compress1X(data, s)
}

// Decompress1X decompresses 1X-encoded data using ReadTable and Scratch.Decompress1X.
func Decompress1X(compressed []byte) ([]byte, error) {
	scratch, remain, err := huff0.ReadTable(compressed, nil)
	if err != nil {
		return nil, fmt.Errorf("read table failed: %w", err)
	}
	return scratch.Decompress1X(remain)
}

// Compress4X compresses input data into 4 streams using huff0.Compress4X.
func Compress4X(data []byte, s *huff0.Scratch) ([]byte, bool, error) {
	if s == nil {
		s = &huff0.Scratch{}
	}
	return huff0.Compress4X(data, s)
}

// Decompress4X decompresses 4X-encoded data given the expected decompressed size.
func Decompress4X(compressed []byte, expectedSize int) ([]byte, error) {
	scratch, remain, err := huff0.ReadTable(compressed, nil)
	if err != nil {
		return nil, fmt.Errorf("read table failed: %w", err)
	}
	return scratch.Decompress4X(remain, expectedSize)
}

// RoundTrip1X compresses and decompresses data using 1X encoding, verifying byte equality.
func RoundTrip1X(data []byte) error {
	compressed, _, err := Compress1X(data, nil)
	if err != nil {
		return fmt.Errorf("compression failed: %w", err)
	}
	decompressed, err := Decompress1X(compressed)
	if err != nil {
		return fmt.Errorf("decompression failed: %w", err)
	}
	if !bytes.Equal(data, decompressed) {
		return errors.New("roundtrip decompressed bytes do not match original data")
	}
	return nil
}

// RoundTrip4X compresses and decompresses data using 4X encoding, verifying byte equality.
func RoundTrip4X(data []byte) error {
	compressed, _, err := Compress4X(data, nil)
	if err != nil {
		return fmt.Errorf("compression failed: %w", err)
	}
	decompressed, err := Decompress4X(compressed, len(data))
	if err != nil {
		return fmt.Errorf("decompression failed: %w", err)
	}
	if !bytes.Equal(data, decompressed) {
		return errors.New("roundtrip decompressed bytes do not match original data")
	}
	return nil
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/klauspost/compress/huff0 in pkg:golang/github.com/klauspost/compress@v1.20.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/klauspost/compress@v1.20.0"
  ],
  "symbols": [
    "github.com/klauspost/compress/huff0"
  ]
}

package main

import (
	"bytes"
	"errors"
	"fmt"
	"os"

	huff0codec "example.com/huff0sample"
	"github.com/klauspost/compress/huff0"
)

func main() {
	samplePayload := bytes.Repeat([]byte("huff0 fast huffman entropy coder in zstd compression. "), 60)

	// Assertion 1: Compress1X creates compressed payload and ReadTable + Scratch.Decompress1X restores original
	var s1 huff0.Scratch
	comp1X, reused1X, err := huff0.Compress1X(samplePayload, &s1)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: Compress1X failed: %v\n", err)
		os.Exit(1)
	}
	if len(comp1X) >= len(samplePayload) {
		fmt.Fprintf(os.Stderr, "FAIL: expected compressed size < original: got %d >= %d\n", len(comp1X), len(samplePayload))
		os.Exit(1)
	}
	if reused1X {
		fmt.Fprintf(os.Stderr, "FAIL: expected reused=false for first compress\n")
		os.Exit(1)
	}

	decScratch, remain1X, err := huff0.ReadTable(comp1X, nil)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: ReadTable failed: %v\n", err)
		os.Exit(1)
	}
	decomp1X, err := decScratch.Decompress1X(remain1X)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: decScratch.Decompress1X failed: %v\n", err)
		os.Exit(1)
	}
	if !bytes.Equal(decomp1X, samplePayload) {
		fmt.Fprintf(os.Stderr, "FAIL: Decompress1X output mismatch\n")
		os.Exit(1)
	}

	// Assertion 2: Decoder retrieved from Scratch.Decoder() decompresses 1X into provided destination
	dec := decScratch.Decoder()
	dst1X := make([]byte, 0, len(samplePayload))
	decOut1X, err := dec.Decompress1X(dst1X, remain1X)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: dec.Decompress1X failed: %v\n", err)
		os.Exit(1)
	}
	if !bytes.Equal(decOut1X, samplePayload) {
		fmt.Fprintf(os.Stderr, "FAIL: dec.Decompress1X output mismatch\n")
		os.Exit(1)
	}

	// Assertion 3: Uninitialized Decoder rejects Decompress1X with "no table loaded"
	var emptyDec huff0.Decoder
	_, err = emptyDec.Decompress1X(dst1X, remain1X)
	if err == nil || err.Error() != "no table loaded" {
		fmt.Fprintf(os.Stderr, "FAIL: expected 'no table loaded' error from uninitialized Decoder, got: %v\n", err)
		os.Exit(1)
	}

	// Assertion 4: Compress4X produces 4-stream compressed block and Decoder.Decompress4X decodes it
	var s4 huff0.Scratch
	comp4X, _, err := huff0.Compress4X(samplePayload, &s4)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: Compress4X failed: %v\n", err)
		os.Exit(1)
	}
	decScratch4, remain4X, err := huff0.ReadTable(comp4X, nil)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: ReadTable 4X failed: %v\n", err)
		os.Exit(1)
	}
	dec4 := decScratch4.Decoder()
	dst4X := make([]byte, 0, len(samplePayload))
	decOut4X, err := dec4.Decompress4X(dst4X, remain4X)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: dec.Decompress4X failed: %v\n", err)
		os.Exit(1)
	}
	if !bytes.Equal(decOut4X, samplePayload) {
		fmt.Fprintf(os.Stderr, "FAIL: dec.Decompress4X output mismatch\n")
		os.Exit(1)
	}

	// Assertion 5: Compress1X returns ErrIncompressible for high-entropy incompressible data
	incompressible := make([]byte, 256)
	for i := range incompressible {
		incompressible[i] = byte(i)
	}
	var sIncomp huff0.Scratch
	_, _, err = huff0.Compress1X(incompressible, &sIncomp)
	if !errors.Is(err, huff0.ErrIncompressible) {
		fmt.Fprintf(os.Stderr, "FAIL: expected ErrIncompressible, got: %v\n", err)
		os.Exit(1)
	}

	// Assertion 6: Compress1X returns ErrUseRLE for single repeated byte
	rleInput := bytes.Repeat([]byte{0x42}, 500)
	var sRle huff0.Scratch
	_, _, err = huff0.Compress1X(rleInput, &sRle)
	if !errors.Is(err, huff0.ErrUseRLE) {
		fmt.Fprintf(os.Stderr, "FAIL: expected ErrUseRLE, got: %v\n", err)
		os.Exit(1)
	}

	// Assertion 7: Scratch.MaxDecodedSize limits maximum allowed decoded size
	limitedScratch, remainLimit, err := huff0.ReadTable(comp1X, nil)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: ReadTable for MaxDecodedSize failed: %v\n", err)
		os.Exit(1)
	}
	limitedScratch.MaxDecodedSize = len(samplePayload) - 10
	_, err = limitedScratch.Decompress1X(remainLimit)
	if !errors.Is(err, huff0.ErrMaxDecodedSizeExceeded) {
		fmt.Fprintf(os.Stderr, "FAIL: expected ErrMaxDecodedSizeExceeded, got: %v\n", err)
		os.Exit(1)
	}

	// Assertion 8: Helper package RoundTrip functions succeed
	if err := huff0codec.RoundTrip1X(samplePayload); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: RoundTrip1X failed: %v\n", err)
		os.Exit(1)
	}
	if err := huff0codec.RoundTrip4X(samplePayload); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: RoundTrip4X failed: %v\n", err)
		os.Exit(1)
	}

	fmt.Println("PASS: github.com/klauspost/compress/huff0 contract passed")
}