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.

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.