structured-zstd 0.0.31

[package]
name = "structured-zstd"
version = "0.0.31"
rust-version = "1.92"
authors = [
    "Moritz Borcherding <moritz.borcherding@web.de>",
    "Structured World Foundation <foundation@sw.foundation>",
]
edition = "2024"
license = "Apache-2.0"
homepage = "https://github.com/structured-world/structured-zstd"
repository = "https://github.com/structured-world/structured-zstd"
description = "Pure Rust zstd implementation — managed fork of ruzstd. Dictionary decompression, no FFI."
exclude = ["fuzz_decodecorpus/*", "decodecorpus_files/*", "dict_tests/files/**"]
# Package metadata points at a crate-local symlink so the packaged crate and repo root README stay in sync.
readme = "README.md"
keywords = ["zstd", "zstandard", "decompression", "compression", "pure-rust"]
categories = ["compression"]

# docs.rs builds the crate with the public feature set so feature-gated
# items (e.g. the `dictionary` module behind `dict_builder`) appear in the
# published documentation. We list the public features explicitly rather
# than using `all-features = true` because the manifest also exposes
# `rustc-dep-of-std` (libstd-build-only — swaps in `rustc-std-workspace-*`
# crates), `bench_internals` (widens the API surface for benches), and
# `fuzz_exports` (widens it for fuzz targets); none of these should appear
# on docs.rs. The `--cfg docsrs` flag activates the
# `#[cfg_attr(docsrs, doc(cfg(...)))]` annotations that render feature
# badges on each item.
[package.metadata.docs.rs]
features = ["std", "hash", "dict_builder", "lsm"]
rustdoc-args = ["--cfg", "docsrs"]

[dependencies]
# Locked behind the `hash` feature flag
twox-hash = { version = "2.0", default-features = false, features = ["xxhash64"], optional = true }
fastrand = {version = "2.3.0", optional = true }
# Optional sync primitive for the FSE default-table cache on no-atomic
# targets (Cortex-M0/M0+, AVR, MSP430 — anywhere `target_has_atomic =
# "ptr"` is false). When this feature is enabled the cache uses a
# critical-section-protected `static mut` slot; when disabled the
# no-atomic build skips the cache entirely and returns an owned
# `Box<FSETable>` per call, dropped with the owning `FrameCompressor`
# (no leak — same memory shape as the pre-cache status quo on those
# targets). On targets with atomic pointer support (every modern
# desktop / server / mobile / Cortex-M3+ / RISC-V-A target) the dep
# is dead code and never instantiated — those targets use the lock-
# free `AtomicPtr` path unconditionally.
critical-section = { version = "1.2", optional = true }

# Internal feature, only used when building as part of libstd, not part of the
# stable interface of this crate.
compiler_builtins = { version = "0.1.2", optional = true }
core = { version = "1.0.0", optional = true, package = "rustc-std-workspace-core" }
alloc = { version = "1.0.0", optional = true, package = "rustc-std-workspace-alloc" }

[dev-dependencies]
criterion = "0.8"
rand = "0.10"
zstd = { version = "0.13.3", features = ["zdict_builder", "experimental"] }

