Module codec 

Codec registry — dispatches compression/decompression by codec id.

Each drop record carries a representation triple (codec, aead, ec). This module centralises codec dispatch behind a Codec trait and a CodecRegistry, so adding a codec is a new file + one registration call (open/closed). The existing free functions compress and decompress remain as thin wrappers around the default registry.

Supported codecs

Id	Name	Encode	Decode	Notes
0x00	store	yes (identity)	yes	No compression
0x01	lz4	yes (lz4_flex)	yes	Fast baseline; pure Rust
0x02	zstd	yes (ruzstd Fastest)	yes (ruzstd)	Pure Rust; ZSTD level 1
0x03	xz	yes (omnizip-lzma)	yes (omnizip-lzma)	LZMA2 in XZ container
0x04	brotli	yes (brotli q11)	yes (brotli)	Best ratio; pure Rust
0x05	deflate	yes (miniz_oxide)	yes (miniz_oxide)	RFC 1951; universal interop; pure Rust
0x06	snappy	yes (omnizip-snappy)	yes (omnizip-snappy)	Google’s high-speed codec; pure Rust

100% pure Rust. No C libraries. Air-gapped safe.

Modules

fsst_brotli

FSST + Brotli composite codec (id 0x09).

zstd_dict

ZSTD dictionary codec operations.

Structs

CodecRegistry

Process-wide registry of codecs, keyed by codec id.

CodecTunables

Codec-agnostic tunables. Every codec reads only the fields it understands; the rest are ignored. The struct is the single source of truth for “what knobs does the writer want to turn” — adding a new knob is one field here, not a new compress_with_* function per codec (OCP).

Constants

CODEC_BCJ_ARM64_LZ4

Codec id 0x23: BCJ-ARM64 filter + LZ4. For AArch64 executables.

CODEC_BCJ_ARM64_ZSTD

Codec id 0x24: BCJ-ARM64 filter + ZSTD.

CODEC_BCJ_X86_LZ4

Codec id 0x20: BCJ-x86 filter + LZ4. For x86/x86_64 executables.

CODEC_BCJ_X86_ZSTD

Codec id 0x21: BCJ-x86 filter + ZSTD.

CODEC_BITSHUFFLE_LZ4

Codec id 0x0F: Bitshuffle+LZ4 (BLOSC2 bit-shuffle + LZ4 back-end).

CODEC_BLOSC2_SHUFFLE_LZ4

Codec id 0x0A: BLOSC shuffle + LZ4 for scientific float data.

CODEC_BROTLI

Codec id 0x04: Brotli frame format (brotli, pure Rust). Encode at quality 11 (best ratio); decode at any quality.

CODEC_BZIP2

Codec id 0x10: BZip2.

CODEC_DEFLATE

Codec id 0x05: DEFLATE stream format (miniz_oxide, pure Rust). Raw RFC 1951 inside a zlib wrapper (RFC 1950).

CODEC_DEFLATE64

Codec id 0x11: Deflate64 (ZIP method 9, 64 KB window).

CODEC_FLAC

Codec id 0x07: FLAC for PCM audio. RESERVED — pending omnizip-flac encoder port. The wrapper at codec::flac::FlacCodec returns UnsupportedFeature until the real codec lands.

CODEC_FSST_BROTLI

Codec id 0x09: FSST + Brotli composite for CSV/JSON.

CODEC_GLZA

Codec id 0x0D: GLZA grammar-based LZ.

CODEC_LIBDEFLATE

Codec id 0x14: libdeflate-compatible DEFLATE (pure-Rust port). Wire-compatible with CODEC_DEFLATE (0x05) — both are RFC 1951 DEFLATE wrapped in RFC 1950 zlib. Different implementation: omnizip-libdeflate is omnizip’s in-house pure-Rust port (LZ77 + fixed-Huffman + canonical Huffman inflate), focused on decode speed; omnizip-deflate (0x05) wraps miniz_oxide.

