weavatrix-search-vector 0.3.1

mod decoder;
mod encoder;
mod format;
mod storage;

use crate::error::SearchError;
use crate::quantized::QuantizedIndex;
use std::io::{Read, Write};
use std::path::Path;

pub(crate) use decoder::decode;
pub(crate) use encoder::encode;

pub(super) const MAGIC: &[u8; 8] = b"WVQNT003";
pub(super) const VERSION: u32 = 1;
pub(super) const HEADER_LEN: usize = 128;
pub(super) const FNV_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
pub(super) const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;

impl QuantizedIndex {
    /// Serializes the complete compact index into a checksummed buffer.
    ///
    /// # Errors
    ///
    /// Returns a capacity or allocation error.
    pub fn to_bytes(&self) -> Result<Vec<u8>, SearchError> {
        encode(self)
    }

    /// Restores and fully validates a compact index from a buffer.
    ///
    /// # Errors
    ///
    /// Returns a typed format, integrity, configuration, or allocation error.
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, SearchError> {
        decode(bytes)
    }

    /// Writes the checksummed compact representation to a stream.
    ///
    /// # Errors
    ///
    /// Returns a serialization or stream error.
    pub fn write_to(&self, mut writer: impl Write) -> Result<(), SearchError> {
        writer
            .write_all(&self.to_bytes()?)
            .map_err(|error| SearchError::storage("write quantized snapshot", &error))
    }

    /// Reads and validates a compact representation from a stream.
    ///
    /// # Errors
    ///
    /// Returns a stream, format, integrity, or allocation error.
    pub fn read_from(mut reader: impl Read) -> Result<Self, SearchError> {
        let mut bytes = Vec::new();
        reader
            .read_to_end(&mut bytes)
            .map_err(|error| SearchError::storage("read quantized snapshot", &error))?;
        Self::from_bytes(&bytes)
    }

    /// Atomically saves a checksummed compact snapshot.
    ///
    /// # Errors
    ///
    /// Returns a serialization or filesystem error.
    pub fn save(&self, path: impl AsRef<Path>) -> Result<(), SearchError> {
        crate::atomic_file::atomic_write(path.as_ref(), &self.to_bytes()?)
    }

    /// Loads and validates a compact snapshot.
    ///
    /// # Errors
    ///
    /// Returns a filesystem, format, integrity, or allocation error.
    pub fn load(path: impl AsRef<Path>) -> Result<Self, SearchError> {
        let bytes = std::fs::read(path.as_ref())
            .map_err(|error| SearchError::storage("read quantized snapshot", &error))?;
        Self::from_bytes(&bytes)
    }
}