silk/zstd

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Bounded, resumable Zstandard decoding into caller-owned byte slices.

When to use

Use Zstd for RFC 8878 files or HTTP zstd content. The decoder accepts all non-dictionary block modes. Use Zstd.make to allocate state, then step until the result reports Finished.

Details

Input and output are borrowed only for one call. State owns its history and scratch storage. Limits apply across all concatenated regular and skippable frames. A frame boundary is not end of input. The first final call fixes the input end. Later calls must supply its unconsumed suffix with final input set.

Gotchas

Output is provisional until Finished: a later checksum or truncated trailer can invalidate earlier output. A failure is terminal. Drop the decoder to release its storage and construct another decoder for another stream.

Import as Zstd with import silk.zstd { Zstd }.

Public declarations: 6.

ZstdLimits

pub struct ZstdLimits

Resource limits for one complete concatenated input stream.

Field inputBytes

pub inputBytes: u64

Maximum consumed bytes, including headers, trailers, and skipped bytes.

Field outputBytes

pub outputBytes: u64

Maximum decoded bytes across all regular frames.

Field frames

pub frames: u64

Maximum regular and skippable frame count combined.

Field skippableBytes

pub skippableBytes: u64

Maximum skipped payload bytes across all skippable frames.

Field windowBytes

pub windowBytes: usize

Maximum advertised window and exact allocated history capacity.

Field workspaceBytes

pub workspaceBytes: usize

Maximum non-window workspace, including staging, state, and bounded entropy scratch.

Associated function ZstdLimits.make

pub fn make() -> ZstdLimits

Returns limits of 64 MiB input, 256 MiB output, 1024 frames, 8 MiB skipped bytes and window, and 1 MiB workspace.

ZstdStatus

pub enum ZstdStatus

The resource needed to continue, or successful end of the complete input.

NeedInput

NeedInput = 0

The supplied input is exhausted; supply more input or declare its end.

NeedOutput

NeedOutput = 1

Pending decoded bytes need output space; supply a nonempty output slice.

Finished

Finished = 2

Final input ended after complete frame and trailer validation.

ZstdProgress

pub struct ZstdProgress

Exact progress made by one successful step.

Field consumed

pub consumed: usize

Input bytes consumed by this call; resubmit only the remaining suffix.

Field written

pub written: usize

Output bytes written by this call; only this prefix of the destination was changed.

Field status

pub status: ZstdStatus

The required next resource or terminal completion.

ZstdReason

pub enum ZstdReason

A precise category of decoder failure.

None

None = 0

No failure; used only by live internal state.

InvalidConfiguration

InvalidConfiguration = 1

Configuration cannot represent the required storage.

InvalidState

InvalidState = 2

A call changes an established final input boundary or adds input after completion.

InvalidMagic

InvalidMagic = 3

Input does not start with a regular or skippable frame magic number.

ReservedFrame

ReservedFrame = 4

The reserved frame-header bit is set.

ReservedBlock

ReservedBlock = 5

A block uses the reserved block type.

BlockSize

BlockSize = 6

A block exceeds the frame block maximum or has an invalid size.

MalformedBlock

MalformedBlock = 7

Entropy data or a match sequence is invalid; inspect the block reason.

UnsupportedDictionary

UnsupportedDictionary = 8

A frame requests a nonzero dictionary ID.

Truncated

Truncated = 9

Final input ends before a complete stream is available.

Checksum

Checksum = 10

The frame checksum differs from seed-zero XXH64 of its decoded bytes.

ContentSize

ContentSize = 11

Decoded frame length differs from its declared content size.

InputLimit

InputLimit = 12

Cumulative input exceeds its configured limit.

OutputLimit

OutputLimit = 13

Cumulative decoded output exceeds its configured limit.

FrameLimit

FrameLimit = 14

The combined regular and skippable frame count exceeds its limit.

SkippableLimit

SkippableLimit = 15

Cumulative skipped payload bytes exceed their limit.

WindowLimit

WindowLimit = 16

The advertised frame window exceeds the configured history capacity.

WorkspaceLimit

WorkspaceLimit = 17

The configured workspace budget cannot hold bounded decoder storage.

ZstdError

pub struct ZstdError

A terminal decoding failure with exact progress and location.

Details

consumed and written describe this call, including progress before failure. Previously written bytes remain provisional. Repeated calls return the same reason and offset with zero progress.

Field reason

pub reason: ZstdReason

The category that stopped decoding.

Field blockReason

pub blockReason: BlockReason

The compressed-block category, or None for framing and resource failures.

Field offset

pub offset: u64

The cumulative consumed input position where failure was detected.

Field consumed

pub consumed: usize

Input bytes consumed during this call before failure.

Field written

pub written: usize

Output bytes written during this call before failure.

Zstd

pub struct Zstd

An owned, allocation-free-after-construction decoder for one concatenated stream.

Details

The state releases all allocations when dropped. It retains neither input nor output borrows between calls. Each regular frame resets its history, entropy tables, and checksum, but cumulative limits do not reset.

Associated function Zstd.make

pub effect<'static> fn make(limits: ZstdLimits) -> Zstd ! ZstdError | OutOfMemoryError ? &mut Allocator

Allocates exact bounded storage and creates a decoder for one complete input stream.

Details

Allocation uses the supplied Allocator. No allocation occurs during step. Storage includes windowBytes, three 128 KiB staging buffers, and bounded state and entropy scratch. A zero window or unrepresentable total size fails before allocation. Insufficient workspace reports WorkspaceLimit.

Method Zstd.step

pub fn step<'life0, 'life1, 'life2>(self: &'life0 mut Zstd, input: &'life1 [u8], output: &'life2 mut [u8], finalInput: bool) -> silk/result.Result<silk/zstd.ZstdProgress, silk/zstd.ZstdError>

Consumes input and writes output until a resource is needed, input finishes, or a typed error occurs.

Details

Resubmit only input[consumed..] and use only output[..written] from each result. A final call fixes the absolute input end. Later calls must supply the complete unconsumed suffix with finalInput true. NeedOutput with an empty destination makes no output progress; provide a nonempty destination before retrying. NeedInput exhausts the input. Finished validates all concatenated frames and permits only empty final retries.

Gotchas

Output can precede a checksum or truncation failure. Do not treat it as validated until Finished. Failure poisons this state. Subsequent calls report the same failure location and make no progress.