Interface Compressor

src/compression.rs:170–241

Interface for compression algorithms. This trait defines the contract that all compression implementations must fulfill. Each compressor is identified by a unique ID (0-7) that is stored in the chunk's `MetaByte`, allowing the reader to select the appropriate decompressor. ## Design The trait provides three methods: 1. **[`id`](Self::id):** Returns the unique algorithm identifier 2. **[`compre

/// - Returning `Cow::Borrowed` from `compress` when compression doesn't help
///   enables zero-copy optimization
pub trait Compressor: Send + Sync + std::fmt::Debug {
    /// Returns the unique ID stored in the `MetaByte` (Bits 1-3).
    ///
    /// This ID must be in the range 0-7 (3 bits) and should be unique across all
    /// registered compressors. ID 0 is reserved for [`NoCompression`].
    ///
    /// ## ID Allocation
    ///
    /// - **0:** `NoCompression` (reserved)
    /// - **1:** LZ4 (reserved)
    /// - **2-7:** Available for custom algorithms
    fn id(&self) -> u8;

    /// Compresses the input data.
    ///
    /// Returns a `Cow<[u8]>` which may borrow the input if compression is not performed
    /// or if the compressed size would be larger than the original (negative compression).
    ///
    /// ## Return Value
    ///
    /// - `Cow::Borrowed(data)`: Compression was not beneficial or not performed
    /// - `Cow::Owned(compressed)`: Data was successfully compressed
    ///
    /// ## Errors
    ///
    /// Returns [`ParcodeError::Compression`] if the compression algorithm fails.
    ///
    /// ## Performance
    ///
    /// This method may allocate memory for the compressed output. For better performance
    /// during serialization, use [`compress_append`](Self::compress_append) instead.
    fn compress<'a>(&self, data: &'a [u8]) -> Result<Cow<'a, [u8]>>;

    /// Decompresses the input data.
    ///
    /// Returns a `Cow<[u8]>` containing the original uncompressed data.
    ///
    /// ## Return Value
    ///
    /// - `Cow::Borrowed(data)`: No decompression needed (e.g., `NoCompression`)
    /// - `Cow::Owned(decompressed)`: Data was successfully decompressed
    ///
    /// ## Errors
    ///
    /// Returns [`ParcodeError::Compression`] if:
    /// - The compressed data is corrupted
    /// - The decompression algorithm fails
    /// - The decompressed size exceeds expected bounds
    fn decompress<'a>(&self, data: &'a [u8]) -> Result<Cow<'a, [u8]>>;

    /// Compresses data and appends it directly to the output vector.
    ///
    /// This method is more efficient than [`compress`](Self::compress) during serialization
    /// because it avoids intermediate allocations by writing directly to the final buffer.
    ///
    /// ## Parameters
    ///
    /// - `data`: The input data to compress