github.com/quic-go/go-ossfuzz-seeds v0.1.0: manage OSS-Fuzz seed corpus generation with Helper

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: manage OSS-Fuzz seed corpus generation with Helper
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/quic-go/go-ossfuzz-seeds@v0.1.0
Demonstrate these symbols/APIs:
  - github.com/quic-go/go-ossfuzz-seeds.Helper

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:728c7e7f8d32a6891abbb22a3047d32d0f5305088e916d1dc1a544474d9f90d2","contract":["Helper embeds testing.F to expose standard fuzz testing methods","Helper.Add registers seed inputs without writing files when FUZZ_CORPUS_DIR is unset","Helper writes corpus files with 0644 permissions into configured corpus directory","Helper skips writing corpus file when dynamic argument lengths cannot be encoded","Helper records byte slice payloads matching direct CorpusEntry serialization"],"goal":"manage OSS-Fuzz seed corpus generation with Helper","kind":"HOW","packages":["pkg:golang/github.com/quic-go/go-ossfuzz-seeds@v0.1.0"],"schemaVersion":1,"symbols":["github.com/quic-go/go-ossfuzz-seeds.Helper"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","compiler":"go","compilerVersion":"1.26.6","distro":"ubuntu","ecosystem":"golang","language":"go","languageVersion":"1.26.6","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/go-ossfuzz-seeds@v0.1.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/quic-go/go-ossfuzz-seeds@v0.1.0","symbols":["github.com/quic-go/go-ossfuzz-seeds.Helper"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.26.6

require github.com/quic-go/go-ossfuzz-seeds v0.1.0

github.com/quic-go/go-ossfuzz-seeds v0.1.0 h1:APacT+iIaNF6fd8AGEiN3bT/Jtkd2jz4v4TzM7MFjy0=
github.com/quic-go/go-ossfuzz-seeds v0.1.0/go.mod h1:3IOHRbJIc+L6YKMwfDtJAM9Vj9k0YY4muhuyUYk5tbk=

package main

import (
	"fmt"
	"os"
	"testing"

	ossfuzzseeds "github.com/quic-go/go-ossfuzz-seeds"
)

func main() {
	testing.Init()

	corpusDir := os.Getenv("FUZZ_CORPUS_DIR")
	if corpusDir == "" {
		corpusDir = "./corpus"
		os.Setenv("FUZZ_CORPUS_DIR", corpusDir)
		defer os.RemoveAll(corpusDir)
	}

	f := &testing.F{}
	helper := ossfuzzseeds.New(f)

	helper.Add(uint8(1), "init-corpus", []byte("payload"))
	fmt.Printf("Helper managed seed corpus entry in %s\n", corpusDir)
}

{
  "schemaVersion": 1,
  "goal": "manage OSS-Fuzz seed corpus generation with Helper",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/quic-go/go-ossfuzz-seeds@v0.1.0"
  ],
  "symbols": [
    "github.com/quic-go/go-ossfuzz-seeds.Helper"
  ]
}

package main

import (
	"bytes"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"testing"

	ossfuzzseeds "github.com/quic-go/go-ossfuzz-seeds"
)

func main() {
	testing.Init()

	if err := runContractTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract assertion failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All contract assertions passed.")
}

func runContractTests() error {
	// Assertion 1: Helper embeds testing.F to expose standard fuzz testing methods
	{
		f := &testing.F{}
		h := ossfuzzseeds.New(f)
		if h == nil {
			return errors.New("assertion 1 failed: New returned nil Helper")
		}
		if h.F != f {
			return errors.New("assertion 1 failed: Helper.F does not match provided testing.F")
		}
		if h.Skipped() {
			return errors.New("assertion 1 failed: unexpected Skipped() on fresh testing.F")
		}
	}

	// Assertion 2: Helper.Add registers seed inputs without writing files when FUZZ_CORPUS_DIR is unset
	{
		os.Unsetenv("FUZZ_CORPUS_DIR")
		f := &testing.F{}
		h := ossfuzzseeds.New(f)
		if h == nil {
			return errors.New("assertion 2 failed: New returned nil Helper")
		}
		h.Add(uint8(10), "test-disabled")
	}

	tmpBase, err := os.MkdirTemp("", "csx-helper-test-*")
	if err != nil {
		return fmt.Errorf("failed to create temp dir: %w", err)
	}
	defer os.RemoveAll(tmpBase)

	// Assertion 3: Helper writes corpus files with 0644 permissions into configured corpus directory
	targetDir := filepath.Join(tmpBase, "corpus-perm")
	{
		os.Setenv("FUZZ_CORPUS_DIR", targetDir)
		defer os.Unsetenv("FUZZ_CORPUS_DIR")

		f := &testing.F{}
		h := ossfuzzseeds.New(f)
		seedArgs := []any{uint16(1234), "mode-check"}
		h.Add(seedArgs...)

		entries, err := os.ReadDir(targetDir)
		if err != nil || len(entries) != 1 {
			return fmt.Errorf("assertion 3 failed: expected 1 corpus file in %s: %w", targetDir, err)
		}
		info, err := entries[0].Info()
		if err != nil {
			return fmt.Errorf("assertion 3 failed: stat error: %w", err)
		}
		if info.Mode().Perm() != 0o644 {
			return fmt.Errorf("assertion 3 failed: expected mode 0644, got %v", info.Mode().Perm())
		}
	}

	// Assertion 4: Helper skips writing corpus file when dynamic argument lengths cannot be encoded
	errDir := filepath.Join(tmpBase, "corpus-err")
	{
		os.Setenv("FUZZ_CORPUS_DIR", errDir)
		defer os.Unsetenv("FUZZ_CORPUS_DIR")

		f := &testing.F{}
		h := ossfuzzseeds.New(f)
		// testing.F.Add accepts []byte, but dynamicSizeWeights fails for these lengths:
		h.Add(make([]byte, 1), make([]byte, 1), make([]byte, 100000))

		entries, err := os.ReadDir(errDir)
		if err != nil {
			return fmt.Errorf("assertion 4 failed: ReadDir failed: %w", err)
		}
		if len(entries) != 0 {
			return fmt.Errorf("assertion 4 failed: expected 0 files on unencodable lengths, found %d", len(entries))
		}
	}

	// Assertion 5: Helper records byte slice payloads matching direct CorpusEntry serialization
	payloadDir := filepath.Join(tmpBase, "corpus-payload")
	{
		os.Setenv("FUZZ_CORPUS_DIR", payloadDir)
		defer os.Unsetenv("FUZZ_CORPUS_DIR")

		f := &testing.F{}
		h := ossfuzzseeds.New(f)
		payload := []byte{0x01, 0x02, 0x03, 0x04}
		seedArgs := []any{uint8(7), "payload-test", payload}
		h.Add(seedArgs...)

		expectedBytes, err := ossfuzzseeds.CorpusEntry(seedArgs...)
		if err != nil {
			return fmt.Errorf("assertion 5 failed: CorpusEntry failed: %w", err)
		}

		entries, err := os.ReadDir(payloadDir)
		if err != nil || len(entries) != 1 {
			return fmt.Errorf("assertion 5 failed: expected 1 file, got %v", entries)
		}
		content, err := os.ReadFile(filepath.Join(payloadDir, entries[0].Name()))
		if err != nil {
			return fmt.Errorf("assertion 5 failed: ReadFile failed: %w", err)
		}
		if !bytes.Equal(content, expectedBytes) {
			return fmt.Errorf("assertion 5 failed: content mismatch: got %x, want %x", content, expectedBytes)
		}
	}

	return nil
}