Skip to main content

memfork_core/
error.rs

1//! Error type for the MemFork engine.
2
3use crate::id::CommitId;
4
5/// Every fallible engine operation returns this error.
6#[derive(Debug, Clone, PartialEq, thiserror::Error)]
7#[non_exhaustive]
8pub enum Error {
9    /// The named branch does not exist.
10    #[error("no such branch: {0}")]
11    NoSuchBranch(String),
12
13    /// A branch with that name already exists.
14    #[error("branch already exists: {0}")]
15    BranchExists(String),
16
17    /// `main` is the root of history and cannot be discarded (DESIGN §4.2).
18    #[error("the default branch `{0}` cannot be discarded")]
19    CannotDiscardDefaultBranch(String),
20
21    /// The referenced commit is not in the graph.
22    #[error("no such commit: {0}")]
23    NoSuchCommit(CommitId),
24
25    /// A commit id could not be parsed from hex.
26    #[error("not a valid commit id: {0}")]
27    BadCommitId(String),
28
29    /// No commit on this branch has that sequence number.
30    #[error("branch `{branch}` has no commit at seq {seq} (head is at seq {head_seq})")]
31    NoSuchSeq {
32        /// The branch that was queried.
33        branch: String,
34        /// The requested sequence number.
35        seq: u64,
36        /// The sequence number of the branch head.
37        head_seq: u64,
38    },
39
40    /// Keys are UTF-8 and at most [`crate::MAX_KEY_BYTES`] bytes (DESIGN §4.1).
41    #[error("key is {0} bytes, maximum is {max} bytes", max = crate::MAX_KEY_BYTES)]
42    KeyTooLong(usize),
43
44    /// Keys may not be empty.
45    #[error("key is empty")]
46    EmptyKey,
47
48    /// Importance is a probability-like weight in `[0, 1]` (DESIGN §4.1).
49    #[error("importance must be in [0, 1] and not NaN, got {0}")]
50    BadImportance(f32),
51
52    /// The embedding dimension is fixed per database on first insert (DESIGN §4.1).
53    #[error("embedding has {got} dimensions, this database uses {expected}")]
54    DimensionMismatch {
55        /// The dimension this database was pinned to.
56        expected: usize,
57        /// The dimension that was supplied.
58        got: usize,
59    },
60
61    /// An embedding was supplied with no values.
62    #[error("embedding is empty")]
63    EmptyEmbedding,
64
65    /// The branch head moved while a transaction was open; retry (DESIGN §4.3).
66    #[error("branch `{branch}` moved from {expected} to {actual} while the transaction was open")]
67    Conflict {
68        /// The branch the transaction was opened on.
69        branch: String,
70        /// The head the transaction was based on.
71        expected: CommitId,
72        /// The head the branch actually has now.
73        actual: CommitId,
74    },
75
76    /// A `Fail`-policy merge found keys changed on both sides (DESIGN §4.2).
77    #[error("merge has {} conflicting key(s): {}", .keys.len(), .keys.join(", "))]
78    MergeConflict {
79        /// The conflicting keys, sorted ascending.
80        keys: Vec<String>,
81    },
82
83    /// The two branches share no common ancestor, so there is nothing to merge against.
84    #[error("branches `{from_branch}` and `{into_branch}` have no common ancestor")]
85    NoCommonAncestor {
86        /// The branch being merged from.
87        from_branch: String,
88        /// The branch being merged into.
89        into_branch: String,
90    },
91
92    /// A branch name did not meet the naming rules.
93    #[error("invalid branch name `{0}`: use 1-255 bytes of printable, non-whitespace UTF-8")]
94    BadBranchName(String),
95
96    /// A change could not be recorded durably, so it did not happen.
97    #[error("{0}")]
98    Journal(String),
99
100    /// A search query vector did not match the database dimension.
101    #[error("query vector has {got} dimensions, this database uses {expected}")]
102    BadQueryDimension {
103        /// The dimension this database was pinned to.
104        expected: usize,
105        /// The dimension that was supplied.
106        got: usize,
107    },
108}
109
110/// Convenience alias.
111pub type Result<T> = core::result::Result<T, Error>;