relate_error/storage.rs
1use std::fmt;
2
3/// Errors that can occur in the storage layer.
4#[derive(Debug, Clone, PartialEq)]
5pub enum StorageError {
6 /// A referenced node was not found.
7 NodeNotFound(i64),
8 /// A referenced relationship was not found.
9 RelationshipNotFound(i64),
10 /// Cannot delete a node that still has relationships.
11 NodeHasRelationships(i64),
12 /// A uniqueness or existence constraint was violated.
13 ConstraintViolation(String),
14 /// An index with the given name already exists.
15 IndexAlreadyExists(String),
16 /// No index found with the given name.
17 IndexNotFound(String),
18 /// A constraint with the given name already exists.
19 ConstraintAlreadyExists(String),
20 /// No constraint found with the given name.
21 ConstraintNotFound(String),
22 /// The selected backend cannot provide transactional semantics.
23 TransactionsUnsupported,
24 /// A transaction is already active on this store.
25 TransactionAlreadyActive,
26 /// No transaction is active on this store.
27 NoActiveTransaction,
28 /// Persistence was published before a rollback-restoration failure made the durable outcome unknowable.
29 /// The store is poisoned and must not be used or reopened until its files are explicitly discarded.
30 PersistenceOutcomeIndeterminate(String),
31 /// A filesystem / I/O failure (open, read, write, sync, rename, remove).
32 ///
33 /// `io::Error` is neither `Clone` nor `PartialEq`, so the raw error is not
34 /// carried; instead the classifying [`std::io::ErrorKind`] is kept
35 /// alongside a fully-rendered message (which already embeds the original
36 /// error's text, so `Display` is unchanged from the old `Other` string).
37 Io {
38 kind: std::io::ErrorKind,
39 message: String,
40 },
41 /// A database file could not be decoded: its stored bytes are not the
42 /// expected on-disk format (e.g. malformed JSON). Distinct from [`Io`],
43 /// which is a filesystem failure; a `Corruption` means the file was read
44 /// but its contents are unusable.
45 Corruption(String),
46 /// A requested operation conflicts with the store's current state (e.g.
47 /// flushing while an explicit transaction is still open).
48 Conflict(String),
49 /// The database file is already open (exclusively locked) by another live
50 /// process. Carries the database path. The store refuses to open rather
51 /// than risk two writers clobbering each other; there is no read-only
52 /// fallback.
53 Locked(String),
54 /// A mutation was attempted against a read-only snapshot of the store —
55 /// today, a backend checked out to a historical MVCC version. Carries a
56 /// human-readable explanation. The store rejects the write rather than
57 /// silently destroying history by overwriting HEAD with the snapshot.
58 ReadOnly(String),
59 /// A generic error that fits no more specific variant.
60 Other(String),
61}
62
63impl fmt::Display for StorageError {
64 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
65 match self {
66 StorageError::NodeNotFound(id) => write!(f, "node {id} not found"),
67 StorageError::RelationshipNotFound(id) => {
68 write!(f, "relationship {id} not found")
69 }
70 StorageError::NodeHasRelationships(id) => write!(
71 f,
72 "cannot delete node {id} with existing relationships (use DETACH DELETE)"
73 ),
74 StorageError::ConstraintViolation(msg) => {
75 write!(f, "constraint violation: {msg}")
76 }
77 StorageError::IndexAlreadyExists(name) => {
78 write!(f, "index {name:?} already exists")
79 }
80 StorageError::IndexNotFound(name) => write!(f, "index {name:?} not found"),
81 StorageError::ConstraintAlreadyExists(name) => {
82 write!(f, "constraint {name:?} already exists")
83 }
84 StorageError::ConstraintNotFound(name) => {
85 write!(f, "constraint {name:?} not found")
86 }
87 StorageError::TransactionsUnsupported => {
88 write!(f, "transactions are not supported by this storage backend")
89 }
90 StorageError::TransactionAlreadyActive => write!(f, "a transaction is already active"),
91 StorageError::NoActiveTransaction => write!(f, "no transaction is active"),
92 StorageError::PersistenceOutcomeIndeterminate(msg) => {
93 write!(f, "persistence outcome is indeterminate: {msg}")
94 }
95 // `Io`/`Corruption`/`Conflict` render their message verbatim: the
96 // message already carries all context (it was formatted at the
97 // failing call site), so byte-for-byte Display is preserved from
98 // the pre-refactor `Other(...)` strings.
99 StorageError::Io { message, .. } => write!(f, "{message}"),
100 StorageError::Corruption(msg) => write!(f, "{msg}"),
101 StorageError::Conflict(msg) => write!(f, "{msg}"),
102 StorageError::Locked(path) => {
103 write!(f, "database is locked by another process: {path}")
104 }
105 StorageError::ReadOnly(msg) => write!(f, "{msg}"),
106 StorageError::Other(msg) => write!(f, "{msg}"),
107 }
108 }
109}
110
111impl std::error::Error for StorageError {}
112
113impl StorageError {
114 /// Build an [`StorageError::Io`] from a raw [`std::io::Error`], capturing
115 /// its [`std::io::ErrorKind`] and a caller-provided message that already
116 /// embeds the error text.
117 pub fn io(error: &std::io::Error, message: String) -> Self {
118 StorageError::Io {
119 kind: error.kind(),
120 message,
121 }
122 }
123}