Skip to main content

runlimit_postgres/
errors.rs

1use runlimit_core::{BatchError, ConsumptionStatus};
2use thiserror::Error;
3
4/// Failure from a quota check.
5#[derive(Debug, Error)]
6#[non_exhaustive]
7pub enum CheckError {
8    /// The atomic batch violated a backend-independent structural requirement.
9    #[error(transparent)]
10    InvalidBatch(#[from] BatchError),
11
12    /// `PostgreSQL` did not commit the transaction, so no quota was consumed.
13    #[error("PostgreSQL rate-limit check failed before commit; quota was not consumed")]
14    DefinitelyNotConsumed(#[source] sqlx::Error),
15
16    /// Commit confirmation was lost, so quota may or may not have been consumed.
17    #[error("PostgreSQL rate-limit commit outcome is unknown; quota may have been consumed")]
18    CommitOutcomeUnknown(#[source] sqlx::Error),
19
20    /// The pool-acquisition budget or operation deadline elapsed before commit
21    /// started.
22    #[error("PostgreSQL rate-limit check timed out while {operation}; quota was not consumed")]
23    TimedOutBeforeCommit {
24        /// Database phase that exhausted the deadline.
25        operation: &'static str,
26    },
27
28    /// The operation deadline elapsed after commit started.
29    #[error("PostgreSQL rate-limit commit timed out; quota may have been consumed")]
30    CommitTimedOut,
31
32    /// Persisted state violated an invariant guaranteed by the migration.
33    #[error("PostgreSQL rate-limit storage invariant failed: {0}")]
34    StorageInvariant(&'static str),
35
36    /// A rolled-back single check produced malformed response metadata.
37    #[error(
38        "PostgreSQL rate-limit single-check response invariant failed after rollback; quota was not consumed"
39    )]
40    ResponseInvariant,
41
42    /// A committed single check produced malformed response metadata.
43    #[error(
44        "PostgreSQL rate-limit single-check response invariant failed after commit; quota was consumed"
45    )]
46    CommittedResponseInvariant,
47}
48
49impl CheckError {
50    /// Reports whether the failed operation may have consumed quota.
51    pub const fn may_have_consumed_quota(&self) -> bool {
52        matches!(
53            self,
54            Self::CommitOutcomeUnknown(_) | Self::CommitTimedOut | Self::CommittedResponseInvariant
55        )
56    }
57}
58
59/// Failure from bounded expired-window cleanup.
60#[derive(Debug, Error)]
61#[non_exhaustive]
62pub enum MaintenanceError {
63    /// `PostgreSQL` did not commit the cleanup transaction, so no rows were
64    /// removed.
65    #[error("PostgreSQL expired-window cleanup failed before commit; no rows were removed")]
66    Database(#[source] sqlx::Error),
67    /// The pool-acquisition budget or operation deadline elapsed before cleanup
68    /// commit started.
69    #[error("PostgreSQL expired-window cleanup timed out while {operation}; no rows were removed")]
70    TimedOutBeforeCommit {
71        /// Database phase that exhausted the deadline.
72        operation: &'static str,
73    },
74    /// Commit confirmation was lost, so rows may or may not have been removed.
75    #[error(
76        "PostgreSQL expired-window cleanup commit outcome is unknown; rows may have been removed"
77    )]
78    CommitOutcomeUnknown(#[source] sqlx::Error),
79    /// The operation deadline elapsed after cleanup commit started.
80    #[error("PostgreSQL expired-window cleanup commit timed out; rows may have been removed")]
81    CommitTimedOut,
82}
83
84impl MaintenanceError {
85    /// Reports whether the failed cleanup may have committed row removals.
86    pub const fn may_have_removed_rows(&self) -> bool {
87        matches!(self, Self::CommitOutcomeUnknown(_) | Self::CommitTimedOut)
88    }
89}
90
91pub(crate) const fn check_error_consumption(error: &CheckError) -> ConsumptionStatus {
92    match error {
93        CheckError::CommitOutcomeUnknown(_) | CheckError::CommitTimedOut => {
94            ConsumptionStatus::PossiblyConsumed
95        }
96        CheckError::CommittedResponseInvariant => ConsumptionStatus::Consumed,
97        _ => ConsumptionStatus::NotConsumed,
98    }
99}