Struct DecodeContext 

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

Shared monotonic decode state.

Implementations

impl<'a> DecodeContext<'a>

pub fn with_companions(self, companions: &'a dyn Companions) -> Self

Attaches the source of the files that the input names.

pub fn open_companion( &self, anchor: Option<&str>, path: &str, ) -> Result<CompanionLoad<'a>, CodecError>

Opens the file that path names, relative to the file that anchor identifies, charges its length to the input budget, and places its content in a derived space.

pub fn locate_companion( &self, anchor: Option<&str>, path: &str, ) -> Result<String, String>

The identity of the file that path names, relative to the file that anchor identifies, without reading the file. The error is the reason that the file is not located.

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 with_arena<'b, T>( &self, arena: &'b DecodeArena, work: impl FnOnce(&DecodeContext<'b>) -> T, ) -> T

Runs work in a caller-owned arena and commits all resource state. The arena can be dropped after the returned owned value no longer needs it. Charges, refusal state, address spaces and trace order remain cumulative.

pub fn retained_allowance(&self) -> u64

Reads an optional-enrichment allowance whose threshold decisions are recorded with Self::observe_retained_allowance.

pub fn observe_retained_allowance(&self, remaining: u64, requested: u64)

Records a threshold decision against a previously read allowance. Each optional-output decision must be recorded. This also marks the preceding retained_bytes_available read as a threshold observation.

pub fn checkpoint(&self) -> DecodeCheckpoint

Captures the current counters without sharing mutable decode state.

pub fn take_trace(&self) -> DecodeTrace

Ends recording for a task started with DecodeCheckpoint::resume.

pub fn accept_trace(&self, trace: &DecodeTrace) -> bool

Applies a task’s operations as one transaction.

Returns false without changing this context if a charge refuses, a budget observation changes, or derived address spaces need rebinding. The caller must then execute the task against this context. This also preserves budget-dependent optional output and the exact refusal site.

pub fn accept_trace_rebinding( &self, trace: &DecodeTrace, rebind: impl FnOnce(&DecodeSpaceRebinding) -> bool, ) -> bool

Applies a task’s operations and rebinds its owned address-space IDs.

rebind runs after all resource checks pass. It must rebind each escaped task-owned space and return true, or return false with the output unchanged. A false result leaves this context unchanged. A resource refusal requires the caller to execute the task at its composition position.

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.