[features]
default = [
    "hash",
    "std",
    "kernel_scalar",
    "kernel_sse2",
    "kernel_bmi2",
    "kernel_avx2",
    "kernel_vbmi2",
    "kernel_neon",
    "kernel_sve",
    "kernel_simd128",
]
# Per-CPU-tier decode kernel selection. The default build enables every
# kernel; with `std`, `detect_cpu_kernel()` picks the best tier at runtime
# (CPU-feature detection) — a universal binary that adapts to any CPU. On
# `no_std` the tier is fixed at compile time from `target_feature`, baking
# the chosen ISA into the build. Constrained targets can trim the SIMD trampolines + their
# dispatch arms by disabling the tiers they don't need; the scalar kernel
# is always compiled as the fallback, so the lowest enabled tier always has
# a backstop. Each feature only affects builds for its architecture (a
# `kernel_avx2` flag is inert on aarch64, `kernel_neon` inert on x86), so
# the all-on default is safe everywhere. The implication chain mirrors the
# real ISA dependency: AVX2 implies BMI2 implies SSE2; SVE implies NEON.
# `kernel_scalar` is a marker only: the scalar kernel is compiled
# unconditionally (it is the mandatory fallback), so this flag gates no code.
# It exists so the scalar tier can be named explicitly in a feature set; a
# scalar-only build is equivalently `--no-default-features` (no SIMD tier
# enabled) or `--no-default-features --features kernel_scalar`.
kernel_scalar = []
kernel_sse2 = []
kernel_bmi2 = ["kernel_sse2"]
kernel_avx2 = ["kernel_bmi2"]
kernel_vbmi2 = ["kernel_avx2"]
kernel_neon = []
kernel_sve = ["kernel_neon"]
# WebAssembly fixed-128-bit SIMD tier (`simd128`). Inert on non-wasm targets
# the same way `kernel_neon` is inert on x86. wasm has no runtime CPU
# detection, so the tier is chosen at compile time from `target_feature =
# "simd128"`; consumers build with `-C target-feature=+simd128`. Covers the
# two 128-bit-class kernels that port directly (row tag-scan, match-copy);
# the 256-bit (AVX2/VBMI2) and scalar-bit-manip (BMI2) kernels have no
# simd128 equivalent and stay scalar on wasm.
kernel_simd128 = []
dict_builder = ["std", "dep:fastrand"]
hash = ["dep:twox-hash"]
# Opt-in cache for FSE default tables on no-atomic targets. See
# `fse_encoder::default_*_table` for the implementation split. On
# targets with atomic pointer support this feature is a no-op.
critical-section = ["dep:critical-section"]
bench_internals = []
fuzz_exports = []
std = []
# Diagnostic-only: atomic histograms of the match/literal copy shape on the
# decode path (call counts + size buckets + requested-vs-overshoot byte
# totals). Off in every shipping / bench build (zero codegen impact). Enabled
# by the `copy_shape` example to capture the copy-call distribution, which is
# deterministic from the compressed input and therefore architecture-
# independent (only the per-call timing is CPU-tier specific).
copy_shape_stats = ["std"]
# Diagnostic tracing of the Fast kernel's inner loop — per-iteration state
# dumps gated at compile time so production builds carry zero cost. Runtime
# activation via `STRUCTURED_ZSTD_KERNEL_TRACE=1` env var. Used by the
# `trace_fast_kernel` example for #220 ratio-divergence investigation.
kernel_trace = ["std"]
# Opt-in storage-format extensions: typed Rust APIs that downstream
# storage / wire-format consumers (lsm-tree, future graph stores) can
# layer on top of the spec-mandated zstd decoder behaviour. Default
# off, no C FFI symbols added regardless of this feature's state.
# Currently exposes:
# - expected-field validation setters on `FrameDecoder`
#   (`expect_dict_id` / `expect_window_descriptor`) for wire-format
#   consumers that need post-AEAD-decrypt sanity checks against a
#   pinned `dict_id` / `window_descriptor`.
# - typed `SkippableFrame` builder + `write_skippable_frame` free
#   function in `zstd::skippable` for RFC 8878 §3.1 skippable
#   frames (16-variant magic + 4-byte LE length + payload).
# Other typed APIs land here over time as bilateral storage-format
# work expands the surface.
lsm = []

# Internal feature, only used when building as part of libstd, not part of the
# stable interface of this crate.
rustc-dep-of-std = ["dep:compiler_builtins", "dep:core", "dep:alloc"]

# Diagnostic example: only buildable with the copy-shape counters compiled
# in, so `--all-targets` on the default feature set skips it (the
# `shape_stats` re-export is feature-gated).
[[example]]
name = "copy_shape"
required-features = ["copy_shape_stats", "dict_builder"]

[[bench]]
name = "decode_all"
harness = false

[[bench]]
name = "huf_decode_kernels"
harness = false

[[bench]]
name = "compare_ffi"
harness = false
required-features = ["dict_builder"]

[[bench]]
name = "compare_ffi_memory"
harness = false
required-features = ["dict_builder"]

[[bench]]
name = "compare_ffi_sequences"
harness = false
required-features = ["dict_builder", "bench_internals"]

[[bench]]
name = "bitstream"
harness = false
required-features = ["bench_internals"]

[[bench]]
name = "dict_builder_fastcover"
harness = false
required-features = ["dict_builder"]

[[bench]]
name = "decode_dict_handle"
harness = false

[[bench]]
name = "wildcopy_candidates"
harness = false
required-features = ["bench_internals"]

[[test]]
name = "block_splitter_donor_parity"
required-features = ["bench_internals"]