structured_zstd/decoding/

errors.rs

//! Errors that might occur while decoding zstd formatted data

use crate::bit_io::GetBitsError;
use crate::blocks::block::BlockType;
use crate::blocks::literals_section::LiteralsSectionType;
use crate::io::Error;
use alloc::vec::Vec;
use core::fmt;
#[cfg(feature = "std")]
use std::error::Error as StdError;

#[derive(Debug)]
#[non_exhaustive]
pub enum FrameDescriptorError {
    InvalidFrameContentSizeFlag {
        got: u8,
    },
    /// The descriptor's `Reserved_bit` (bit 3) is set, which a decoder of this
    /// format version must refuse.
    ReservedBitSet,
}

impl fmt::Display for FrameDescriptorError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::InvalidFrameContentSizeFlag { got } => write!(
                f,
                "Invalid Frame_Content_Size_Flag; Is: {got}, Should be one of: 0, 1, 2, 3"
            ),
            Self::ReservedBitSet => write!(
                f,
                "Reserved_bit of the Frame_Header_Descriptor is set; it must be zero"
            ),
        }
    }
}

#[cfg(feature = "std")]
impl StdError for FrameDescriptorError {}

/// Why a frame of the v0.5, v0.6 or v0.7 format could not be decoded.
#[cfg(feature = "legacy")]
#[cfg_attr(docsrs, doc(cfg(feature = "legacy")))]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum LegacyFrameError {
    /// The input ends inside the frame.
    Truncated,
    /// The frame header sets a reserved bit or asks for a window the format
    /// does not allow.
    UnsupportedParameter,
    /// The frame is malformed; `reason` names the structure that is.
    Corrupted {
        /// What failed to decode.
        reason: &'static str,
    },
    /// The output buffer is too small for the frame's content.
    OutputTooSmall,
    /// The dictionary could not be read.
    DictionaryCorrupted,
    /// The frame needs a dictionary with another ID than the one supplied.
    DictionaryMismatch {
        /// The ID the frame names.
        expected: u32,
        /// The ID of the dictionary supplied, 0 for none.
        provided: u32,
    },
    /// The 22-bit content checksum of a v0.7 frame does not match its output.
    ChecksumMismatch {
        /// The value the frame stores.
        expected: u32,
        /// The value computed over the output.
        calculated: u32,
    },
}

#[cfg(feature = "legacy")]
impl LegacyFrameError {
    /// The code libzstd returns for the same failure.
    pub fn code(&self) -> ErrorCode {
        match self {
            LegacyFrameError::UnsupportedParameter => ErrorCode::FrameParameterUnsupported,
            LegacyFrameError::OutputTooSmall => ErrorCode::DstSizeTooSmall,
            LegacyFrameError::DictionaryCorrupted => ErrorCode::DictionaryCorrupted,
            LegacyFrameError::DictionaryMismatch { .. } => ErrorCode::DictionaryWrong,
            LegacyFrameError::ChecksumMismatch { .. } => ErrorCode::ChecksumWrong,
            // A cut frame, as `ZSTD_findFrameSizeInfoLegacy` and the legacy
            // decoders' size checks report it (`srcSize_wrong`).
            LegacyFrameError::Truncated => ErrorCode::SrcSizeWrong,
            LegacyFrameError::Corrupted { .. } => ErrorCode::CorruptionDetected,
        }
    }
}

#[cfg(feature = "legacy")]
impl fmt::Display for LegacyFrameError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Truncated => write!(f, "the input ends inside a v0.5-v0.7 frame"),
            Self::UnsupportedParameter => {
                write!(
                    f,
                    "the v0.5-v0.7 frame header asks for an unsupported setting"
                )
            }
            Self::Corrupted { reason } => write!(f, "corrupt v0.5-v0.7 frame: {reason}"),
            Self::OutputTooSmall => write!(f, "the output buffer is too small for the frame"),
            Self::DictionaryCorrupted => write!(f, "the dictionary could not be read"),
            Self::DictionaryMismatch { expected, provided } => write!(
                f,
                "the frame needs dictionary 0x{expected:X}, the one supplied is 0x{provided:X}"
            ),
            Self::ChecksumMismatch {
                expected,
                calculated,
            } => write!(
                f,
                "content checksum mismatch: frame stored 0x{expected:06X}, decoder calculated 0x{calculated:06X}"
            ),
        }
    }
}

#[cfg(all(feature = "legacy", feature = "std"))]
impl StdError for LegacyFrameError {}

#[derive(Debug)]
#[non_exhaustive]
pub enum FrameHeaderError {
    WindowTooBig { got: u64 },
    WindowTooSmall { got: u64 },
    FrameDescriptorError(FrameDescriptorError),
    DictIdTooSmall { got: usize, expected: usize },
    MismatchedFrameSize { got: usize, expected: u8 },
    FrameSizeIsZero,
    InvalidFrameSize { got: u8 },
}

impl fmt::Display for FrameHeaderError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::WindowTooBig { got } => write!(
                f,
                "window_size bigger than allowed maximum. Is: {}, Should be lower than: {}",
                got,
                crate::common::MAX_WINDOW_SIZE
            ),
            Self::WindowTooSmall { got } => write!(
                f,
                "window_size smaller than allowed minimum. Is: {}, Should be greater than: {}",
                got,
                crate::common::MIN_WINDOW_SIZE
            ),
            Self::FrameDescriptorError(e) => write!(f, "{e:?}"),
            Self::DictIdTooSmall { got, expected } => write!(
                f,
                "Not enough bytes in dict_id. Is: {got}, Should be: {expected}"
            ),
            Self::MismatchedFrameSize { got, expected } => write!(
                f,
                "frame_content_size does not have the right length. Is: {got}, Should be: {expected}"
            ),
            Self::FrameSizeIsZero => write!(f, "frame_content_size was zero"),
            Self::InvalidFrameSize { got } => write!(
                f,
                "Invalid frame_content_size. Is: {got}, Should be one of 1, 2, 4, 8 bytes"
            ),
        }
    }
}

#[cfg(feature = "std")]
impl StdError for FrameHeaderError {
    fn source(&self) -> Option<&(dyn StdError + 'static)> {
        match self {
            FrameHeaderError::FrameDescriptorError(source) => Some(source),
            _ => None,
        }
    }
}

impl From<FrameDescriptorError> for FrameHeaderError {
    fn from(error: FrameDescriptorError) -> Self {
        Self::FrameDescriptorError(error)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum ReadFrameHeaderError {
    MagicNumberReadError(Error),
    BadMagicNumber(u32),
    FrameDescriptorReadError(Error),
    InvalidFrameDescriptor(FrameDescriptorError),
    WindowDescriptorReadError(Error),
    DictionaryIdReadError(Error),
    FrameContentSizeReadError(Error),
    SkipFrame { magic_number: u32, length: u32 },
}

impl fmt::Display for ReadFrameHeaderError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::MagicNumberReadError(e) => write!(f, "Error while reading magic number: {e}"),
            Self::BadMagicNumber(e) => write!(f, "Read wrong magic number: 0x{e:X}"),
            Self::FrameDescriptorReadError(e) => {
                write!(f, "Error while reading frame descriptor: {e}")
            }
            Self::InvalidFrameDescriptor(e) => write!(f, "{e:?}"),
            Self::WindowDescriptorReadError(e) => {
                write!(f, "Error while reading window descriptor: {e}")
            }
            Self::DictionaryIdReadError(e) => write!(f, "Error while reading dictionary id: {e}"),
            Self::FrameContentSizeReadError(e) => {
                write!(f, "Error while reading frame content size: {e}")
            }
            Self::SkipFrame {
                magic_number,
                length,
            } => write!(
                f,
                "SkippableFrame encountered with MagicNumber 0x{magic_number:X} and length {length} bytes"
            ),
        }
    }
}

#[cfg(feature = "std")]
impl StdError for ReadFrameHeaderError {
    fn source(&self) -> Option<&(dyn StdError + 'static)> {
        match self {
            ReadFrameHeaderError::MagicNumberReadError(source) => Some(source),
            ReadFrameHeaderError::FrameDescriptorReadError(source) => Some(source),
            ReadFrameHeaderError::InvalidFrameDescriptor(source) => Some(source),
            ReadFrameHeaderError::WindowDescriptorReadError(source) => Some(source),
            ReadFrameHeaderError::DictionaryIdReadError(source) => Some(source),
            ReadFrameHeaderError::FrameContentSizeReadError(source) => Some(source),
            _ => None,
        }
    }
}

