### Install filepathx

Source: https://github.com/klauspost/compress/blob/master/s2/cmd/internal/filepathx/README.md

Use 'go get' to install the filepathx library.

```bash
go get github.com/yargevad/filepathx
```

--------------------------------

### Sample Directory Contents

Source: https://github.com/klauspost/compress/blob/master/s2/cmd/internal/filepathx/README.md

Lists the files and directories within the 'a' directory for the example.

```txt
a
a/b
a/b/c.d
a/b/c.d/e.f
```

--------------------------------

### Install s2 Commandline Tools

Source: https://github.com/klauspost/compress/blob/master/s2/README.md

Installs the `s2c` (compress) and `s2d` (decompress) command-line tools globally using `go install`.

```Shell
go install github.com/klauspost/compress/s2/cmd/s2c@latest && go install github.com/klauspost/compress/s2/cmd/s2d@latest
```

--------------------------------

### Command Line Usage

Source: https://github.com/klauspost/compress/blob/master/dict/README.md

Instructions on how to install and use the `builddict` command-line tool to create dictionaries from sample data.

```APIDOC
## Installation
```bash
$ go install github.com/klauspost/compress/dict/cmd/builddict@latest
```

## Basic Usage
Collect samples in a directory (e.g., `samples/`) and run:

```bash
$ builddict samples/
```

This creates `dictionary.bin` in the current directory.

## Options

- `-format` (string): Output type. Options: "zstd", "s2", "raw". Default: "zstd".
- `-hash` (int): Hash bytes match length. Minimum match length. Must be 4-8. Default: 6.
- `-len` (int): Specify custom output size. Default: 114688.
- `-max` (int): Max input length to index per input file. Default: 32768.
- `-o` (string): Output file name. Default: `dictionary.bin`.
- `-q`: Suppress progress output.
- `-dictID` (int): Zstandard dictionary ID. 0 for random. Default: 0.
- `-zcompat` (bool): Generate dictionary compatible with zstd 1.5.5 and older. Default: false.
- `-zlevel` (int): Zstandard compression level (1-4). Default: 4 (best).
```

--------------------------------

### Install Dictionary Builder CLI

Source: https://github.com/klauspost/compress/blob/master/dict/README.md

Installs the command-line tool for building dictionaries. Ensure you have Go installed and configured.

```bash
$ go install github.com/klauspost/compress/dict/cmd/builddict@latest
```

--------------------------------

### Directory Structure Example

Source: https://github.com/klauspost/compress/blob/master/s2/cmd/internal/filepathx/README.md

Illustrates a sample directory structure used for testing globbing patterns.

```bash
find a
```

--------------------------------

### Install gzhttp Package

Source: https://github.com/klauspost/compress/blob/master/gzhttp/README.md

Use this command to install or update the gzhttp package.

```bash
go get -u github.com/klauspost/compress
```

--------------------------------

### Library Usage (Go)

Source: https://github.com/klauspost/compress/blob/master/dict/README.md

Example of how to use the `dict` package in Go code to programmatically build Zstandard dictionaries.

```APIDOC
## Build Zstandard Dictionary
```Go
package main

import (
	"github.com/klaupost/compress/dict"
	"github.com/klauspost/compress/zstd"
)

func main() {
	var samples [][]byte

	// ... Fill samples with representative data.

	dict, err := dict.BuildZstdDict(samples, dict.Options{
		HashLen:     6,
		MaxDictSize: 114688,
		ZstdDictID:  0, // Random
		ZstdCompat:  false,
		ZstdLevel:   zstd.SpeedBestCompression,
	})
	// ... Handle error, etc.
}
```

Similar functions `BuildS2Dict` and `BuildRawDict` are available for S2 and raw dictionaries.
```

--------------------------------

### Globbing Example with filepathx

Source: https://github.com/klauspost/compress/blob/master/s2/cmd/internal/filepathx/README.md

Demonstrates how to use filepathx.Glob with a double star pattern to find files recursively. Ensure the program is built and executed with the desired pattern as a command-line argument.

```go
package main

import (
	"fmt"
	"os"

	"github.com/yargevad/filepathx"
)

func main() {
	if 2 != len(os.Args) {
		fmt.Println(len(os.Args), os.Args)
		fmt.Fprintf(os.Stderr, "Usage: go build example/find/*.go; ./find <pattern>\n")
		os.Exit(1)
		return
	}
	pattern := os.Args[1]

	matches, err := filepathx.Glob(pattern)
	if err != nil {
		panic(err)
	}

	for _, match := range matches {
		fmt.Printf("MATCH: [%v]\n", match)
	}
}
```