CODEC_LZ4

Codec id 0x01: LZ4 block format (lz4_flex, pure Rust).

CODEC_LZ4_HC

Codec id 0x13: LZ4 HC (hash-chain match finder + lazy parsing). Real encoder from omnizip-lz4 0.14.1; was a stub in 0.13.1.

CODEC_PPMD

Codec id 0x0C: PPMd (dormant — raw fallback).

CODEC_PPMD8

Codec id 0x12: PPMd8 (RESTART + RLE, user-tunable memory budget).

CODEC_REFERENCED

Codec id 0xFE: REFERENCED. Sentinel codec id for drops that are not stored in this image’s slabs — the bytes live in a base image and the reader resolves them via the overlay chain.

CODEC_RICEPP

Codec id 0x08: Rice++ for FITS / scientific integer-pixel images. RESERVED — pending omnizip-ricepp encoder port.

CODEC_SHUFFLE_ZSTD

Codec id 0x0E: Shuffle+Zstd (BLOSC2 byte-shuffle + Zstd back-end).

CODEC_SNAPPY

Codec id 0x06: Snappy format (omnizip-snappy → snap, pure Rust). No compression levels; ~500 MB/s encode and decode.

CODEC_STORE

Codec id 0x00: store (no compression).

CODEC_XZ

Codec id 0x03: XZ/LZMA2 format via omnizip-lzma.

CODEC_ZPAQ

Codec id 0x0B: ZPAQ context-mixing archiver.

CODEC_ZSTD

Codec id 0x02: Zstandard frame format (ruzstd, pure Rust). Encode uses CompressionLevel::Fastest (ZSTD level 1); decode supports any level the reference encoder can produce.

Traits

Codec

The behaviour every compression codec implements. New codecs register a Codec impl with CodecRegistry::register; the dispatch code never changes.

PerCodecTunables

Optional trait: codecs with strongly-typed per-codec tunables.

Functions

best_binary_codec

Returns the best available codec for binary content classes (structured binary — ELF, Mach-O, PE, object files, etc.).

best_compressible_codec

Returns the best available codec for compressible content classes (Text, Code). Brotli q5 is the current default — beats ZSTD L6 (omnizip 0.7+) on real source code in our benchmarks. Try switching to CODEC_ZSTD if ZSTD’s level differentiation improves enough to beat Brotli; the change is one line.

codec_name

Human-readable name for a registered codec id, e.g. for CLI inspection output.

compress

Compress plaintext using the codec identified by codec_id, via the process-wide default CodecRegistry.

compress_brotli

Compress with Brotli at quality 11 (best ratio).

compress_brotli_with_quality

Compress with Brotli at an explicit quality (0–11). Quality 0 is the fastest; quality 11 is the reference encoder’s maximum.

compress_deflate

Compress with DEFLATE at level 6 (default). Output is a zlib-framed DEFLATE stream (RFC 1950) decodable by any zlib decoder (gzip -d, zlib.decompress, etc.).

compress_lz4_with_size

Compress with LZ4, prepending the original size as a 4-byte LE header. Routes through omnizip-lz4::Lz4FastCodec so callers stay first-party (omnizip) for the codec implementation.

compress_with_options

Compress with a quality/level hint. For codecs that support a quality parameter (Brotli, ZSTD), this overrides the default. For codecs without quality control (LZ4, Store, Snappy), the hint is silently ignored.

compress_with_tunables

Compress plaintext with the given codec and tunables. Codecs that don’t override compress_with_tunables on the Codec trait fall back to plain compress.

compress_zstd

Compress with Zstandard at CompressionLevel::Fastest (ZSTD level 1). The output is a standard ZSTD frame decodable by any conformant ZSTD decoder.

decompress

Decompress compressed using the codec identified by codec_id, via the process-wide default CodecRegistry. The expected_len is the plaintext_len from the drop record; the decompressed output MUST match it exactly.