impl From<FrameDescriptorError> for ReadFrameHeaderError {
    fn from(error: FrameDescriptorError) -> Self {
        Self::InvalidFrameDescriptor(error)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum BlockHeaderReadError {
    ReadError(Error),
    FoundReservedBlock,
    BlockTypeError(BlockTypeError),
    BlockSizeError(BlockSizeError),
}

#[cfg(feature = "std")]
impl std::error::Error for BlockHeaderReadError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            BlockHeaderReadError::ReadError(source) => Some(source),
            BlockHeaderReadError::BlockTypeError(source) => Some(source),
            BlockHeaderReadError::BlockSizeError(source) => Some(source),
            BlockHeaderReadError::FoundReservedBlock => None,
        }
    }
}

impl ::core::fmt::Display for BlockHeaderReadError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> ::core::fmt::Result {
        match self {
            BlockHeaderReadError::ReadError(_) => write!(f, "Error while reading the block header"),
            BlockHeaderReadError::FoundReservedBlock => write!(
                f,
                "Reserved block occured. This is considered corruption by the documentation"
            ),
            BlockHeaderReadError::BlockTypeError(e) => write!(f, "Error getting block type: {e}"),
            BlockHeaderReadError::BlockSizeError(e) => {
                write!(f, "Error getting block content size: {e}")
            }
        }
    }
}

impl From<Error> for BlockHeaderReadError {
    fn from(val: Error) -> Self {
        Self::ReadError(val)
    }
}

impl From<BlockTypeError> for BlockHeaderReadError {
    fn from(val: BlockTypeError) -> Self {
        Self::BlockTypeError(val)
    }
}

impl From<BlockSizeError> for BlockHeaderReadError {
    fn from(val: BlockSizeError) -> Self {
        Self::BlockSizeError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum BlockTypeError {
    InvalidBlocktypeNumber { num: u8 },
}

#[cfg(feature = "std")]
impl std::error::Error for BlockTypeError {}

impl core::fmt::Display for BlockTypeError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            BlockTypeError::InvalidBlocktypeNumber { num } => {
                write!(
                    f,
                    "Invalid Blocktype number. Is: {num}. Should be one of: 0, 1, 2, 3 (3 is reserved).",
                )
            }
        }
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum BlockSizeError {
    BlockSizeTooLarge { size: u32 },
}

#[cfg(feature = "std")]
impl std::error::Error for BlockSizeError {}

impl core::fmt::Display for BlockSizeError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            BlockSizeError::BlockSizeTooLarge { size } => {
                write!(
                    f,
                    "Blocksize was bigger than the absolute maximum {} (128kb). Is: {}",
                    crate::common::MAX_BLOCK_SIZE,
                    size,
                )
            }
        }
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum DecompressBlockError {
    BlockContentReadError(Error),
    MalformedSectionHeader {
        expected_len: usize,
        remaining_bytes: usize,
    },
    DecompressLiteralsError(DecompressLiteralsError),
    LiteralsSectionParseError(LiteralsSectionParseError),
    SequencesHeaderParseError(SequencesHeaderParseError),
    DecodeSequenceError(DecodeSequenceError),
    ExecuteSequencesError(ExecuteSequencesError),
    /// The block's literals, or its whole output, run past the block maximum
    /// (RFC 8878 3.1.1.2.4, `Block_Maximum_Size`): `size` bytes where
    /// `maximum` is the most a block of this frame may produce, the smaller of
    /// its window and 128 KiB.
    ExpandsPastBlockMaximum {
        size: usize,
        maximum: usize,
    },
    /// A compressed block's content is `size` bytes, past the block maximum
    /// (RFC 8878 3.1.1.2.4, `Block_Maximum_Size`) of `maximum`, the smaller of
    /// the frame's window and 128 KiB, whatever it would decode to.
    ContentPastBlockMaximum {
        size: usize,
        maximum: usize,
    },
    /// A block with no sequences whose literals do not fit a fixed-capacity
    /// backend: `requested` bytes at `tail` against `capacity`. The block is
    /// within the block maximum, so this says the caller's slice is short, and
    /// the frame decoder turns it into `TargetTooSmall` (or a content-size
    /// mismatch for a frame that declared one). Growable backends grow instead
    /// and never produce it.
    LiteralsOutputOverflow {
        tail: usize,
        requested: usize,
        capacity: usize,
    },
}

#[cfg(feature = "std")]
impl std::error::Error for DecompressBlockError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            DecompressBlockError::BlockContentReadError(source) => Some(source),
            DecompressBlockError::DecompressLiteralsError(source) => Some(source),
            DecompressBlockError::LiteralsSectionParseError(source) => Some(source),
            DecompressBlockError::SequencesHeaderParseError(source) => Some(source),
            DecompressBlockError::DecodeSequenceError(source) => Some(source),
            DecompressBlockError::ExecuteSequencesError(source) => Some(source),
            _ => None,
        }
    }
}

impl core::fmt::Display for DecompressBlockError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            DecompressBlockError::BlockContentReadError(e) => {
                write!(f, "Error while reading the block content: {e}")
            }
            DecompressBlockError::MalformedSectionHeader {
                expected_len,
                remaining_bytes,
            } => {
                write!(
                    f,
                    "Malformed section header. Says literals would be this long: {expected_len} but there are only {remaining_bytes} bytes left",
                )
            }
            DecompressBlockError::DecompressLiteralsError(e) => write!(f, "{e:?}"),
            DecompressBlockError::LiteralsSectionParseError(e) => write!(f, "{e:?}"),
            DecompressBlockError::SequencesHeaderParseError(e) => write!(f, "{e:?}"),
            DecompressBlockError::DecodeSequenceError(e) => write!(f, "{e:?}"),
            DecompressBlockError::ExecuteSequencesError(e) => write!(f, "{e:?}"),
            DecompressBlockError::ExpandsPastBlockMaximum { size, maximum } => write!(
                f,
                "Block expands to {size} bytes, past this frame's maximum of {maximum}"
            ),
            DecompressBlockError::ContentPastBlockMaximum { size, maximum } => write!(
                f,
                "Compressed block of {size} bytes, past this frame's maximum of {maximum}"
            ),
            DecompressBlockError::LiteralsOutputOverflow {
                tail,
                requested,
                capacity,
            } => write!(
                f,
                "Literals would write past the output buffer: tail={tail}, requested={requested}, capacity={capacity}"
            ),
        }
    }
}

impl From<Error> for DecompressBlockError {
    fn from(val: Error) -> Self {
        Self::BlockContentReadError(val)
    }
}

impl From<DecompressLiteralsError> for DecompressBlockError {
    fn from(val: DecompressLiteralsError) -> Self {
        Self::DecompressLiteralsError(val)
    }
}

impl From<LiteralsSectionParseError> for DecompressBlockError {
    fn from(val: LiteralsSectionParseError) -> Self {
        Self::LiteralsSectionParseError(val)
    }
}

impl From<SequencesHeaderParseError> for DecompressBlockError {
    fn from(val: SequencesHeaderParseError) -> Self {
        Self::SequencesHeaderParseError(val)
    }
}

impl From<DecodeSequenceError> for DecompressBlockError {
    fn from(val: DecodeSequenceError) -> Self {
        Self::DecodeSequenceError(val)
    }
}

impl From<ExecuteSequencesError> for DecompressBlockError {
    fn from(val: ExecuteSequencesError) -> Self {
        Self::ExecuteSequencesError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum DecodeBlockContentError {
    DecoderStateIsFailed,
    ExpectedHeaderOfPreviousBlock,
    ReadError {
        step: BlockType,
        source: Error,
    },
    DecompressBlockError(DecompressBlockError),
    /// The block's decompressed payload would not fit in the
    /// caller-provided output buffer (only reachable via the
    /// direct-decode path with a fixed-capacity backend). Internal
    /// diagnostic variant — the frame-level decoder always
    /// converts this into
    /// `FrameDecoderError::FrameContentSizeMismatch` before
    /// returning to the user, so external callers never observe
    /// it. The `step: BlockType` field is kept for in-crate
    /// debugging (which decode arm triggered the overshoot) but is
    /// not part of any caller-visible distinction.
    BackendOverflow {
        step: BlockType,
    },
}

#[cfg(feature = "std")]
impl std::error::Error for DecodeBlockContentError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            DecodeBlockContentError::ReadError { step: _, source } => Some(source),
            DecodeBlockContentError::DecompressBlockError(source) => Some(source),
            _ => None,
        }
    }
}

