Skip to main content

docs_search/
error.rs

1//! Typed, exhaustive errors for index build and decode.
2
3use std::fmt;
4
5/// Everything that can go wrong building or reading an index.
6#[derive(Debug)]
7#[non_exhaustive]
8pub enum IndexError {
9    /// The blob does not start with the format magic.
10    InvalidMagic {
11        /// The first bytes found, for diagnosis; never assumed valid UTF-8.
12        found: [u8; 6],
13    },
14    /// The format version is newer than this crate understands.
15    UnsupportedVersion {
16        /// The version read from the header.
17        found: u32,
18        /// The highest version this crate decodes.
19        supported: u32,
20    },
21    /// The blob ends before a section the header promises.
22    Truncated {
23        /// What was being read when the blob ran out.
24        section: &'static str,
25    },
26    /// A section's internal structure is inconsistent (bad offset, bad
27    /// postings, overflowing count, non-finite vector metadata).
28    Corrupt {
29        /// What was inconsistent, for diagnosis.
30        reason: &'static str,
31    },
32    /// The FST dictionary itself failed to load.
33    Fst(fst::Error),
34    /// The index carries a quantized-vector section, but this build was
35    /// compiled without the `vectors` feature. Rebuild with the feature,
36    /// or use an index built without vectors.
37    VectorsUnsupported,
38    /// A vector was set with a dimension different from the one already
39    /// established for this index.
40    VectorDim {
41        /// Dimension of the first vector added (or of the index so far).
42        expected: u32,
43        /// Dimension of the offending vector.
44        found: u32,
45    },
46}
47
48impl fmt::Display for IndexError {
49    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
50        match self {
51            Self::InvalidMagic { found } => {
52                write!(f, "invalid magic: expected \"DSIDX2\", found {found:02x?}")
53            }
54            Self::UnsupportedVersion { found, supported } => {
55                write!(
56                    f,
57                    "index version {found} unsupported; this crate decodes up to {supported}"
58                )
59            }
60            Self::Truncated { section } => {
61                write!(f, "truncated index: ran out of bytes reading {section}")
62            }
63            Self::Corrupt { reason } => write!(f, "corrupt index: {reason}"),
64            Self::Fst(e) => write!(f, "term dictionary error: {e}"),
65            Self::VectorsUnsupported => write!(
66                f,
67                "index carries a quantized-vector section; rebuild with the `vectors` feature to read it"
68            ),
69            Self::VectorDim { expected, found } => {
70                write!(f, "vector dimension {found} does not match the index dimension {expected}")
71            }
72        }
73    }
74}
75
76impl std::error::Error for IndexError {
77    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
78        match self {
79            Self::Fst(e) => Some(e),
80            _ => None,
81        }
82    }
83}
84
85impl From<fst::Error> for IndexError {
86    fn from(e: fst::Error) -> Self {
87        Self::Fst(e)
88    }
89}