Skip to main content

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}