impl core::fmt::Display for DecodeBlockContentError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            DecodeBlockContentError::DecoderStateIsFailed => {
                write!(
                    f,
                    "Can't decode next block if failed along the way. Results will be nonsense",
                )
            }
            DecodeBlockContentError::ExpectedHeaderOfPreviousBlock => {
                write!(
                    f,
                    "Can't decode next block body, while expecting to decode the header of the previous block. Results will be nonsense",
                )
            }
            DecodeBlockContentError::ReadError { step, source } => {
                write!(f, "Error while reading bytes for {step}: {source}",)
            }
            DecodeBlockContentError::DecompressBlockError(e) => write!(f, "{e:?}"),
            DecodeBlockContentError::BackendOverflow { step } => write!(
                f,
                "{step} block's decompressed payload exceeds the caller-provided output buffer",
            ),
        }
    }
}

impl From<DecompressBlockError> for DecodeBlockContentError {
    fn from(val: DecompressBlockError) -> Self {
        Self::DecompressBlockError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum DecodeBufferError {
    NotEnoughBytesInDictionary {
        got: usize,
        need: usize,
    },
    OffsetTooBig {
        offset: usize,
        buf_len: usize,
    },
    ZeroOffset,
    /// Legacy unit variant kept for binary compatibility with earlier
    /// snapshots of this enum. Not surfaced from any current
    /// production path — `BufferBackend::try_extend` /
    /// `try_extend_from_within` and the new `try_reserve` (used by
    /// `DecodeBuffer::repeat`) carry their failures through the
    /// richer [`Self::OutputBufferOverflow`] variant below, which
    /// reports the offending `tail` / `requested` / `capacity`
    /// triple. New code should pattern-match on
    /// `OutputBufferOverflow`; this unit variant is retained to keep
    /// the `#[non_exhaustive]` enum's existing discriminant set
    /// stable.
    BackendOverflow,
    /// Repeat-side match copy would write past the writable tail of
    /// a fixed-capacity backend (`UserSliceBackend`). Surfaced by
    /// `DecodeBuffer::repeat` / `_lookahead`
    /// when the new `BufferBackend::try_reserve` rejects the
    /// pre-write capacity check — keeping the safe public decode
    /// APIs error-returning instead of panicking via the per-call
    /// `assert!` inside `extend_from_within_unchecked`. Growable
    /// backends (`FlatBuf`, `RingBuffer`) never produce this; their
    /// `try_reserve` falls through to infallible `reserve`.
    OutputBufferOverflow {
        tail: usize,
        requested: usize,
        capacity: usize,
    },
}

#[cfg(feature = "std")]
impl std::error::Error for DecodeBufferError {}

impl core::fmt::Display for DecodeBufferError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            DecodeBufferError::NotEnoughBytesInDictionary { got, need } => {
                write!(
                    f,
                    "Need {need} bytes from the dictionary but it is only {got} bytes long",
                )
            }
            DecodeBufferError::OffsetTooBig { offset, buf_len } => {
                write!(f, "offset: {offset} bigger than buffer: {buf_len}",)
            }
            DecodeBufferError::ZeroOffset => {
                write!(f, "Illegal offset: 0 found")
            }
            DecodeBufferError::BackendOverflow => {
                write!(
                    f,
                    "Match repeat would overflow the output buffer's fixed capacity"
                )
            }
            DecodeBufferError::OutputBufferOverflow {
                tail,
                requested,
                capacity,
            } => {
                write!(
                    f,
                    "Match repeat would write past fixed-capacity buffer: tail={tail}, requested={requested}, capacity={capacity}"
                )
            }
        }
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum DictionaryDecodeError {
    BadMagicNum { got: [u8; 4] },
    DictionaryTooSmall { got: usize, need: usize },
    ZeroDictionaryId,
    ZeroRepeatOffsetInDictionary { index: u8 },
    FSETableError(FSETableError),
    HuffmanTableError(HuffmanTableError),
}

#[cfg(feature = "std")]
impl std::error::Error for DictionaryDecodeError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            DictionaryDecodeError::FSETableError(source) => Some(source),
            DictionaryDecodeError::HuffmanTableError(source) => Some(source),
            _ => None,
        }
    }
}

impl core::fmt::Display for DictionaryDecodeError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            DictionaryDecodeError::BadMagicNum { got } => {
                write!(
                    f,
                    "Bad magic_num at start of the dictionary; Got: {:#04X?}, Expected: {:#04x?}",
                    got,
                    crate::decoding::dictionary::MAGIC_NUM,
                )
            }
            DictionaryDecodeError::DictionaryTooSmall { got, need } => {
                write!(
                    f,
                    "Dictionary is too small: got {got} bytes, need at least {need} bytes",
                )
            }
            DictionaryDecodeError::ZeroDictionaryId => {
                write!(f, "Dictionary id must be non-zero")
            }
            DictionaryDecodeError::ZeroRepeatOffsetInDictionary { index } => {
                write!(f, "Dictionary repeat offset rep{index} must be non-zero")
            }
            DictionaryDecodeError::FSETableError(e) => write!(f, "{e:?}"),
            DictionaryDecodeError::HuffmanTableError(e) => write!(f, "{e:?}"),
        }
    }
}

impl From<FSETableError> for DictionaryDecodeError {
    fn from(val: FSETableError) -> Self {
        Self::FSETableError(val)
    }
}

impl From<HuffmanTableError> for DictionaryDecodeError {
    fn from(val: HuffmanTableError) -> Self {
        Self::HuffmanTableError(val)
    }
}

/// The class a decoding failure falls in, as libzstd's stable error codes name
/// it (`zstd_errors.h`). The C API returns these codes and the command line
/// prints [`ErrorCode::message`], so both report a failure alike.
///
/// # Examples
///
/// ```
/// use structured_zstd::decoding::errors::{ErrorCode, FrameDecoderError};
///
/// let err = FrameDecoderError::DictNotProvided { dict_id: 7 };
/// assert_eq!(err.code(), ErrorCode::DictionaryWrong);
/// assert_eq!(err.code().message(), "Dictionary mismatch");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ErrorCode {
    /// Not a frame: the magic number is unknown.
    PrefixUnknown,
    /// The frame header asks for something this decoder does not support.
    FrameParameterUnsupported,
    /// The frame's window is past the ceiling in force.
    FrameParameterWindowTooLarge,
    /// A setting lies outside its allowed range.
    ParameterOutOfBound,
    /// The dictionary could not be read.
    DictionaryCorrupted,
    /// The frame needs another dictionary than the one supplied, or one that
    /// was not supplied.
    DictionaryWrong,
    /// The output buffer is too small.
    DstSizeTooSmall,
    /// The decoder was used before a frame was started.
    InitMissing,
    /// The content checksum does not match the decoded data.
    ChecksumWrong,
    /// The input ends inside the frame.
    SrcSizeWrong,
    /// The frame is malformed or damaged.
    CorruptionDetected,
}

impl ErrorCode {
    /// libzstd's message for the code (`ZSTD_getErrorString`).
    pub fn message(self) -> &'static str {
        match self {
            ErrorCode::PrefixUnknown => "Unknown frame descriptor",
            ErrorCode::FrameParameterUnsupported => "Unsupported frame parameter",
            ErrorCode::FrameParameterWindowTooLarge => {
                "Frame requires too much memory for decoding"
            }
            ErrorCode::ParameterOutOfBound => "Parameter is out of bound",
            ErrorCode::DictionaryCorrupted => "Dictionary is corrupted",
            ErrorCode::DictionaryWrong => "Dictionary mismatch",
            ErrorCode::DstSizeTooSmall => "Destination buffer is too small",
            ErrorCode::InitMissing => "Context should be init first",
            ErrorCode::ChecksumWrong => "Restored data doesn't match checksum",
            ErrorCode::SrcSizeWrong => "Src size is incorrect",
            ErrorCode::CorruptionDetected => "Data corruption detected",
        }
    }
}