--------------------------------

### Encoding Example with Dictionary

Source: https://github.com/klauspost/compress/blob/master/s2/README.md

Demonstrates an encoded sequence using literals and backreferences, referencing a predefined dictionary. The output shows the decoded string based on the provided dictionary and encoded instructions.

```text
Dictionary: `[0x0a][Yesterday 25 bananas were added to Benjamins brown bag]`.

Initial repeat offset is set at 10, which is the letter `2`.

Encoded `[LIT "10"][REPEAT len=10][LIT "hich"][MATCH off=50 len=6][MATCH off=31 len=6][MATCH off=61 len=10]`

Decoded: `[10][ bananas w][hich][ were ][brown ][were added]`

Output: `10 bananas which were brown were added`
```

--------------------------------

### Example: Content-Aware Random Jitter (Go)

Source: https://github.com/klauspost/compress/blob/master/gzhttp/README.md

Applies 1 to 32 bytes of random data based on the first 50000 bytes of content. This helps obfuscate the exact compressed size for security.

```Go
gzhttp.RandomJitter(32, 50000)
```

--------------------------------

### Registering Zstd Compressor/Decompressor for ZIP Files

Source: https://github.com/klauspost/compress/blob/master/zstd/README.md

Example demonstrating how to register Zstd compressors and decompressors for individual zip Reader/Writer instances. This approach avoids global registration panics and allows for resource reuse.

```go
import (
	"github.com/klauspost/compress/zstd"
	"github.com/klauspost/compress/zip"
)

func ExampleZipCompressor() {
	// Create a new zip writer with a Zstd compressor
	zw, err := zip.NewWriter(os.Stdout)
	if err != nil {
		panic(err)
	}

	// Register the Zstd compressor for this writer
	compressor, err := zstd.NewWriter(nil)
	if err != nil {
		panic(err)
	}
	zw.RegisterCompressor(zip.Zstd, compressor)

	// Create a new zip reader with a Zstd decompressor
	zr, err := zip.NewReader(os.Stdin, 1024)
	if err != nil {
		panic(err)
	}

	// Register the Zstd decompressor for this reader
	decompressor, err := zstd.NewReader(nil)
	if err != nil {
		panic(err)
	}
	zr.RegisterDecompressor(zip.Zstd, decompressor)

	// Now you can compress and decompress files within zip archives using Zstd
	// ... (rest of the zip file operations)

	// Close the writer and reader
	compressor.Close()
	decompressor.Close()
	zw.Close()
	// zr.Close() is not needed as it doesn't hold resources
}

```

--------------------------------

### Configure Zstandard Encoder with Options

Source: https://context7.com/klauspost/compress/llms.txt

Option functions passed to `zstd.NewWriter` or `enc.ResetWithOptions` to tune compression level, window size, concurrency, CRC, padding, and dictionary use. Examples include `WithEncoderLevel`, `WithWindowSize`, `WithEncoderConcurrency`, `WithEncoderCRC`, and `WithEncoderPadding`.

```go
package main

import (
	"bytes"
	"io"
	"log"
	"fmt"

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

func main() {
	enc, err := zstd.NewWriter(nil,
		zstd.WithEncoderLevel(zstd.SpeedBetterCompression),
		zstd.WithWindowSize(4<<20),          // 4 MB window
		zstd.WithEncoderConcurrency(4),
		zstd.WithEncoderCRC(true),
		zstd.WithEncoderPadding(512),         // pad output to 512-byte boundary
		zstd.WithZeroFrames(true),            // encode empty input as a full frame
		zstd.WithAllLitEntropyCompression(true),
	)
	if err != nil {
		log.Fatal(err)
	}

	var buf bytes.Buffer
	enc.Reset(&buf)
	io.WriteString(enc, "content to compress with tuned settings")
	enc.Close()
	fmt.Printf("output size (padded to 512): %d bytes\n", buf.Len())

	// Switch to fastest on the same encoder instance
	var buf2 bytes.Buffer
	err = enc.ResetWithOptions(&buf2,
		zstd.WithEncoderLevel(zstd.SpeedFastest),
		zstd.WithEncoderCRC(false),
	)
	if err != nil {
		log.Fatal(err)
	}
	io.WriteString(enc, "fast path")
	enc.Close()
	fmt.Printf("fast output: %d bytes\n", buf2.Len())
}
```

