footing 0.6.6

Feature-gated foundations for Rust backend services
Documentation
use std::fmt;

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

/// Invalid presence inputs or a failed database operation.
///
/// Display and Debug omit identities and database error details. The original
/// database error remains available through the [`std::error::Error::source`]
/// chain. Database variants retain the backend even when both features are enabled.
/// Their error descriptors reuse that backend's retry classification: a retryable
/// failure may be transient, but an interrupted write can have an unknown commit
/// outcome. Send the next regular heartbeat instead of replaying buffered requests.
#[derive(thiserror::Error)]
#[non_exhaustive]
pub enum PresenceError {
    /// The scope is empty, too long, or contains control characters.
    #[error("presence scope must contain 1 to 256 UTF-8 bytes without control characters")]
    InvalidScope,
    /// A user ID or pagination boundary is invalid.
    #[error("presence user ID must contain 1 to 256 UTF-8 bytes without control characters")]
    InvalidUserId,
    /// The timeout is zero, exceeds the supported range, or loses precision.
    #[error(
        "presence timeout must be a whole number of milliseconds between 1 millisecond and 2147483647 seconds"
    )]
    InvalidTimeout,
    /// A query or cleanup batch size is outside the supported range.
    #[error("presence limit must be between 1 and 1000")]
    InvalidLimit,
    /// A PostgreSQL operation failed.
    #[cfg(feature = "presence-postgres")]
    #[cfg_attr(docsrs, doc(cfg(feature = "presence-postgres")))]
    #[error("presence database operation failed")]
    Postgres(#[from] crate::db::postgres::PostgresPoolError),
    /// A SQLite operation failed.
    #[cfg(feature = "presence-sqlite")]
    #[cfg_attr(docsrs, doc(cfg(feature = "presence-sqlite")))]
    #[error("presence database operation failed")]
    Sqlite(#[from] crate::db::sqlite::SqlitePoolError),
}

impl fmt::Debug for PresenceError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("PresenceError")
            .field("code", &self.error_code())
            .finish_non_exhaustive()
    }
}

impl ClassifyError for PresenceError {
    fn error_kind(&self) -> ErrorKind {
        match self {
            #[cfg(feature = "presence-postgres")]
            Self::Postgres(_) => ErrorKind::Dependency,
            #[cfg(feature = "presence-sqlite")]
            Self::Sqlite(_) => ErrorKind::Dependency,
            Self::InvalidScope
            | Self::InvalidUserId
            | Self::InvalidTimeout
            | Self::InvalidLimit => ErrorKind::Validation,
        }
    }

    fn error_code(&self) -> ErrorCode {
        ErrorCode::internal(match self {
            Self::InvalidScope => "presence_invalid_scope",
            Self::InvalidUserId => "presence_invalid_user_id",
            Self::InvalidTimeout => "presence_invalid_timeout",
            Self::InvalidLimit => "presence_invalid_limit",
            #[cfg(feature = "presence-postgres")]
            Self::Postgres(_) => "presence_database_failed",
            #[cfg(feature = "presence-sqlite")]
            Self::Sqlite(_) => "presence_database_failed",
        })
    }

    fn error_descriptor(&self) -> ErrorDescriptor {
        let retryable = match self {
            #[cfg(feature = "presence-postgres")]
            Self::Postgres(source) => source.error_descriptor().retryable(),
            #[cfg(feature = "presence-sqlite")]
            Self::Sqlite(source) => source.error_descriptor().retryable(),
            Self::InvalidScope
            | Self::InvalidUserId
            | Self::InvalidTimeout
            | Self::InvalidLimit => false,
        };
        ErrorDescriptor::new(self.error_kind(), self.error_code(), self.to_string())
            .with_retryable(retryable)
    }
}