impl FrameDescriptorError {
    /// The code libzstd returns for the refused descriptor.
    pub fn code(&self) -> ErrorCode {
        match self {
            // A set Reserved_bit is an unsupported frame parameter
            // (upstream zstd `zstd_decompress.c:511`).
            FrameDescriptorError::ReservedBitSet => ErrorCode::FrameParameterUnsupported,
            _ => ErrorCode::CorruptionDetected,
        }
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum FrameDecoderError {
    ReadFrameHeaderError(ReadFrameHeaderError),
    FrameHeaderError(FrameHeaderError),
    /// The frame's window exceeds the ceiling in force: the decoder's
    /// [`FrameDecoder::set_max_window_size`](crate::decoding::FrameDecoder::set_max_window_size)
    /// setting, or [`MAX_DECODER_WINDOW_SIZE`](crate::decoding::MAX_DECODER_WINDOW_SIZE).
    #[non_exhaustive]
    WindowSizeTooBig {
        /// The window the frame declares.
        requested: u64,
        /// The ceiling it exceeded.
        limit: u64,
    },
    /// A requested window ceiling lies outside 1 KiB (the smallest window a
    /// frame declares, RFC 8878 3.1.1.1.2) ..=
    /// [`MAX_DECODER_WINDOW_SIZE`](crate::decoding::MAX_DECODER_WINDOW_SIZE).
    WindowCeilingOutOfRange {
        /// The ceiling asked for.
        requested: u64,
    },
    DictionaryDecodeError(DictionaryDecodeError),
    FailedToReadBlockHeader(BlockHeaderReadError),
    FailedToReadBlockBody(DecodeBlockContentError),
    FailedToReadChecksum(Error),
    NotYetInitialized,
    FailedToInitialize(FrameHeaderError),
    FailedToDrainDecodebuffer(Error),
    FailedToSkipFrame,
    TargetTooSmall,
    /// Decoded block sizes don't sum to the frame's declared
    /// `frame_content_size` (either a block claims to expand past
    /// FCS, or the stream ends before reaching FCS). Indicates a
    /// malformed or corrupt frame — distinct from
    /// [`Self::TargetTooSmall`] (which is the caller's
    /// responsibility) so callers can tell decoder-side issues
    /// apart from their own buffer sizing mistakes.
    FrameContentSizeMismatch {
        declared: u64,
        produced: u64,
    },
    /// The frame carried a trailing XXH64 content checksum and the decoder
    /// was set to [`ContentChecksum::Verify`](crate::decoding::ContentChecksum::Verify),
    /// but the digest computed over the decompressed output did not match the
    /// stored value. Indicates corruption in the compressed stream or its
    /// trailing checksum. `expected` is the value read from the frame tail;
    /// `calculated` is the digest the decoder computed (both low 32 bits).
    ChecksumMismatch {
        expected: u32,
        calculated: u32,
    },
    DictNotProvided {
        dict_id: u32,
    },
    DictIdMismatch {
        expected: u32,
        provided: u32,
    },
    DictAlreadyRegistered {
        dict_id: u32,
    },
    /// Frame header's `dict_id` did not match the value pinned via
    /// `FrameDecoder::expect_dict_id`. Returned BEFORE any block
    /// decode and BEFORE any output is produced — no XXH64 init,
    /// no partial output. Scratch buffer allocation / reservation
    /// for the decode pipeline happens during frame-header parsing,
    /// which is already complete when this validation fires, so
    /// the cost of scratch sizing is paid even on a mismatched
    /// header. `expected` is the pinned value (`Some(0)` is
    /// treated as "no dictionary expected", matching a frame whose
    /// header omits the optional `Dictionary_ID` field); `found`
    /// reports what the frame actually carried (`None` when the
    /// header omits the field, `Some(id)` when it does not).
    #[cfg(feature = "lsm")]
    UnexpectedDictId {
        expected: Option<u32>,
        found: Option<u32>,
    },
    /// Frame header's raw `Window_Descriptor` byte did not match
    /// the value pinned via `FrameDecoder::expect_window_descriptor`.
    /// Returned BEFORE any block decode work. Single-segment frames
    /// (which omit the `Window_Descriptor` byte from the wire) are
    /// reported via `found: None` so callers can distinguish
    /// "wrong descriptor" from "no descriptor on the wire".
    #[cfg(feature = "lsm")]
    UnexpectedWindowDescriptor {
        expected: u8,
        found: Option<u8>,
    },
    /// Block-precise variant of [`Self::FailedToReadBlockHeader`]: a block
    /// header read failed and the decoder captured WHERE. `block_index` is
    /// the 0-based index of the failing block in the frame; `frame_offset`
    /// is the frame-absolute byte offset of that block's `Block_Header`
    /// (matches `FrameEmitInfo.blocks[block_index].offset_in_frame` from the
    /// encode side). Lets per-block recovery (ECC repair) target the one bad
    /// block instead of re-fetching the whole frame.
    #[cfg(feature = "lsm")]
    FailedToReadBlockHeaderAt {
        source: BlockHeaderReadError,
        block_index: u32,
        frame_offset: u32,
    },
    /// Block-precise variant of [`Self::FailedToReadBlockBody`]: a block
    /// body decode failed. Carries the same `block_index` / `frame_offset`
    /// coordinates plus the failing block's structural metadata
    /// ([`FrameBlock`]) reconstructed from its header, so a consumer can
    /// locate and repair exactly this block.
    ///
    /// [`FrameBlock`]: crate::encoding::frame_emit_info::FrameBlock
    #[cfg(feature = "lsm")]
    FailedToReadBlockBodyAt {
        source: DecodeBlockContentError,
        block_index: u32,
        frame_offset: u32,
        block: crate::encoding::frame_emit_info::FrameBlock,
    },
    /// `FrameDecoder::decode_blocks_partial` was called with
    /// `start_block > end_block` (the half-open block range is
    /// empty-or-inverted and cannot describe a valid subset). API
    /// misuse, surfaced as `Err` rather than a `PartialDecode`
    /// outcome — distinct from a corrupt-frame stop, which is
    /// reported via `PartialDecode::stopped_at`.
    #[cfg(feature = "lsm")]
    InvalidBlockRange {
        start_block: u32,
        end_block: u32,
    },
    /// A resuming [`FrameDecoder::decode_blocks_partial`] was given a
    /// `window_prime` (via [`ResumeInput`]) shorter than the match window the
    /// resume block can reach back into. The resumed decode would read past the
    /// primed history and silently mis-resolve matches, so it is rejected up
    /// front. `got` is the supplied prime length; `need` is the required
    /// minimum (`min(window_size, output_offset)`).
    ///
    /// [`FrameDecoder::decode_blocks_partial`]: crate::decoding::FrameDecoder::decode_blocks_partial
    /// [`ResumeInput`]: crate::decoding::ResumeInput
    #[cfg(feature = "lsm")]
    ResumeWindowTooShort {
        got: usize,
        need: usize,
    },
    /// A resuming [`FrameDecoder::decode_blocks_partial`] was given a
    /// [`ResumeInput`] whose [`ResumeState`] was captured from a frame with a
    /// different decode-relevant shape (window size, dictionary id,
    /// single-segment flag, content-checksum flag, or magicless mode) than the
    /// frame currently [`reset`](crate::decoding::FrameDecoder::reset) into the
    /// decoder. Applying entropy/repcode state across mismatched frames would
    /// yield byte-wrong output, so it is rejected up front.
    ///
    /// [`FrameDecoder::decode_blocks_partial`]: crate::decoding::FrameDecoder::decode_blocks_partial
    /// [`ResumeInput`]: crate::decoding::ResumeInput
    /// [`ResumeState`]: crate::decoding::ResumeState
    #[cfg(feature = "lsm")]
    ResumeFrameMismatch,
    /// A resume was attempted while a dictionary that carries no ID was
    /// applied, on either the emitting or the resuming side.
    ///
    /// The frame key tells dictionaries apart by the ID the decoder recorded,
    /// and a raw-content dictionary has none — every one of them is ID 0. Two
    /// different raw dictionaries therefore key alike, so a snapshot captured
    /// under one would be restored under the other: foreign entropy and repcode
    /// state, and output that is wrong with nothing to say so. A dictionary that
    /// cannot be told from another cannot carry a resume across, so it is
    /// refused. Give the dictionary an ID (a serialized dictionary carries one,
    /// or supply a non-zero one to
    /// [`Dictionary::from_raw_content`](crate::decoding::Dictionary::from_raw_content))
    /// to make it resumable.
    #[cfg(feature = "lsm")]
    ResumeUnidentifiedDictionary,
    /// A frame of the v0.5, v0.6 or v0.7 format failed to decode.
    #[cfg(feature = "legacy")]
    #[cfg_attr(docsrs, doc(cfg(feature = "legacy")))]
    LegacyFrame(LegacyFrameError),
}

#[cfg(feature = "legacy")]
impl From<LegacyFrameError> for FrameDecoderError {
    fn from(err: LegacyFrameError) -> Self {
        FrameDecoderError::LegacyFrame(err)
    }
}

impl FrameDecoderError {
    /// The code libzstd returns for the same failure. A variant with no exact
    /// counterpart is `CorruptionDetected`, the code for a malformed frame.
    pub fn code(&self) -> ErrorCode {
        match self {
            FrameDecoderError::ReadFrameHeaderError(
                ReadFrameHeaderError::InvalidFrameDescriptor(descriptor),
            ) => descriptor.code(),
            FrameDecoderError::ReadFrameHeaderError(_) => ErrorCode::PrefixUnknown,
            // A window past the format's maximum is refused while the header
            // is read, before the ceiling check, and is the same failure.
            FrameDecoderError::FrameHeaderError(FrameHeaderError::WindowTooBig { .. })
            | FrameDecoderError::FailedToInitialize(FrameHeaderError::WindowTooBig { .. }) => {
                ErrorCode::FrameParameterWindowTooLarge
            }
            FrameDecoderError::FrameHeaderError(_) | FrameDecoderError::FailedToInitialize(_) => {
                ErrorCode::FrameParameterUnsupported
            }
            FrameDecoderError::WindowSizeTooBig { .. } => ErrorCode::FrameParameterWindowTooLarge,
            FrameDecoderError::WindowCeilingOutOfRange { .. } => ErrorCode::ParameterOutOfBound,
            FrameDecoderError::DictionaryDecodeError(_) => ErrorCode::DictionaryCorrupted,
            FrameDecoderError::DictNotProvided { .. }
            | FrameDecoderError::DictIdMismatch { .. }
            | FrameDecoderError::DictAlreadyRegistered { .. } => ErrorCode::DictionaryWrong,
            FrameDecoderError::TargetTooSmall => ErrorCode::DstSizeTooSmall,
            FrameDecoderError::NotYetInitialized => ErrorCode::InitMissing,
            FrameDecoderError::ChecksumMismatch { .. } => ErrorCode::ChecksumWrong,
            #[cfg(feature = "legacy")]
            FrameDecoderError::LegacyFrame(err) => err.code(),
            _ => ErrorCode::CorruptionDetected,
        }
    }
}

#[cfg(feature = "std")]
impl StdError for FrameDecoderError {
    fn source(&self) -> Option<&(dyn StdError + 'static)> {
        match self {
            FrameDecoderError::ReadFrameHeaderError(source) => Some(source),
            FrameDecoderError::FrameHeaderError(source) => Some(source),
            FrameDecoderError::DictionaryDecodeError(source) => Some(source),
            FrameDecoderError::FailedToReadBlockHeader(source) => Some(source),
            FrameDecoderError::FailedToReadBlockBody(source) => Some(source),
            #[cfg(feature = "lsm")]
            FrameDecoderError::FailedToReadBlockHeaderAt { source, .. } => Some(source),
            #[cfg(feature = "lsm")]
            FrameDecoderError::FailedToReadBlockBodyAt { source, .. } => Some(source),
            FrameDecoderError::FailedToReadChecksum(source) => Some(source),
            FrameDecoderError::FailedToInitialize(source) => Some(source),
            FrameDecoderError::FailedToDrainDecodebuffer(source) => Some(source),
            #[cfg(feature = "legacy")]
            FrameDecoderError::LegacyFrame(source) => Some(source),
            _ => None,
        }
    }
}

impl core::fmt::Display for FrameDecoderError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> ::core::fmt::Result {
        match self {
            FrameDecoderError::ReadFrameHeaderError(e) => {
                write!(f, "{e:?}")
            }
            FrameDecoderError::FrameHeaderError(e) => {
                write!(f, "{e:?}")
            }
            FrameDecoderError::WindowSizeTooBig { requested, limit } => {
                write!(
                    f,
                    "Specified window_size is too big; Requested: {requested}, Allowed: {limit}",
                )
            }
            FrameDecoderError::WindowCeilingOutOfRange { requested } => {
                write!(
                    f,
                    "window ceiling {requested} is outside {}..={}",
                    crate::common::MIN_WINDOW_SIZE,
                    crate::common::MAX_DECODER_WINDOW_SIZE,
                )
            }
            FrameDecoderError::DictionaryDecodeError(e) => {
                write!(f, "{e:?}")
            }
            FrameDecoderError::FailedToReadBlockHeader(e) => {
                write!(f, "Failed to parse/decode block body: {e}")
            }
            FrameDecoderError::FailedToReadBlockBody(e) => {
                write!(f, "Failed to parse block header: {e}")
            }
            #[cfg(feature = "lsm")]
            FrameDecoderError::FailedToReadBlockHeaderAt {
                source,
                block_index,
                frame_offset,
            } => {
                write!(
                    f,
                    "Failed to read block header at block {block_index} (frame offset {frame_offset}): {source}"
                )
            }
            #[cfg(feature = "lsm")]
            FrameDecoderError::FailedToReadBlockBodyAt {
                source,
                block_index,
                frame_offset,
                ..
            } => {
                write!(
                    f,
                    "Failed to decode block body at block {block_index} (frame offset {frame_offset}): {source}"
                )
            }
            FrameDecoderError::FailedToReadChecksum(e) => {
                write!(f, "Failed to read checksum: {e}")
            }
            FrameDecoderError::NotYetInitialized => {
                write!(f, "Decoder must initialized or reset before using it",)
            }
            FrameDecoderError::FailedToInitialize(e) => {
                write!(f, "Decoder encountered error while initializing: {e}")
            }
            FrameDecoderError::FailedToDrainDecodebuffer(e) => {
                write!(
                    f,
                    "Decoder encountered error while draining the decodebuffer: {e}",
                )
            }
            FrameDecoderError::FailedToSkipFrame => {
                write!(
                    f,
                    "Failed to skip bytes for the length given in the frame header"
                )
            }
            FrameDecoderError::TargetTooSmall => {
                write!(
                    f,
                    "Target must have at least as many bytes as the content size reported by the frame"
                )
            }
            FrameDecoderError::FrameContentSizeMismatch { declared, produced } => {
                write!(
                    f,
                    "Frame content size mismatch (corrupt frame): declared {declared} bytes, blocks summed to {produced} bytes"
                )
            }
            FrameDecoderError::ChecksumMismatch {
                expected,
                calculated,
            } => {
                write!(
                    f,
                    "Content checksum mismatch (corrupt frame): frame stored 0x{expected:08X}, decoder calculated 0x{calculated:08X}"
                )
            }
            FrameDecoderError::DictNotProvided { dict_id } => {
                write!(
                    f,
                    "Frame header specified dictionary id 0x{dict_id:X} that wasn't provided via add_dict()/add_dict_from_bytes() (or add_dict_handle() on atomic targets) or reset_with_dict_handle()/decode_all_with_dict_handle()/decode_all_with_dict_bytes()"
                )
            }
            FrameDecoderError::DictIdMismatch { expected, provided } => {
                write!(
                    f,
                    "Frame header dictionary id 0x{expected:X} does not match provided dictionary id 0x{provided:X}"
                )
            }
            FrameDecoderError::DictAlreadyRegistered { dict_id } => {
                write!(
                    f,
                    "Dictionary id 0x{dict_id:X} already registered in decoder"
                )
            }
            #[cfg(feature = "lsm")]
            FrameDecoderError::UnexpectedDictId { expected, found } => {
                write!(f, "Frame header dict_id mismatch: expected ")?;
                match expected {
                    Some(id) => write!(f, "0x{id:X}")?,
                    None => write!(f, "<none>")?,
                }
                write!(f, ", found ")?;
                match found {
                    Some(id) => write!(f, "0x{id:X}"),
                    None => write!(f, "<none>"),
                }
            }
            #[cfg(feature = "lsm")]
            FrameDecoderError::UnexpectedWindowDescriptor { expected, found } => {
                write!(
                    f,
                    "Frame header window_descriptor mismatch: expected 0x{expected:02X}, found "
                )?;
                match found {
                    Some(byte) => write!(f, "0x{byte:02X}"),
                    None => write!(f, "<none> (single-segment frame omits window_descriptor)"),
                }
            }
            #[cfg(feature = "lsm")]
            FrameDecoderError::InvalidBlockRange {
                start_block,
                end_block,
            } => {
                write!(
                    f,
                    "Invalid block range for partial decode: start_block {start_block} > end_block {end_block}"
                )
            }
            #[cfg(feature = "lsm")]
            FrameDecoderError::ResumeWindowTooShort { got, need } => {
                write!(
                    f,
                    "resume window_prime too short: got {got} bytes, need at least {need}"
                )
            }
            #[cfg(feature = "lsm")]
            FrameDecoderError::ResumeFrameMismatch => {
                write!(
                    f,
                    "resume state was captured from a frame with a different decode shape than the current frame"
                )
            }
            #[cfg(feature = "lsm")]
            FrameDecoderError::ResumeUnidentifiedDictionary => {
                write!(
                    f,
                    "a dictionary with no ID cannot be told from another one, so it cannot carry a resume state across frames"
                )
            }
            #[cfg(feature = "legacy")]
            FrameDecoderError::LegacyFrame(e) => write!(f, "{e}"),
        }
    }
}

impl From<DictionaryDecodeError> for FrameDecoderError {
    fn from(val: DictionaryDecodeError) -> Self {
        Self::DictionaryDecodeError(val)
    }
}

impl From<BlockHeaderReadError> for FrameDecoderError {
    fn from(val: BlockHeaderReadError) -> Self {
        Self::FailedToReadBlockHeader(val)
    }
}

impl From<FrameHeaderError> for FrameDecoderError {
    fn from(val: FrameHeaderError) -> Self {
        Self::FrameHeaderError(val)
    }
}

impl From<ReadFrameHeaderError> for FrameDecoderError {
    fn from(val: ReadFrameHeaderError) -> Self {
        Self::ReadFrameHeaderError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum DecompressLiteralsError {
    MissingCompressedSize,
    MissingNumStreams,
    GetBitsError(GetBitsError),
    HuffmanTableError(HuffmanTableError),
    HuffmanDecoderError(HuffmanDecoderError),
    UninitializedHuffmanTable,
    MissingBytesForJumpHeader { got: usize },
    MissingBytesForLiterals { got: usize, needed: usize },
    ExtraPadding { skipped_bits: i32 },
    BitstreamReadMismatch { read_til: isize, expected: isize },
    DecodedLiteralCountMismatch { decoded: usize, expected: usize },
}

#[cfg(feature = "std")]
impl std::error::Error for DecompressLiteralsError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            DecompressLiteralsError::GetBitsError(source) => Some(source),
            DecompressLiteralsError::HuffmanTableError(source) => Some(source),
            DecompressLiteralsError::HuffmanDecoderError(source) => Some(source),
            _ => None,
        }
    }
}
impl core::fmt::Display for DecompressLiteralsError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            DecompressLiteralsError::MissingCompressedSize => {
                write!(
                    f,
                    "compressed size was none even though it must be set to something for compressed literals",
                )
            }
            DecompressLiteralsError::MissingNumStreams => {
                write!(
                    f,
                    "num_streams was none even though it must be set to something (1 or 4) for compressed literals",
                )
            }
            DecompressLiteralsError::GetBitsError(e) => write!(f, "{e:?}"),
            DecompressLiteralsError::HuffmanTableError(e) => write!(f, "{e:?}"),
            DecompressLiteralsError::HuffmanDecoderError(e) => write!(f, "{e:?}"),
            DecompressLiteralsError::UninitializedHuffmanTable => {
                write!(
                    f,
                    "Tried to reuse huffman table but it was never initialized",
                )
            }
            DecompressLiteralsError::MissingBytesForJumpHeader { got } => {
                write!(f, "Need 6 bytes to decode jump header, got {got} bytes",)
            }
            DecompressLiteralsError::MissingBytesForLiterals { got, needed } => {
                write!(
                    f,
                    "Need at least {needed} bytes to decode literals. Have: {got} bytes",
                )
            }
            DecompressLiteralsError::ExtraPadding { skipped_bits } => {
                write!(
                    f,
                    "Padding at the end of the sequence_section was more than a byte long: {skipped_bits} bits. Probably caused by data corruption",
                )
            }
            DecompressLiteralsError::BitstreamReadMismatch { read_til, expected } => {
                write!(
                    f,
                    "Bitstream was read till: {read_til}, should have been: {expected}",
                )
            }
            DecompressLiteralsError::DecodedLiteralCountMismatch { decoded, expected } => {
                write!(
                    f,
                    "Did not decode enough literals: {decoded}, Should have been: {expected}",
                )
            }
        }
    }
}