--------------------------------

### Create gzip compressed data with kgzip.NewWriterLevel

Source: https://context7.com/klauspost/compress/llms.txt

Provides a stdlib-compatible `*gzip.Writer` with improved throughput. Supports various compression levels. The example demonstrates writing to a buffer and then decompressing with the standard library's gzip reader.

```go
package main

import (
	"bytes"
	"compress/gzip"
	"fmt"
	"io"
	"log"

	kgzip "github.com/klauspost/compress/gzip"
)

func main() {
	var buf bytes.Buffer

	w, err := kgzip.NewWriterLevel(&buf, kgzip.BestSpeed)
	if err != nil {
		log.Fatal(err)
	}
	w.Header.Name = "data.txt"
	io.WriteString(w, "gzip-compressed content using klauspost/compress — drop-in replacement")
	if err := w.Close(); err != nil {
		log.Fatal(err)
	}

	fmt.Printf("gzip compressed: %d bytes\n", buf.Len())

	// Decompress with stdlib gzip (byte-for-byte compatible)
	r, err := gzip.NewReader(&buf)
	if err != nil {
		log.Fatal(err)
	}
	defer r.Close()
	out, _ := io.ReadAll(r)
	fmt.Println(string(out))
}
```

--------------------------------

### Enable Stateless Compression

Source: https://github.com/klauspost/compress/blob/master/gzhttp/README.md

Shows how to enable stateless compression using `CompressionLevel(-3)` or `CompressionLevel(gzip.StatelessCompression)`. It is recommended to use this with a `bufio.Writer` with a small buffer for high-concurrency, low-activity scenarios.

```Go
gzhttp.CompressionLevel(-3)
```

--------------------------------

### Build and Run Command

Source: https://github.com/klauspost/compress/blob/master/s2/cmd/internal/filepathx/README.md

Shows the commands to build the Go program and then run it with a specific globbing pattern.

```bash
go build example/find/*.go
./find 'a/**/*.*'
```

--------------------------------

### Build Zstandard Dictionary using Go Library

Source: https://github.com/klauspost/compress/blob/master/dict/README.md

Demonstrates how to build a Zstandard dictionary programmatically using the `dict` package. Ensure samples are pre-truncated and representative.

```go
package main

import (
	"github.com/klaupost/compress/dict"
	"github.com/klauspost/compress/zstd"
)

func main() {
	var samples [][]byte

	// ... Fill samples with representative data.

	dict, err := dict.BuildZstdDict(samples, dict.Options{
		HashLen:     6,
		MaxDictSize: 114688,
		ZstdDictID:  0, // Random
		ZstdCompat:  false,
		ZstdLevel:   zstd.SpeedBestCompression,
	})
	// ... Handle error, etc.
}
```

--------------------------------

### Buffer Decompression

Source: https://github.com/klauspost/compress/blob/master/zstd/README.md

Example of how to decompress a byte slice (buffer) using the zstd library. This method is suitable for smaller, in-memory data chunks.

```APIDOC
## Buffer Decompression

### Description
This example demonstrates how to decompress a byte slice into another byte slice.

### Usage
Create a `zstd.Reader` with a `nil` input (for buffer operations) and optionally configure concurrency. Then, use the `DecodeAll` method to decompress the source buffer.

### Code Example
```Go
import "github.com/klauspost/compress/zstd"

// Create a reader that caches decompressors. For buffer operations, nil is supplied.
var decoder, _ = zstd.NewReader(nil, zstd.WithDecoderConcurrency(0))

func DecompressBuffer(src []byte) ([]byte, error) {
    // The destination buffer can be nil; it will be allocated by the decoder.
    return decoder.DecodeAll(src, nil)
}
```

### Notes
- `zstd.WithDecoderConcurrency(0)` creates GOMAXPROCS decoders.
- The decoder can be reused for concurrent decompression of multiple buffers.
- For best performance, store and reuse the decoder instance.
```

--------------------------------

### zstd.EncodeTo / zstd.DecodeTo

Source: https://context7.com/klauspost/compress/llms.txt

Package-level convenience functions that maintain a shared, GC-managed encoder/decoder using Go 1.24 weak pointers. No setup required.

