footing 0.1.12

Feature-gated foundations for Rust backend services
Documentation
use thiserror::Error;

use crate::result::{ClassifyError, ErrorKind};

#[derive(Debug, Error)]
#[non_exhaustive]
/// Errors that can occur while handling pagination.
pub enum PaginationError {
    #[error("default page_size must be greater than zero")]
    /// Indicates default page size zero.
    DefaultPageSizeZero,
    #[error("max page_size must be greater than zero")]
    /// Indicates maximum page size zero.
    MaxPageSizeZero,
    #[error("default page_size {default} must be less than or equal to max page_size {max}")]
    /// The default page size exceeds the supported size.
    DefaultPageSizeTooLarge {
        #[doc = "The configured default."]
        default: u32,
        #[doc = "The configured upper bound."]
        max: u32,
    },
    #[error("max cursor length must be greater than zero")]
    /// Indicates maximum cursor length zero.
    MaxCursorLengthZero,
    #[error("page must be greater than zero")]
    /// Indicates page zero.
    PageZero,
    #[error("page offset exceeds the supported i64 range")]
    /// The requested page and size cannot be represented as a SQL offset.
    OffsetOverflow,
    #[error("page_size must be greater than zero")]
    /// Indicates page size zero.
    PageSizeZero,
    #[error("page_size must be less than or equal to {max}")]
    /// The page size exceeds the supported size.
    PageSizeTooLarge {
        #[doc = "The configured upper bound."]
        max: u32,
    },
    #[error("cursor is too large; maximum length is {max} bytes")]
    /// The cursor exceeds the supported size.
    CursorTooLarge {
        #[doc = "The configured upper bound."]
        max: usize,
    },
    #[error("cursor must not be empty")]
    /// Indicates cursor empty.
    CursorEmpty,
    #[error("cursor contains unsupported characters")]
    /// Indicates cursor invalid characters.
    CursorInvalidCharacters,
    #[error("page contains {items} items, which exceeds page_size {page_size}")]
    /// Indicates page items exceed page size.
    PageItemsExceedPageSize {
        #[doc = "The number of returned items."]
        items: usize,
        #[doc = "The configured page size."]
        page_size: u32,
    },
    #[error("next_cursor is required when has_more is true")]
    /// Indicates cursor required for more results.
    CursorRequiredForMoreResults,
    #[error("next_cursor must be absent when has_more is false")]
    /// Indicates cursor unexpected without more results.
    CursorUnexpectedWithoutMoreResults,
    #[error("total {total} is less than returned item count {items}")]
    /// Indicates total less than items.
    TotalLessThanItems {
        #[doc = "The total number of items."]
        total: u64,
        #[doc = "The number of returned items."]
        items: usize,
    },
}

impl ClassifyError for PaginationError {
    fn error_kind(&self) -> ErrorKind {
        ErrorKind::Validation
    }

    fn error_code(&self) -> crate::result::ErrorCode {
        crate::result::ErrorCode::internal(match self {
            Self::DefaultPageSizeZero => "pagination_default_page_size_zero",
            Self::MaxPageSizeZero => "pagination_max_page_size_zero",
            Self::DefaultPageSizeTooLarge { .. } => "pagination_default_page_size_too_large",
            Self::MaxCursorLengthZero => "pagination_max_cursor_length_zero",
            Self::PageZero => "pagination_page_zero",
            Self::OffsetOverflow => "pagination_offset_overflow",
            Self::PageSizeZero => "pagination_page_size_zero",
            Self::PageSizeTooLarge { .. } => "pagination_page_size_too_large",
            Self::CursorTooLarge { .. } => "pagination_cursor_too_large",
            Self::CursorEmpty => "pagination_cursor_empty",
            Self::CursorInvalidCharacters => "pagination_cursor_invalid_characters",
            Self::PageItemsExceedPageSize { .. } => "pagination_page_items_exceed_page_size",
            Self::CursorRequiredForMoreResults => "pagination_cursor_required_for_more_results",
            Self::CursorUnexpectedWithoutMoreResults => {
                "pagination_cursor_unexpected_without_more_results"
            }
            Self::TotalLessThanItems { .. } => "pagination_total_less_than_items",
        })
    }
}

/// Failure to validate a page or encode its continuation cursor.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum CursorPageBuildError<E> {
    /// Page metadata violates the same constraints as [`super::CursorPage::new`].
    #[error(transparent)]
    Pagination(#[from] PaginationError),
    /// The caller's cursor encoder failed.
    #[error("continuation cursor encoding failed")]
    Cursor(#[source] E),
}

#[derive(Debug, Error)]
#[non_exhaustive]
/// Errors that can occur while handling cursor.
pub enum CursorError {
    #[error("cursor must not be empty")]
    /// Indicates empty.
    Empty,
    #[error("cursor is too large; maximum length is {max} bytes")]
    /// The value exceeds the supported size.
    TooLarge {
        #[doc = "The configured upper bound."]
        max: usize,
    },
    #[error("cursor encoding is invalid")]
    /// The encoding is invalid.
    InvalidEncoding,
    #[error("cursor payload is invalid")]
    /// The payload is invalid.
    InvalidPayload(#[from] serde_json::Error),
    #[error("cursor signature is invalid")]
    /// The signature is invalid.
    InvalidSignature,
    #[error("cursor secret must contain at least {min_bytes} bytes")]
    /// The secret is invalid.
    InvalidSecret {
        #[doc = "The minimum number of bytes."]
        min_bytes: usize,
    },
    #[error("cursor kind is invalid")]
    /// The kind is invalid.
    InvalidKind,
    #[error("cursor kind mismatch: expected {expected}, got {actual:?}")]
    /// Indicates kind mismatch.
    KindMismatch {
        /// The expected value.
        expected: String,
        /// The value that was encountered.
        actual: Option<String>,
    },
    #[error("cursor version {actual} is not supported")]
    /// The version is unsupported.
    UnsupportedVersion {
        #[doc = "The value that was encountered."]
        actual: u8,
    },
}

impl ClassifyError for CursorError {
    fn error_kind(&self) -> ErrorKind {
        ErrorKind::Validation
    }

    fn error_code(&self) -> crate::result::ErrorCode {
        crate::result::ErrorCode::internal(match self {
            Self::Empty => "cursor_empty",
            Self::TooLarge { .. } => "cursor_too_large",
            Self::InvalidEncoding => "cursor_invalid_encoding",
            Self::InvalidPayload(_) => "cursor_invalid_payload",
            Self::InvalidSignature => "cursor_invalid_signature",
            Self::InvalidSecret { .. } => "cursor_invalid_secret",
            Self::InvalidKind => "cursor_invalid_kind",
            Self::KindMismatch { .. } => "cursor_kind_mismatch",
            Self::UnsupportedVersion { .. } => "cursor_unsupported_version",
        })
    }
}