impl From<HuffmanDecoderError> for DecompressLiteralsError {
    fn from(val: HuffmanDecoderError) -> Self {
        Self::HuffmanDecoderError(val)
    }
}

impl From<GetBitsError> for DecompressLiteralsError {
    fn from(val: GetBitsError) -> Self {
        Self::GetBitsError(val)
    }
}

impl From<HuffmanTableError> for DecompressLiteralsError {
    fn from(val: HuffmanTableError) -> Self {
        Self::HuffmanTableError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum ExecuteSequencesError {
    DecodebufferError(DecodeBufferError),
    NotEnoughBytesForSequence {
        wanted: usize,
        have: usize,
    },
    ZeroOffset,
    /// An inline sequence (`exec_sequence_inline`) would have written past
    /// the writable tail of the output buffer. Raised by every capacity-bounded
    /// backend that runs the inline executor (the fixed-capacity user slice and
    /// the pre-reserved flat buffer alike). Indicates the frame is corrupt: its
    /// sequences expand past the declared `frame_content_size` plus the
    /// caller-supplied `WILDCOPY_OVERLENGTH` slack. The fast-path check is
    /// per-sequence; the post-block FCS overflow check would also catch the
    /// same shape, but the per-sequence guard is what keeps the unsafe write
    /// surface inside the buffer on the way to the post-block check.
    OutputBufferOverflow {
        tail: usize,
        requested: usize,
        capacity: usize,
    },
}

impl core::fmt::Display for ExecuteSequencesError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            ExecuteSequencesError::DecodebufferError(e) => {
                write!(f, "{e:?}")
            }
            ExecuteSequencesError::NotEnoughBytesForSequence { wanted, have } => {
                write!(
                    f,
                    "Sequence wants to copy up to byte {wanted}. Bytes in literalsbuffer: {have}"
                )
            }
            ExecuteSequencesError::ZeroOffset => {
                write!(f, "Illegal offset: 0 found")
            }
            ExecuteSequencesError::OutputBufferOverflow {
                tail,
                requested,
                capacity,
            } => {
                write!(
                    f,
                    "Inline sequence would write past the output buffer: tail={tail}, requested={requested}, capacity={capacity}"
                )
            }
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for ExecuteSequencesError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            ExecuteSequencesError::DecodebufferError(source) => Some(source),
            _ => None,
        }
    }
}

