cheers_core/
error.rs

1//! Workspace-wide typed errors.
2//!
3//! Per-module errors ([`CodecError`], [`StoreError`]) stay local to the modules
4//! that raise them — they describe failures a single subsystem can own. [`Error`]
5//! is the umbrella type for functions that touch more than one subsystem (e.g. a
6//! sign-in handler that loads a user *and* mints a token); it carries the
7//! original typed cause via `#[from]` so callers can downcast when they need to.
8//!
9//! All the error *types* live here in `cheers-core`, even when the machinery that
10//! raises them lives in a higher crate: [`RefreshError`] is produced by
11//! `cheers-server`'s refresh rotator, but the type is keyless, so keeping it in
12//! the shared contract crate lets the [`Error`] umbrella stay whole (both the
13//! `cheers-verify` `EdgeVerifier` and the `cheers-server` `SessionAuthority`
14//! return this one `Error`).
15//!
16//! ```
17//! use cheers_core::{CodecError, Error};
18//!
19//! fn outer() -> Result<(), Error> {
20//!     // CodecError -> Error via the From impl.
21//!     Err(CodecError::Malformed)?
22//! }
23//!
24//! assert!(matches!(outer(), Err(Error::Codec(CodecError::Malformed))));
25//! ```
26
27use crate::codec::CodecError;
28use crate::store::StoreError;
29
30/// Errors raised by refresh-token rotation (`cheers-server`'s `RefreshRotator`).
31///
32/// Keyless, so it lives in the shared contract crate. `#[non_exhaustive]` so
33/// future variants don't break callers.
34#[derive(Debug, thiserror::Error)]
35#[non_exhaustive]
36pub enum RefreshError {
37    /// The presented token isn't in the store.
38    #[error("unknown refresh token")]
39    Unknown,
40    /// `expires_at <= now` for this token.
41    #[error("refresh token expired")]
42    Expired,
43    /// The presented token has already been rotated. The chain is now revoked as
44    /// a side effect — every record sharing the chain id has `revoked = true`
45    /// after this error returns.
46    #[error("replay detected; chain revoked")]
47    Replay,
48    /// The chain was previously revoked (logout, device revoke, prior replay).
49    #[error("chain revoked")]
50    ChainRevoked,
51    /// Underlying `RefreshStore` failure.
52    #[error(transparent)]
53    Store(#[from] StoreError),
54}
55
56/// Top-level cheers error. `#[non_exhaustive]` so new variants are non-breaking.
57#[derive(Debug, thiserror::Error)]
58#[non_exhaustive]
59pub enum Error {
60    /// Failure inside the [`Codec`](crate::codec::Codec) layer.
61    #[error(transparent)]
62    Codec(#[from] CodecError),
63
64    /// Failure inside a [`UserStore`]/[`CredentialStore`](crate::store::CredentialStore)/`RefreshStore`
65    /// impl.
66    ///
67    /// [`UserStore`]: crate::store
68    #[error(transparent)]
69    Store(#[from] StoreError),
70
71    /// Failure inside refresh-token rotation — surfaced by `cheers-server`'s
72    /// `SessionAuthority::rotate`.
73    #[error(transparent)]
74    Refresh(#[from] RefreshError),
75
76    /// A token verified cryptographically but its `jti` is in the revocation
77    /// set — surfaced by `cheers-verify`'s `EdgeVerifier`.
78    #[error("session revoked")]
79    Revoked,
80
81    /// Caller passed invalid input that no specific subsystem owns
82    /// (e.g. an empty subject string, a timestamp outside i64 range).
83    #[error("invalid input: {0}")]
84    InvalidInput(String),
85}
86
87/// Crate-local `Result` alias. Re-exported at the crate root.
88pub type Result<T> = std::result::Result<T, Error>;
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93
94    #[test]
95    fn codec_error_converts_via_from() {
96        let e: Error = CodecError::Malformed.into();
97        assert!(matches!(e, Error::Codec(CodecError::Malformed)));
98    }
99
100    #[test]
101    fn store_error_converts_via_from() {
102        let e: Error = StoreError::NotFound.into();
103        assert!(matches!(e, Error::Store(StoreError::NotFound)));
104    }
105
106    #[test]
107    fn refresh_error_converts_via_from() {
108        let e: Error = RefreshError::Replay.into();
109        assert!(matches!(e, Error::Refresh(RefreshError::Replay)));
110        // RefreshError itself absorbs a StoreError.
111        let e: Error = RefreshError::from(StoreError::Conflict).into();
112        assert!(matches!(e, Error::Refresh(RefreshError::Store(StoreError::Conflict))));
113    }
114
115    #[test]
116    fn question_mark_propagates() {
117        fn inner() -> Result<()> {
118            Err(StoreError::Conflict)?
119        }
120        assert!(matches!(inner(), Err(Error::Store(StoreError::Conflict))));
121    }
122
123    #[test]
124    fn invalid_input_displays_message() {
125        let e = Error::InvalidInput("subject empty".into());
126        assert_eq!(format!("{e}"), "invalid input: subject empty");
127    }
128
129    #[test]
130    fn error_is_send_sync_static() {
131        fn _check<T: Send + Sync + 'static>() {}
132        _check::<Error>();
133    }
134}
cheers_core/error.rs

cheers_core/
error.rs