```APIDOC
## zstd.EncodeTo / zstd.DecodeTo — Simple one-shot functions (Go 1.24+)

Package-level convenience functions that maintain a shared, GC-managed encoder/decoder using Go 1.24 weak pointers. No setup required.

### zstd.EncodeTo

Compresses `src` using a shared encoder.

#### Parameters

`dst` ([]byte): The destination buffer. If nil, a new buffer will be allocated.
`src` ([]byte): The data to compress.

#### Returns

`[]byte`: The compressed data.

### zstd.DecodeTo

Decompresses `src` using a shared decoder.

#### Parameters

`dst` ([]byte): The destination buffer. If nil, a new buffer will be allocated.
`src` ([]byte): The data to decompress.

#### Returns

`[]byte`: The decompressed data.
`error`: An error if decompression fails.
```

--------------------------------

### One-Shot Compression/Decompression with zstd.EncodeTo/DecodeTo (Go 1.24+)

Source: https://context7.com/klauspost/compress/llms.txt

Package-level convenience functions that maintain a shared, GC-managed encoder/decoder using Go 1.24 weak pointers. No setup required.

```go
//go:build go1.24

package main

import (
	"fmt"
	"log"

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

func main() {
	src := []byte("quick compression with no setup")

	compressed := zstd.EncodeTo(nil, src)
	fmt.Printf("compressed %d → %d bytes\n", len(src), len(compressed))

	decompressed, err := zstd.DecodeTo(nil, compressed)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(decompressed))
	// quick compression with no setup
}
```

--------------------------------

### Streaming Decompression

Source: https://github.com/klauspost/compress/blob/master/zstd/README.md

Example of how to decompress a stream of data using the zstd library. It demonstrates creating a new reader, copying data, and properly closing the reader to release resources.

```APIDOC
## Streaming Decompression

### Description
This example shows how to decompress a stream of data from an `io.Reader` to an `io.Writer`.

### Usage
Create a new `zstd.Reader` with the input stream, defer its `Close` method, and then use `io.Copy` to write the decompressed data to the output writer.

### Code Example
```Go
import "github.com/klauspost/compress/zstd"
import "io"

func DecompressStream(in io.Reader, out io.Writer) error {
    d, err := zstd.NewReader(in)
    if err != nil {
        return err
    }
    defer d.Close()
    
    _, err = io.Copy(out, d)
    return err
}
```

### Notes
- Ensure `d.Close()` is called to release goroutines, especially when using default settings.
- Goroutines will exit upon returning an error, including `io.EOF`.
- Streams are decoded concurrently in 4 stages by default. Use `zstd.WithDecoderConcurrency(1)` for synchronous decompression.
```

--------------------------------

### Build Zstandard Dictionary using CLI

Source: https://github.com/klauspost/compress/blob/master/dict/README.md

Builds a Zstandard dictionary from sample files located in a directory. The dictionary is saved as 'dictionary.bin' by default.

```bash
$ builddict samples/
```

--------------------------------

### Create and Use S2 Dictionary

Source: https://github.com/klauspost/compress/blob/master/s2/README.md

Demonstrates how to create an S2 dictionary from a sample file, encode data using it, and decode data. The same dictionary must be used for both encoding and decoding.

```Go
    // Read a sample
    sample, err := os.ReadFile("sample.json")

    // Create a dictionary.
    dict := s2.MakeDict(sample, nil)
	
    // b := dict.Bytes() will provide a dictionary that can be saved
    // and reloaded with s2.NewDict(b).
	
    // To encode:
    encoded := dict.Encode(nil, file)

    // To decode:
    decoded, err := dict.Decode(nil, file)
```

--------------------------------

### Create Snappy Compatible Writer with S2

Source: https://github.com/klauspost/compress/blob/master/s2/README.md

Initializes a new S2 writer that is compatible with Snappy. This allows for stream compression using S2's efficient encoders while maintaining Snappy compatibility.

```Go
enc := s2.NewWriter(w, s2.WriterSnappyCompat())
```

--------------------------------

### File Copy with Read-ahead

Source: https://github.com/klauspost/compress/blob/master/s2/cmd/internal/readahead/README.md

Demonstrates a basic file copy operation using the readahead package. Error handling is omitted for brevity. Ensure the input and output files exist and are accessible.

```Go
input, _ := os.Open("input.txt")
output, _ := os.Create("output.txt")
def input.Close()
def output.Close()

// Create a read-ahead Reader with default settings
ra := readahead.NewReader(input)
def ra.Close()

// Copy the content to our output
_, _ = io.Copy(output, ra)
```

--------------------------------

### Get Index Separately with s2.NewWriter and CloseIndex

Source: https://github.com/klauspost/compress/blob/master/s2/README.md