impl From<DecodeBufferError> for ExecuteSequencesError {
    fn from(val: DecodeBufferError) -> Self {
        Self::DecodebufferError(val)
    }
}

impl From<crate::decoding::buffer_backend::BackendOverflow> for ExecuteSequencesError {
    fn from(val: crate::decoding::buffer_backend::BackendOverflow) -> Self {
        Self::OutputBufferOverflow {
            tail: val.tail,
            requested: val.requested,
            capacity: val.capacity,
        }
    }
}

impl ExecuteSequencesError {
    /// `Some(requested)` when this error is a fixed-capacity output-buffer
    /// overshoot from the Compressed-block sequence executor — either the
    /// inline-sequence path ([`Self::OutputBufferOverflow`]) or the
    /// match-repeat fallback ([`DecodeBufferError::OutputBufferOverflow`]
    /// wrapped in [`Self::DecodebufferError`]). `requested` is the byte
    /// count the failing write tried to append past the slice end.
    ///
    /// `None` for every non-overflow variant. Used by
    /// `FrameDecoder::run_direct_decode` to fold an in-block Compressed
    /// overshoot into the same `FrameContentSizeMismatch` contract the
    /// Raw/RLE [`DecodeBlockContentError::BackendOverflow`] arm already
    /// produces — both mean "the frame's content expands past the
    /// declared `frame_content_size`".
    pub(crate) fn output_overflow_requested(&self) -> Option<usize> {
        match self {
            ExecuteSequencesError::OutputBufferOverflow { requested, .. } => Some(*requested),
            ExecuteSequencesError::DecodebufferError(DecodeBufferError::OutputBufferOverflow {
                requested,
                ..
            }) => Some(*requested),
            _ => None,
        }
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum DecodeSequenceError {
    GetBitsError(GetBitsError),
    FSEDecoderError(FSEDecoderError),
    FSETableError(FSETableError),
    ExtraPadding {
        skipped_bits: i32,
    },
    UnsupportedOffset {
        offset_code: u8,
    },
    ZeroOffset,
    NotEnoughBytesForNumSequences,
    ExtraBits {
        bits_remaining: isize,
    },
    MissingCompressionMode,
    MissingByteForRleLlTable,
    MissingByteForRleOfTable,
    MissingByteForRleMlTable,
    /// An RLE-mode sequence table's single symbol code is out of range
    /// for its axis (LL/ML/OF). `axis` names the axis; `code` is the
    /// offending value read from the stream.
    InvalidRleCode {
        axis: &'static str,
        code: u8,
    },
}

#[cfg(feature = "std")]
impl std::error::Error for DecodeSequenceError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            DecodeSequenceError::GetBitsError(source) => Some(source),
            DecodeSequenceError::FSEDecoderError(source) => Some(source),
            DecodeSequenceError::FSETableError(source) => Some(source),
            _ => None,
        }
    }
}

