Enum DecodeError 

pub enum DecodeError {
    InvalidHeader(WireError),
    BlockTooLarge {
        size: usize,
        offset: usize,
    },
    MissingField {
        block_type: &'static str,
        field_name: &'static str,
        field_id: u64,
    },
    InvalidUtf8 {
        block_type: &'static str,
        field_name: &'static str,
    },
    MissingEndSentinel,
    TrailingData {
        extra_bytes: usize,
    },
    DecompressFailed(String),
    DecompressionBomb {
        actual: usize,
        limit: usize,
    },
    UnresolvedReference {
        hash: [u8; 32],
    },
    MissingContentStore,
    Type(TypeError),
    Wire(WireError),
    Io(Error),
}

Errors that can occur during BCP payload decoding.

The decoder validates at multiple levels: header integrity, block frame structure, TLV body fields, stream termination, decompression, and content store resolution. Each error variant captures enough context for meaningful diagnostics.

Error hierarchy:

  DecodeError
  ├── InvalidHeader(WireError)   ← magic, version, or reserved byte wrong
  ├── BlockTooLarge              ← single block body exceeds size limit
  ├── MissingField               ← required TLV field absent in block body
  ├── InvalidUtf8                ← string field contains non-UTF-8 bytes
  ├── MissingEndSentinel         ← payload ran out without END block
  ├── TrailingData               ← extra bytes after END sentinel
  ├── DecompressFailed           ← zstd decompression error
  ├── DecompressionBomb          ← decompressed size exceeds safety limit
  ├── UnresolvedReference        ← BLAKE3 hash not found in content store
  ├── MissingContentStore        ← IS_REFERENCE block but no store provided
  ├── Type(TypeError)            ← from bcp-types body deserialization
  ├── Wire(WireError)            ← from bcp-wire frame parsing
  └── Io(std::io::Error)         ← from underlying I/O reads

Variants

InvalidHeader(WireError)

The 8-byte file header failed validation.

This wraps a WireError from BcpHeader::read_from — the inner error distinguishes between bad magic, unsupported version, and non-zero reserved byte.

BlockTooLarge

A block body exceeds the maximum allowed size.

Fields

size: usize

offset: usize

MissingField

A required field was missing from a known block type’s body.

This provides richer context than the underlying TypeError::MissingRequiredField by including the block type name and the field’s wire ID.

Fields

block_type: &'static str

field_name: &'static str

field_id: u64

InvalidUtf8

A string field contained invalid UTF-8 bytes.

Fields

block_type: &'static str

field_name: &'static str

MissingEndSentinel

The payload ended without an END sentinel block (type=0xFF).

Every valid BCP payload must terminate with an END block. If the byte stream is exhausted before encountering one, the payload is considered truncated.

TrailingData

Extra bytes were found after the END sentinel.

Per the spec, this is a warning-level condition — the payload decoded successfully, but the trailing data may indicate corruption or a buggy encoder. The decoder captures this as an error variant so callers can decide how to handle it.

Fields

extra_bytes: usize

DecompressFailed(String)

Zstd decompression failed.

Returned when a block’s COMPRESSED flag (bit 1) or the header’s COMPRESSED flag (bit 0) is set and the zstd decoder cannot parse the compressed data. Common causes: truncated input, corrupt frame, or non-zstd data with the flag erroneously set.

DecompressionBomb

Decompressed data exceeds the safety limit.

Prevents decompression bombs — payloads crafted to decompress into vastly larger output. The limit is the caller-configured maximum (default: 16 MiB per block, 256 MiB for whole-payload).

Fields

actual: usize

limit: usize

UnresolvedReference

A block has the IS_REFERENCE flag set but its 32-byte BLAKE3 hash was not found in the content store.

This means the content was previously content-addressed during encoding but the corresponding data was not provided to the decoder’s content store.

Fields

hash: [u8; 32]

MissingContentStore

A block has the IS_REFERENCE flag but no content store was provided to the decoder.

Use [BcpDecoder::decode_with_store] instead of [BcpDecoder::decode] when decoding payloads that contain content-addressed blocks.

Type(TypeError)

A body deserialization error from bcp-types.

This covers missing required fields, unknown wire types, and invalid enum values encountered while parsing TLV fields within a block body.

Wire(WireError)

A wire-level framing error from bcp-wire.

Surfaces when a block frame’s varint is malformed, the body length exceeds the remaining bytes, or other structural issues.

Io(Error)

An I/O error from the underlying reader (streaming decoder).

Trait Implementations

impl Debug for DecodeError

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

Formats the value using the given formatter.

impl Display for DecodeError

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

Formats the value using the given formatter.

impl Error for DecodeError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for DecodeError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<TypeError> for DecodeError

fn from(source: TypeError) -> Self

Converts to this type from the input type.

impl From<WireError> for DecodeError

fn from(source: WireError) -> Self

Converts to this type from the input type.