zstdpatch

Documentation

Overview

Package zstdpatch — CLI-backed patch-from encode/decode.

These functions shell out to `zstd ≥ 1.5`. EncodeFull / DecodeFull live in fullgo.go and do NOT require the CLI.

Package zstdpatch — pure-Go plain-zstd encode/decode via klauspost/compress.

These functions do NOT require the zstd binary. They are used by the exporter for the size-ceiling comparison in intralayer.go, and kept in the API for decoder symmetry (no current production caller decodes zstd-full bytes — see spec §1 and §4.4).

Package zstdpatch implements zstd --patch-from style byte-level deltas and plain zstd encode/decode.

Two backends live in this package:

• cli.go — Encode / Decode (shells out to `zstd ≥ 1.5` for --patch-from)
• fullgo.go — EncodeFull / DecodeFull (pure Go, via github.com/klauspost/compress)

Availability of the CLI backend can be queried via Available(ctx) (see available.go).

Index

• Variables
• func Available(ctx context.Context) (ok bool, reason string)
• func AvailableDetail(ctx context.Context) (ok bool, detail string)
• func Decode(ctx context.Context, ref, patch []byte) ([]byte, error)
• func DecodeFull(data []byte) ([]byte, error)
• func Encode(ctx context.Context, ref, target []byte, opts EncodeOpts) ([]byte, error)
• func EncodeFull(target []byte, opts EncodeOpts) ([]byte, error)
• type EncodeOpts

Variables

var ErrZstdBinaryMissing = &zstdErr{
	msg:    "zstd binary required but unavailable",
	action: "install zstd 1.5+ (brew install zstd / apt install zstd)",
}

var ErrZstdEncodeFailure = &zstdErr{
	msg:    "zstd encode failed",
	action: "re-run with --log-level=debug for zstd stderr capture",
}

Functions

func Available

func Available(ctx context.Context) (ok bool, reason string)

Available reports whether zstd >= 1.5 is usable for patch-from encode/decode. Each call does a fresh LookPath + `zstd --version`; callers invoke Available at most once per top-level operation, so process-wide caching isn't worth the concurrency hazard.

func AvailableDetail

func AvailableDetail(ctx context.Context) (ok bool, detail string)

func Decode

func Decode(ctx context.Context, ref, patch []byte) ([]byte, error)

Decode reads a zstd frame produced by Encode and returns the original target bytes. ref must be byte-identical to the ref used at encode time. Callers are expected to verify the decoded bytes against the content digest recorded in the sidecar. ctx cancellation kills the zstd subprocess.

func DecodeFull

func DecodeFull(data []byte) ([]byte, error)

DecodeFull reads a standalone zstd frame. WithDecoderMaxWindow=1<<31 admits any Phase 4-emitted frame; smaller windows still allocate only their declared size.

func Encode

func Encode(ctx context.Context, ref, target []byte, opts EncodeOpts) ([]byte, error)

Encode produces a zstd frame using --patch-from=ref that decodes to target. An empty target returns a precomputed empty frame to avoid invoking the CLI on a degenerate case that crashes older zstd builds. ctx cancellation kills the zstd subprocess. EncodeOpts tunes level and window; zero-valued opts reproduce Phase-3 byte-identical output.

func EncodeFull

func EncodeFull(target []byte, opts EncodeOpts) ([]byte, error)

EncodeFull compresses target as a standalone zstd frame. Zero-valued EncodeOpts reproduces the historical -3 --long=27 default.

Types

type EncodeOpts

type EncodeOpts struct {
	// Level is the zstd compression level (1..22). Zero means level 3.
	Level int
	// WindowLog is log2 of the long-mode window in bytes (10..31).
	// Zero means 27 (128 MiB), the historical Phase-3 cap.
	WindowLog int
}

EncodeOpts tunes the producer-side zstd parameters. A zero value requests the historical Phase-3 defaults (level 3, --long=27) so existing callers and existing fixtures keep their byte-for-byte outputs.