Struct DecodeContext 

pub struct DecodeContext<'a> { /* private fields */ }

Shared monotonic decode state.

Implementations

impl<'a> DecodeContext<'a>

pub fn new( arena: &'a DecodeArena, policy: &DecodePolicy, depth: DecodeDepth, ) -> Self

Creates one session before input acquisition and detection.

pub fn for_loaded_input( arena: &'a DecodeArena, policy: &DecodePolicy, input_bytes: u64, ) -> Result<Self, CodecError>

Starts post-decode processing with the measured byte length of an already loaded input. This admits the input-proportional allowances without keeping another copy of the source bytes. Format-declared counts must not be used as the input length.

pub fn read_root( reader: &mut dyn ReadSeek, arena: &'a DecodeArena, policy: &DecodePolicy, depth: DecodeDepth, ) -> Result<(Self, View<'a>), CodecError>

Reads the root input under max_input_bytes, copies it into the arena, registers the root space, establishes input-proportional allowances, and returns the context and root view.

pub fn from_root_bytes( bytes: &'a [u8], arena: &'a DecodeArena, policy: &DecodePolicy, ) -> Result<(Self, View<'a>), CodecError>

Builds a full-depth context over caller-owned root bytes, for fuzz targets and tests. The arena still backs any expansions produced during decode.

pub fn from_root_bytes_at( bytes: &'a [u8], arena: &'a DecodeArena, policy: &DecodePolicy, depth: DecodeDepth, ) -> Result<(Self, View<'a>), CodecError>

Builds a context over caller-owned root bytes that requests depth.

pub fn from_root_bytes_limit( bytes: &'a [u8], arena: &'a DecodeArena, policy: &DecodePolicy, ) -> Result<(Self, View<'a>), ResourceLimit>

Builds a full-depth root context with a resource-only refusal channel.

pub fn policy(&self) -> &DecodePolicy

Returns the decode policy in force.

pub fn depth(&self) -> DecodeDepth

Returns the depth the caller requested.

pub fn container_only(&self) -> bool

Returns whether the caller requested only the container layer.

pub fn per_expand_allowance(&self) -> u64

The largest size one expansion may declare: the smaller of max_decompressed_bytes_per_expand and its input-proportional allowance.

A codec compares a declared expansion size against it before DecodeContext::begin_expand, so a declared size above it is a per-input bound that skips one member instead of fusing the session.

pub fn retain_bytes( &self, bytes: u64, operation: &'static str, ) -> Result<(), CodecError>

Charges bytes that decoded output keeps for the rest of the session.

This is the one retained-bytes chokepoint: native record text, arena buffers, and retained copies of source bytes call it. Temporary and derived storage is not charged.

pub fn retained_bytes_available(&self) -> u64

Retained bytes the session can still afford: the retained-byte allowance (the smaller of max_retained_bytes and the input-proportional allowance) minus the bytes already retained, or zero after a refusal fused the session.

A codec uses this only to decide whether to skip optional enrichment before it builds the enrichment, and reports the skip as a loss. It does not reserve anything: the bytes the codec keeps are still charged through DecodeContext::retain_bytes, which can still refuse.

pub fn alloc_filled<T: Clone>( &self, count: usize, value: T, operation: &'static str, ) -> Result<Vec<T>, CodecError>

Allocates count copies of value with fallible allocation.

Use this instead of vec![value; parsed_count] for a count read from the input; validate the count against the bytes it describes first (View::counted, bounded_len).

pub fn charge_entities( &self, count: u64, operation: &'static str, ) -> Result<(), CodecError>

Charges admitted entities.

pub fn admit_entities( &self, current: u64, admitted: &mut u64, operation: &'static str, ) -> Result<(), CodecError>

Charges entities newly present since admitted, then advances admitted.

Codecs call this at admission boundaries so max_entities refuses further work instead of only reporting after a finished IR is built.

pub fn enter_nested( &self, operation: &'static str, ) -> Result<DepthGuard<'_>, CodecError>

Enters one recursive nesting level until the returned guard is dropped.

pub fn enter_nested_limit( &self, operation: &'static str, ) -> Result<DepthGuard<'_>, ResourceLimit>

Enters one nesting level with a resource-only refusal.

pub fn resource_refusal(&self) -> Option<ResourceLimit>

Returns the resource refusal that has fused this decode session.

pub fn begin_expand( &self, spec: ExpandSpec, ) -> Result<ExpandWriter<'_, 'a>, CodecError>

Begins an expansion whose output is charged incrementally and becomes available only after successful finalization.

pub fn concat_views(&self, inputs: &[View<'_>]) -> Result<View<'a>, CodecError>

Copies several input extents into one derived view.

pub fn concat_retained( &self, inputs: &[Vec<u8>], operation: &'static str, ) -> Result<Vec<u8>, CodecError>

Concatenates owned chunks into one retained buffer without an arena copy.

pub fn register_slice<'v>( &self, parent: View<'v>, range: ByteRange, ) -> Result<View<'v>, CodecError>

Registers a stored (uncompressed) child range as a space that borrows the parent bytes without copying.

range is expressed in the parent view’s own space coordinates and must lie within the parent window; a range that escapes the parent is refused here, at the request site, exactly as View::child refuses. No bytes are copied. It is the archive-entry counterpart of DecodeContext::begin_expand — stored ZIP entries take this path, compressed ones take the expander. Registration still refuses on a fused context so a stored entry cannot be admitted after a refusal.

pub fn finish_session(self) -> Result<(), CodecError>

Closes a decode or inspection session, returning a fused resource error even when codec code swallowed the charge that caused it.

impl DecodeContext<'_>

pub fn inflate_probe( &self, source: View<'_>, cap: usize, zlib: bool, ) -> Result<Option<Vec<u8>>, CodecError>

Inflates one raw or zlib member up to cap. An oversized or malformed member supplies no evidence. Resource refusals remain typed.

impl DecodeContext<'_>

pub fn read_input_prefix( &self, reader: &mut dyn Read, length: usize, ) -> Result<Vec<u8>, CodecError>

Reads at most length bytes and admits each copied byte before growth. Input storage is governed by the input-byte dimension.

pub fn extend_input_prefix( &self, reader: &mut dyn Read, bytes: &mut Vec<u8>, length: usize, ) -> Result<(), CodecError>

Extends admitted input storage up to a total bounded length.

pub fn complete_input( &self, reader: &mut dyn Read, bytes: &mut Vec<u8>, ) -> Result<(), CodecError>

Acquires the remaining input without reading or charging the prefix twice.

pub fn refuse_input_limit( &self, additional: u64, operation: &'static str, ) -> CodecError

Raises a typed input-byte refusal without changing its dimension.

impl DecodeContext<'_>

pub fn parse_xml<'input>( &self, text: &'input str, operation: &'static str, ) -> Result<Document<'input>, CodecError>

Parses XML with DTD processing disabled and charges its node depth. The scan bounds the storage that roxmltree reserves and copies, and the rest of the per-expansion allowance limits its nodes.

pub fn parse_json_value( &self, text: &str, operation: &'static str, ) -> Result<Value, CodecError>

Parses a JSON value tree after charging its nesting depth.

pub fn parse_json<T: DeserializeOwned>( &self, text: &str, operation: &'static str, ) -> Result<T, CodecError>

Parses a type with a derived Deserialize after charging the source’s nesting depth. Its storage is bounded as a serde_json::Value tree of the same text.

impl DecodeContext<'_>

pub fn utf16le_text( &self, bytes: &[u8], units: usize, trim_nul: bool, _operation: &'static str, ) -> Result<String, CodecError>

Decodes units UTF-16LE code units, rejecting unpaired surrogates.

pub fn utf16le_lossy_text( &self, bytes: &[u8], units: usize, trim_nul: bool, _operation: &'static str, ) -> Result<String, CodecError>

Decodes units UTF-16LE code units, replacing unpaired surrogates with U+FFFD.

impl<'input> DecodeContext<'input>

pub fn open_zstd<'ctx>( &'ctx self, source: View<'input>, ) -> Result<ZstdDecoder<'ctx, 'input>, CodecError>

Inspects all frame windows before allocating a decoder. The output each frame’s decoder buffers, its window or its declared content size when that is smaller, must fit the per-expansion decompression allowance, and the declared window must fit the decoder’s. Either excess is CodecError::NotImplemented for this stream and leaves the session open, since nothing was allocated.

Trait Implementations

impl<'a> Debug for DecodeContext<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.