Module skippable 

Available on crate feature lsm only.

Typed Rust API for zstd skippable frames (RFC 8878 §3.1).

Skippable frames carry an arbitrary application payload alongside a zstd data stream. Spec layout, byte-compatible with donor ZSTD_writeSkippableFrame (lib/compress/zstd_compress.c:4751-4763 in zstd v1.5.7):

+----------+-----------+----------------+
| 4 bytes  | 4 bytes   | payload bytes  |
| magic LE | length LE | (size = length)|
+----------+-----------+----------------+

• magic = 0x184D2A50 + magic_variant, with magic_variant in 0..=15 — 16 application-claimed magic numbers in the skippable-magic range 0x184D2A50..=0x184D2A5F.
• length is the payload byte count as a little-endian u32, so payloads above u32::MAX are not representable on the wire (the validation in SkippableFrame::new / write_skippable_frame surfaces this as SkippableFrameError::PayloadTooLarge).

Primary use case

Embedded metadata sidecars in storage formats. The first canonical consumer is the lsm-tree v1 encrypted wire format (https://github.com/structured-world/coordinode-lsm-tree), which stacks MetadataFrame / BodyFrame / EccFrame skippable frames around an inner zstd frame. Any storage-format author needing to interleave metadata with zstd data can use the same shape — the API takes a generic magic_variant: u8 and leaves the per-variant semantics to the application.

Magic variant allocation policy

Magic variants 0x184D2A50..=0x184D2A5F are an application-protocol concern, NOT a structured-zstd concern. This crate accepts magic_variant: u8 in 0..=15 and validates only that bound. No per-variant constants are baked into the source — applications are responsible for documenting which variants they claim and coordinating with other ecosystem consumers to avoid collisions.

The ecosystem registry of known allocations and the policy for claiming new ones lives in docs/SKIPPABLE_MAGIC_ALLOCATIONS.md.

Structs

SkippableFrame

A typed skippable-frame value.

Enums

DecodeSkippableFrameError

Errors surfaced when reading a SkippableFrame from a stream.

SkippableFrameError

Errors surfaced when constructing or writing a SkippableFrame.

Constants

SKIPPABLE_HEADER_SIZE

Number of bytes the skippable-frame header occupies on the wire: 4 bytes magic + 4 bytes length.

SKIPPABLE_MAGIC_MAX_VARIANT

Upper bound on the variant nibble. Variants are constrained to the low 4 bits of the magic number so SKIPPABLE_MAGIC_START + variant stays inside the spec’s 0x184D2A50..=0x184D2A5F band.

SKIPPABLE_MAGIC_START

First magic number in the skippable-frame range (RFC 8878 §3.1.2). Variants 0..=15 correspond to magics in [0x184D2A50, 0x184D2A5F].

Functions

write_skippable_frame

Free function for callers that want to write a skippable frame directly into a sink without constructing a temporary SkippableFrame. Shape mirrors donor ZSTD_writeSkippableFrame(dst, dstCapacity, src, srcSize, magicVariant) — same validation, same byte-level output.