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}