plugmem_host/
error.rs

1//! Host-layer errors.
2
3use std::path::PathBuf;
4
5/// Every way the host layer can fail. Engine failures pass through as
6/// [`HostError::Engine`]; everything filesystem- or network-shaped is
7/// typed here.
8#[derive(Debug, thiserror::Error)]
9#[non_exhaustive]
10pub enum HostError {
11    /// The database file is exclusively locked by another process (or
12    /// another handle in this process). One local database has one owner — open a
13    /// different file, or drop the other handle.
14    #[error("database at {} is locked by another process", path.display())]
15    Locked {
16        /// The database base path.
17        path: PathBuf,
18    },
19
20    /// A filesystem operation failed.
21    #[error("i/o on {}: {source}", path.display())]
22    Io {
23        /// The file the operation touched.
24        path: PathBuf,
25        /// The underlying error.
26        #[source]
27        source: std::io::Error,
28    },
29
30    /// There is no published snapshot generation to map: the database has
31    /// never been checkpointed, so a read-only open ([`crate::Database::
32    /// open_readonly`]) or a [`crate::Database::scrub`] has nothing to point
33    /// at. Open it read-write once and checkpoint, then retry.
34    ///
35    /// A *dirty journal* is not this error. A reader maps the published
36    /// generation and never reads the journal, which is snapshot isolation:
37    /// it answers as of the last checkpoint rather than refusing until you
38    /// take one.
39    #[error("database at {} has no published snapshot yet: checkpoint it once first", path.display())]
40    NeedsCheckpoint {
41        /// The database base path.
42        path: PathBuf,
43    },
44
45    /// The engine returned a typed error.
46    #[error(transparent)]
47    Engine(#[from] plugmem_core::Error),
48
49    /// The embedder transport or response was unusable (the message
50    /// names what exactly: status, dimension mismatch, malformed JSON).
51    #[error("embedder: {0}")]
52    Embed(String),
53}
54
55/// What to tell someone whose pool hit its ceiling.
56///
57/// Kept as one string in one place so the CLI, the MCP server and the Node
58/// binding say the same thing. The engine cannot say it: `plugmem-core` knows
59/// nothing about config files, and its message is therefore a bare byte count
60/// — true, and useless on its own.
61pub const MAX_BYTES_HINT: &str = "that ceiling is `max_bytes` (`[engine] max_bytes` in config.toml), \
62and it applies to each pool separately rather than to their sum. Its default is not a capacity \
63judgement — it is the figure that keeps every pool addressable where `usize` is 32 bits, so a \
64database written anywhere opens anywhere. Raising it costs exactly that portability: a 32-bit \
65host then refuses the file with a typed error instead of misreading it.";
66
67impl HostError {
68    /// The follow-up line for a pool that ran out of room, or `None` when this
69    /// error is something else.
70    ///
71    /// The number in the message is a setting; the setting has a name and one
72    /// specific trade-off. Callers that talk to a person should print this
73    /// after the error itself.
74    pub fn capacity_hint(&self) -> Option<&'static str> {
75        let Self::Engine(engine) = self else {
76            return None;
77        };
78        matches!(
79            engine,
80            plugmem_core::Error::CapacityExceeded { .. }
81                | plugmem_core::Error::Arena(plugmem_core::ArenaError::CapacityExceeded { .. })
82        )
83        .then_some(MAX_BYTES_HINT)
84    }
85
86    /// Shorthand for wrapping an I/O error with its path.
87    pub(crate) fn io(path: &std::path::Path, source: std::io::Error) -> Self {
88        Self::Io {
89            path: path.to_path_buf(),
90            source,
91        }
92    }
93}
94
95#[cfg(test)]
96mod tests {
97    use super::*;
98
99    #[test]
100    fn a_pool_ceiling_carries_its_follow_up_and_nothing_else_does() {
101        // The engine's own message for this is a bare byte count — true, and
102        // useless to somebody who does not know the number is a setting. Every
103        // surface prints this line after it, so it has to actually attach.
104        for engine in [
105            plugmem_core::Error::CapacityExceeded { what: "vectors" },
106            plugmem_core::Error::Arena(plugmem_core::ArenaError::CapacityExceeded {
107                max_bytes: 65_536,
108            }),
109        ] {
110            let hint = HostError::Engine(engine).capacity_hint();
111            assert_eq!(hint, Some(MAX_BYTES_HINT));
112            assert!(hint.unwrap().contains("max_bytes"));
113        }
114
115        // Anything else must not: a lock conflict followed by a lecture about
116        // pool sizing is worse than no follow-up at all.
117        assert_eq!(
118            HostError::Engine(plugmem_core::Error::TooLarge {
119                what: "text",
120                len: 9_000,
121                max: 4_096,
122            })
123            .capacity_hint(),
124            None
125        );
126        assert_eq!(HostError::Embed("no provider".into()).capacity_hint(), None);
127        assert_eq!(
128            HostError::Locked {
129                path: PathBuf::from("/tmp/m.plugmem"),
130            }
131            .capacity_hint(),
132            None
133        );
134    }
135}
plugmem_host/error.rs

plugmem_host/
error.rs
