scyph_utils/pagination/error.rs
1//! Pagination error types.
2//!
3//! Defines [`PaginationError`] — failures that occur when decoding opaque pagination cursor tokens.
4//! These map to HTTP 400 Bad Request since they indicate the client sent a malformed cursor value.
5
6use scyph_core::AppError;
7
8/// Errors encountered during pagination cursor encoding or decoding.
9///
10/// ## When Does This Occur?
11///
12/// [`PaginationError::InvalidCursor`] surfaces when a client sends a `cursor` query parameter
13/// that cannot be decoded as a valid Base64 URL-safe UUID. Common causes:
14///
15/// - Manually constructed or guessed cursor values.
16/// - Cursor values from a different encoding scheme.
17/// - Truncated or corrupted cursor strings in URL.
18///
19/// The error message includes the underlying Base64 or UUID parsing failure for debugging.
20///
21/// # Examples
22///
23/// ```rust
24/// use scyph_utils::pagination::{Cursor, PaginationError};
25///
26/// // Valid cursor round-trip
27/// let id = uuid::Uuid::nil();
28/// let encoded = Cursor::encode(id);
29/// assert!(Cursor::decode(&encoded).is_ok());
30///
31/// // Invalid cursor → PaginationError::InvalidCursor
32/// let result = Cursor::decode("not-valid-base64!!!");
33/// assert!(matches!(result, Err(PaginationError::InvalidCursor(_))));
34/// ```
35#[derive(Debug, thiserror::Error)]
36pub enum PaginationError {
37 /// Invalid or malformed cursor pagination token.
38 #[error("Invalid pagination cursor token: {0}")]
39 InvalidCursor(String),
40}
41
42impl From<PaginationError> for AppError {
43 fn from(err: PaginationError) -> Self {
44 match err {
45 PaginationError::InvalidCursor(msg) => AppError::BadRequest(msg),
46 }
47 }
48}