Create a writer without the `WriterAddIndex()` option and use `CloseIndex()` to retrieve the index separately. This is useful for storing the index for later use without appending it to the compressed stream.

```go
enc := s2.NewWriter(w)
io.Copy(enc, r)
index, err := enc.CloseIndex()
```

--------------------------------

### Configure Zstd Compression Options

Source: https://github.com/klauspost/compress/blob/master/gzhttp/README.md

Demonstrates how to configure the gzhttp wrapper for Zstd compression. Options include disabling Zstd, disabling Gzip, preferring Zstd over Gzip, setting the Zstd compression level, and using a custom Zstd writer implementation.

```Go
// Disable zstd, only use gzip
wrapper, _ := gzhttp.NewWrapper(gzhttp.EnableZstd(false))
```

```Go
// Disable gzip, only use zstd
wrapper, _ := gzhttp.NewWrapper(gzhttp.EnableGzip(false))
```

```Go
// Prefer gzip when client accepts both with equal qvalues
wrapper, _ := gzhttp.NewWrapper(gzhttp.PreferZstd(false))
```

```Go
// Set zstd compression level (1=fastest, 2=default, 3=better, 4=best)
wrapper, _ := gzhttp.NewWrapper(gzhttp.ZstdCompressionLevel(int(zstd.SpeedDefault)))
```

```Go
// Use custom zstd writer implementation
wrapper, _ := gzhttp.NewWrapper(gzhttp.ZstdImplementation(myZstdFactory))
```

--------------------------------

### Estimate Compressibility of Data

Source: https://context7.com/klauspost/compress/llms.txt

Use compress.Estimate to get a score indicating how compressible a byte slice is. Values near 0 are incompressible, while values above 0.1 are likely compressible. This can be used as a quick pre-check before allocating a compressor.

```go
package main

import (
	"fmt"
	"strings"

	"github.com/klauspost/compress"
)

func main() {
	repeated := []byte(strings.Repeat("hello world ", 100))
	random := make([]byte, 1200)
	for i := range random {
		random[i] = byte(i * 7)
	}

	fmt.Printf("repeated text score: %.3f\n", compress.Estimate(repeated))
	// repeated text score: 0.922

	fmt.Printf("pseudo-random score: %.3f\n", compress.Estimate(random))
	// pseudo-random score: 0.014

	if compress.Estimate(repeated) > 0.1 {
		fmt.Println("worth compressing")
	}
}
```

--------------------------------

### Create configurable HTTP compression middleware with gzhttp.NewWrapper

Source: https://context7.com/klauspost/compress/llms.txt

Returns a reusable middleware factory for fine-grained control over HTTP compression. Allows configuration of compression levels, minimum response size, content-type filtering, ETag handling, and BREACH mitigation.

```go
package main

import (
	"fmt"
	"net/http"

	"github.com/klauspost/compress/gzhttp"
	"github.com/klauspost/compress/gzip"
)

func main() {
	wrapper, err := gzhttp.NewWrapper(
		gzhttp.CompressionLevel(gzip.BestSpeed),
		gzhttp.MinSize(512),                    // only compress responses > 512 bytes
		gzhttp.ContentTypes([]string{           // whitelist specific content types
			"application/json",
			"text/html",
			"text/plain",
		}),
		gzhttp.SuffixETag("-gz"),               // append "-gz" to ETag on compressed responses
		gzhttp.EnableZstd(true),
		gzhttp.ZstdCompressionLevel(1),         // SpeedFastest
		gzhttp.PreferZstd(true),
	)
	if err != nil {
		panic(err)
	}

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		fmt.Fprint(w, `{"status":"ok","data":"compressed response"}`)
	})

	http.Handle("/", wrapper(handler))
	http.ListenAndServe(":8080", nil)
}
```

--------------------------------

### Example: Non-Content-Aware Random Jitter (Go)

Source: https://github.com/klauspost/compress/blob/master/gzhttp/README.md

Applies 1 to 32 bytes of random data, independent of content. Use when responses are very large or deterministic, and buffer size is a concern. This is considered less secure than content-based jitter.

```Go
gzhttp.RandomJitter(32, -1)
```

--------------------------------

### Build s2 Commandline Tools

Source: https://github.com/klauspost/compress/blob/master/s2/README.md

Builds the `s2c` (compress) and `s2d` (decompress) command-line tools into the current directory using `go build`.

```Shell
go build github.com/klauspost/compress/s2/cmd/s2c && go build github.com/klauspost/compress/s2/cmd/s2d
```