// SPDX-License-Identifier: AGPL-3.0-only

//! Error types for reading and writing the on-disk save format.

use thiserror::Error;

/// A failure encountered while encoding or decoding a save-format record.
#[derive(Debug, Error)]
pub enum SaveError {
    /// The leading magic bytes did not match the expected record tag.
    #[error("record magic mismatch: expected {expected:?}, found {found:?}")]
    BadMagic {
        /// The magic the record was expected to begin with.
        expected: [u8; 4],
        /// The magic actually found at the start of the buffer.
        found: [u8; 4],
    },

    /// The buffer ended before a field of the declared size could be read.
    #[error("record truncated at offset {offset}: needed {needed} bytes, {available} available")]
    Truncated {
        /// The byte offset at which the read was attempted.
        offset: usize,
        /// The number of bytes the field required.
        needed: usize,
        /// The number of bytes actually remaining from `offset`.
        available: usize,
    },

    /// The decompressed payload length did not match the length the header declared.
    #[error("payload length mismatch: header declared {expected} bytes, decompressed {actual}")]
    LengthMismatch {
        /// The uncompressed length recorded in the header.
        expected: usize,
        /// The length actually produced by decompression.
        actual: usize,
    },

    /// The payload was too large for its length to fit the 32-bit header field.
    #[error("payload too large to frame: {len} bytes exceeds the u32 length field")]
    PayloadTooLarge {
        /// The oversized payload length in bytes.
        len: usize,
    },

    /// The payload could not be (de)serialized by `postcard`.
    #[error("payload serialization failed")]
    Serialization(#[from] postcard::Error),

    /// Compression or decompression failed at the I/O layer (`zstd`).
    #[error("payload compression failed")]
    Compression(#[from] std::io::Error),
}