prikk_error/
lib.rs

1#![forbid(unsafe_code)]
2#![warn(missing_docs)]
3
4//! Shared error taxonomy for Prikk crates.
5
6use core::fmt;
7
8/// Shared result type.
9pub type Result<T> = core::result::Result<T, PrikkError>;
10
11/// Error type used by the initial implementation crates.
12///
13/// `#[non_exhaustive]` (RFC 132 increment 1): `prikk-error` is published, and until this attribute
14/// landed, adding any new variant was a breaking change for every downstream match. Verified free to
15/// add before landing it: no exhaustive `match` on a `PrikkError` value exists anywhere in this
16/// workspace.
17#[non_exhaustive]
18#[derive(Debug, Clone, PartialEq, Eq)]
19pub enum PrikkError {
20    /// Canonical encoding failed because input data violates the frozen schema contract.
21    CanonicalEncoding(String),
22    /// An object identifier had an invalid form.
23    InvalidObjectId(String),
24    /// A signature had an invalid form or did not match its envelope context.
25    InvalidSignature(String),
26    /// A path-like name failed Prikk path/ref validation.
27    InvalidName(String),
28    /// A persistent object had an unexpected type.
29    ObjectTypeMismatch {
30        /// The object type required by the caller.
31        expected: String,
32        /// The object type actually found in the stored envelope.
33        actual: String,
34    },
35    /// The persistent format version is unsupported.
36    UnsupportedFormatVersion(u32),
37    /// A persisted object or record has malformed bytes.
38    MalformedData(String),
39    /// A persisted object was found at a path that does not match its computed ID.
40    Integrity(String),
41    /// A lock could not be acquired because another writer may be active.
42    LockConflict(String),
43    /// The requested object type cannot be persisted in the requested store.
44    UnsupportedObjectType(String),
45    /// An I/O failure. `kind` is `Some` only when this value was built from a real
46    /// `std::io::Error` via [`From`] -- every explicit construction site elsewhere in the workspace
47    /// (a caller-precondition violation, a platform-capability refusal, or a validation failure
48    /// wearing this variant rather than one that describes it) sets `kind: None`, which is the
49    /// truth, not a placeholder to "tidy" into something non-optional. RFC 132 increment 2 is
50    /// expected to move those sites onto variants that describe them and narrow this field.
51    Io {
52        /// The underlying `std::io::ErrorKind`, when this was built from a real `std::io::Error`.
53        kind: Option<std::io::ErrorKind>,
54        /// Human-readable context. Alone carries the full `Display` message -- see that impl.
55        context: String,
56    },
57}
58
59impl fmt::Display for PrikkError {
60    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
61        match self {
62            Self::CanonicalEncoding(msg) => write!(f, "canonical encoding error: {msg}"),
63            Self::InvalidObjectId(msg) => write!(f, "invalid object id: {msg}"),
64            Self::InvalidSignature(msg) => write!(f, "invalid signature: {msg}"),
65            Self::InvalidName(msg) => write!(f, "invalid name: {msg}"),
66            Self::ObjectTypeMismatch { expected, actual } => {
67                write!(f, "object type mismatch: expected {expected}, got {actual}")
68            }
69            Self::UnsupportedFormatVersion(version) => {
70                write!(f, "unsupported format version: {version}")
71            }
72            Self::MalformedData(msg) => write!(f, "malformed persisted data: {msg}"),
73            Self::Integrity(msg) => write!(f, "integrity error: {msg}"),
74            Self::LockConflict(msg) => write!(f, "lock conflict: {msg}"),
75            Self::UnsupportedObjectType(msg) => write!(f, "unsupported object type: {msg}"),
76            Self::Io { context, .. } => write!(f, "i/o error: {context}"),
77        }
78    }
79}
80
81impl std::error::Error for PrikkError {}
82
83impl From<std::io::Error> for PrikkError {
84    fn from(value: std::io::Error) -> Self {
85        Self::Io {
86            kind: Some(value.kind()),
87            context: value.to_string(),
88        }
89    }
90}
prikk_error/lib.rs

prikk_error/
lib.rs