impl core::fmt::Display for DecodeSequenceError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            DecodeSequenceError::GetBitsError(e) => write!(f, "{e:?}"),
            DecodeSequenceError::FSEDecoderError(e) => write!(f, "{e:?}"),
            DecodeSequenceError::FSETableError(e) => write!(f, "{e:?}"),
            DecodeSequenceError::ExtraPadding { skipped_bits } => {
                write!(
                    f,
                    "Padding at the end of the sequence_section was more than a byte long: {skipped_bits} bits. Probably caused by data corruption",
                )
            }
            DecodeSequenceError::UnsupportedOffset { offset_code } => {
                write!(
                    f,
                    "Do not support offsets bigger than 1<<32; got: {offset_code}",
                )
            }
            DecodeSequenceError::ZeroOffset => write!(
                f,
                "Read an offset == 0. That is an illegal value for offsets"
            ),
            DecodeSequenceError::NotEnoughBytesForNumSequences => write!(
                f,
                "Bytestream did not contain enough bytes to decode num_sequences"
            ),
            DecodeSequenceError::ExtraBits { bits_remaining } => write!(f, "{bits_remaining}"),
            DecodeSequenceError::MissingCompressionMode => write!(
                f,
                "compression modes are none but they must be set to something"
            ),
            DecodeSequenceError::MissingByteForRleLlTable => {
                write!(f, "Need a byte to read for RLE ll table")
            }
            DecodeSequenceError::MissingByteForRleOfTable => {
                write!(f, "Need a byte to read for RLE of table")
            }
            DecodeSequenceError::MissingByteForRleMlTable => {
                write!(f, "Need a byte to read for RLE ml table")
            }
            DecodeSequenceError::InvalidRleCode { axis, code } => {
                write!(f, "RLE {axis} table code {code} is out of range")
            }
        }
    }
}

impl From<GetBitsError> for DecodeSequenceError {
    fn from(val: GetBitsError) -> Self {
        Self::GetBitsError(val)
    }
}

impl From<FSETableError> for DecodeSequenceError {
    fn from(val: FSETableError) -> Self {
        Self::FSETableError(val)
    }
}

impl From<FSEDecoderError> for DecodeSequenceError {
    fn from(val: FSEDecoderError) -> Self {
        Self::FSEDecoderError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum LiteralsSectionParseError {
    IllegalLiteralSectionType { got: u8 },
    GetBitsError(GetBitsError),
    NotEnoughBytes { have: usize, need: u8 },
}

#[cfg(feature = "std")]
impl std::error::Error for LiteralsSectionParseError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            LiteralsSectionParseError::GetBitsError(source) => Some(source),
            _ => None,
        }
    }
}
impl core::fmt::Display for LiteralsSectionParseError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            LiteralsSectionParseError::IllegalLiteralSectionType { got } => {
                write!(
                    f,
                    "Illegal literalssectiontype. Is: {got}, must be in: 0, 1, 2, 3"
                )
            }
            LiteralsSectionParseError::GetBitsError(e) => write!(f, "{e:?}"),
            LiteralsSectionParseError::NotEnoughBytes { have, need } => {
                write!(
                    f,
                    "Not enough byte to parse the literals section header. Have: {have}, Need: {need}",
                )
            }
        }
    }
}

impl From<GetBitsError> for LiteralsSectionParseError {
    fn from(val: GetBitsError) -> Self {
        Self::GetBitsError(val)
    }
}

impl core::fmt::Display for LiteralsSectionType {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> Result<(), core::fmt::Error> {
        match self {
            LiteralsSectionType::Compressed => write!(f, "Compressed"),
            LiteralsSectionType::Raw => write!(f, "Raw"),
            LiteralsSectionType::RLE => write!(f, "RLE"),
            LiteralsSectionType::Treeless => write!(f, "Treeless"),
        }
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum SequencesHeaderParseError {
    NotEnoughBytes { need_at_least: u8, got: usize },
}

#[cfg(feature = "std")]
impl std::error::Error for SequencesHeaderParseError {}

impl core::fmt::Display for SequencesHeaderParseError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            SequencesHeaderParseError::NotEnoughBytes { need_at_least, got } => {
                write!(
                    f,
                    "source must have at least {need_at_least} bytes to parse header; got {got} bytes",
                )
            }
        }
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum FSETableError {
    AccLogIsZero,
    AccLogTooBig {
        got: u8,
        max: u8,
    },
    GetBitsError(GetBitsError),
    ProbabilityCounterMismatch {
        got: u32,
        expected_sum: u32,
        symbol_probabilities: Vec<i32>,
    },
    TooManySymbols {
        got: usize,
    },
    /// Probability value outside the RFC 8878 §4.1.1 allowed set
    /// `{-1, 0, 1..=table_size}`. Carries the violating value, the
    /// table size (`1 << accuracy_log`) and `accuracy_log` so the
    /// caller can pinpoint the failure without re-deriving the bound.
    InvalidProbability {
        value: i32,
        table_size: u32,
        accuracy_log: u8,
    },
    /// `calc_baseline_and_numbits` produced a state-entry whose bit
    /// width exceeds the table's accuracy log, violating the
    /// `new_state + (1 << num_bits) - 1 < table_size` invariant that
    /// the unchecked `read_entry` decode hot path relies on. The
    /// triggering probability is in-range per RFC 8878 §4.1.1; the
    /// failure is an internal table-shape inconsistency surfaced
    /// against the public `build_from_probabilities` API.
    TableInvariantViolation {
        prob: i32,
        symbol: u8,
        num_bits: u8,
        accuracy_log: u8,
    },
}

#[cfg(feature = "std")]
impl std::error::Error for FSETableError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            FSETableError::GetBitsError(source) => Some(source),
            _ => None,
        }
    }
}

impl core::fmt::Display for FSETableError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            FSETableError::AccLogIsZero => write!(f, "Acclog must be at least 1"),
            FSETableError::AccLogTooBig { got, max } => {
                write!(
                    f,
                    "Found FSE acc_log: {got} bigger than allowed maximum in this case: {max}"
                )
            }
            FSETableError::GetBitsError(e) => write!(f, "{e:?}"),
            FSETableError::ProbabilityCounterMismatch {
                got,
                expected_sum,
                symbol_probabilities,
            } => {
                write!(
                    f,
                    "FSE probability sum mismatch: got {got}, expected {expected_sum}. Indicates corrupted data or an invalid distribution\n {symbol_probabilities:?}",
                )
            }
            FSETableError::TooManySymbols { got } => {
                write!(
                    f,
                    "There are too many symbols in this distribution: {got}. Max: 256",
                )
            }
            FSETableError::InvalidProbability {
                value,
                table_size,
                accuracy_log,
            } => {
                write!(
                    f,
                    "FSE probability value {value} is outside the RFC 8878 allowed set (must be -1, 0, or in 1..={table_size}; accuracy_log={accuracy_log})",
                )
            }
            FSETableError::TableInvariantViolation {
                prob,
                symbol,
                num_bits,
                accuracy_log,
            } => {
                write!(
                    f,
                    "FSE table invariant violation: symbol {symbol} (prob {prob}) produced num_bits {num_bits} > accuracy_log {accuracy_log}",
                )
            }
        }
    }
}

impl From<GetBitsError> for FSETableError {
    fn from(val: GetBitsError) -> Self {
        Self::GetBitsError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum FSEDecoderError {
    GetBitsError(GetBitsError),
    TableIsUninitialized,
    /// Externally constructed `FSETable` violates the
    /// `decode.len() == 1 << accuracy_log` shape invariant. Only
    /// reachable under `feature = "fuzz-exports"`, where fuzz
    /// harnesses can set the `FSETable.decode` / `accuracy_log`
    /// fields directly and skip `build_decoding_table`.
    InvalidTableShape {
        decode_len: usize,
        accuracy_log: u8,
    },
}

#[cfg(feature = "std")]
impl std::error::Error for FSEDecoderError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            FSEDecoderError::GetBitsError(source) => Some(source),
            _ => None,
        }
    }
}

impl core::fmt::Display for FSEDecoderError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            FSEDecoderError::GetBitsError(e) => write!(f, "{e:?}"),
            FSEDecoderError::TableIsUninitialized => {
                write!(f, "Tried to use an uninitialized table!")
            }
            FSEDecoderError::InvalidTableShape {
                decode_len,
                accuracy_log,
            } => match 1usize.checked_shl((*accuracy_log).into()) {
                Some(expected) => write!(
                    f,
                    "FSETable shape invariant violated: decode.len() = {decode_len}, expected 1 << accuracy_log = {expected} (accuracy_log = {accuracy_log})",
                ),
                None => write!(
                    f,
                    "FSETable shape invariant violated: decode.len() = {decode_len}, accuracy_log = {accuracy_log} overflows 1 << accuracy_log for usize",
                ),
            },
        }
    }
}

impl From<GetBitsError> for FSEDecoderError {
    fn from(val: GetBitsError) -> Self {
        Self::GetBitsError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum HuffmanTableError {
    GetBitsError(GetBitsError),
    FSEDecoderError(FSEDecoderError),
    FSETableError(FSETableError),
    SourceIsEmpty,
    NotEnoughBytesForWeights {
        got_bytes: usize,
        expected_bytes: u8,
    },
    ExtraPadding {
        skipped_bits: i32,
    },
    TooManyWeights {
        got: usize,
    },
    MissingWeights,
    LeftoverIsNotAPowerOf2 {
        got: u32,
    },
    NotEnoughBytesToDecompressWeights {
        have: usize,
        need: usize,
    },
    FSETableUsedTooManyBytes {
        used: usize,
        available_bytes: u8,
    },
    NotEnoughBytesInSource {
        got: usize,
        need: usize,
    },
    WeightBiggerThanMaxNumBits {
        got: u8,
    },
    MaxBitsTooHigh {
        got: u8,
    },
}

#[cfg(feature = "std")]
impl StdError for HuffmanTableError {
    fn source(&self) -> Option<&(dyn StdError + 'static)> {
        match self {
            HuffmanTableError::GetBitsError(source) => Some(source),
            HuffmanTableError::FSEDecoderError(source) => Some(source),
            HuffmanTableError::FSETableError(source) => Some(source),
            _ => None,
        }
    }
}

impl core::fmt::Display for HuffmanTableError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> ::core::fmt::Result {
        match self {
            HuffmanTableError::GetBitsError(e) => write!(f, "{e:?}"),
            HuffmanTableError::FSEDecoderError(e) => write!(f, "{e:?}"),
            HuffmanTableError::FSETableError(e) => write!(f, "{e:?}"),
            HuffmanTableError::SourceIsEmpty => write!(f, "Source needs to have at least one byte"),
            HuffmanTableError::NotEnoughBytesForWeights {
                got_bytes,
                expected_bytes,
            } => {
                write!(
                    f,
                    "Header says there should be {expected_bytes} bytes for the weights but there are only {got_bytes} bytes in the stream"
                )
            }
            HuffmanTableError::ExtraPadding { skipped_bits } => {
                write!(
                    f,
                    "Padding at the end of the sequence_section was more than a byte long: {skipped_bits} bits. Probably caused by data corruption",
                )
            }
            HuffmanTableError::TooManyWeights { got } => {
                write!(
                    f,
                    "More than 255 weights decoded (got {got} weights). Stream is probably corrupted",
                )
            }
            HuffmanTableError::MissingWeights => {
                write!(f, "Can\'t build huffman table without any weights")
            }
            HuffmanTableError::LeftoverIsNotAPowerOf2 { got } => {
                write!(f, "Leftover must be power of two but is: {got}")
            }
            HuffmanTableError::NotEnoughBytesToDecompressWeights { have, need } => {
                write!(
                    f,
                    "Not enough bytes in stream to decompress weights. Is: {have}, Should be: {need}",
                )
            }
            HuffmanTableError::FSETableUsedTooManyBytes {
                used,
                available_bytes,
            } => {
                write!(
                    f,
                    "FSE table used more bytes: {used} than were meant to be used for the whole stream of huffman weights ({available_bytes})",
                )
            }
            HuffmanTableError::NotEnoughBytesInSource { got, need } => {
                write!(f, "Source needs to have at least {need} bytes, got: {got}",)
            }
            HuffmanTableError::WeightBiggerThanMaxNumBits { got } => {
                write!(
                    f,
                    "Cant have weight: {} bigger than max_num_bits: {}",
                    got,
                    crate::huff0::MAX_MAX_NUM_BITS,
                )
            }
            HuffmanTableError::MaxBitsTooHigh { got } => {
                write!(
                    f,
                    "max_bits derived from weights is: {} should be lower than: {}",
                    got,
                    crate::huff0::MAX_MAX_NUM_BITS,
                )
            }
        }
    }
}

impl From<GetBitsError> for HuffmanTableError {
    fn from(val: GetBitsError) -> Self {
        Self::GetBitsError(val)
    }
}

impl From<FSEDecoderError> for HuffmanTableError {
    fn from(val: FSEDecoderError) -> Self {
        Self::FSEDecoderError(val)
    }
}

impl From<FSETableError> for HuffmanTableError {
    fn from(val: FSETableError) -> Self {
        Self::FSETableError(val)
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub enum HuffmanDecoderError {
    GetBitsError(GetBitsError),
}

impl core::fmt::Display for HuffmanDecoderError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            HuffmanDecoderError::GetBitsError(e) => write!(f, "{e:?}"),
        }
    }
}

#[cfg(feature = "std")]
impl StdError for HuffmanDecoderError {
    fn source(&self) -> Option<&(dyn StdError + 'static)> {
        match self {
            HuffmanDecoderError::GetBitsError(source) => Some(source),
        }
    }
}

impl From<GetBitsError> for HuffmanDecoderError {
    fn from(val: GetBitsError) -> Self {
        Self::GetBitsError(val)
    }
}

#[cfg(test)]
mod tests;