rate_guard_core/
error.rs

1//! error.rs
2//! Defines both simple and verbose rate limiting error/result types.
3
4use crate::types::Uint;
5use core::fmt;
6
7/// Error type for fast-path rate limiting. No extra diagnostic information.
8#[derive(Debug, Clone, PartialEq, Eq)]
9pub enum SimpleRateLimitError {
10    InsufficientCapacity,
11    BeyondCapacity,
12    ExpiredTick,
13    ContentionFailure,
14}
15
16/// Result type for fast-path rate limiting.
17pub type SimpleRateLimitResult = Result<(), SimpleRateLimitError>;
18
19/// Error type for verbose rate limiting. Contains diagnostic information.
20#[derive(Debug, Clone, PartialEq, Eq)]
21pub enum VerboseRateLimitError {
22    /// Not enough tokens available.
23    InsufficientCapacity {
24        acquiring: Uint,
25        available: Uint,
26        retry_after_ticks: Uint,
27    },
28    /// Request permanently exceeds the configured capacity.
29    BeyondCapacity {
30        acquiring: Uint,
31        capacity: Uint,
32    },
33    /// Provided tick is too old.
34    ExpiredTick {
35        min_acceptable_tick: Uint,
36    },
37    /// Failed due to lock contention.
38    ContentionFailure,
39}
40
41/// Result type for verbose rate limiting.
42pub type VerboseRateLimitResult = Result<(), VerboseRateLimitError>;
43
44// Display trait for SimpleRateLimitError
45impl fmt::Display for SimpleRateLimitError {
46    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
47        use SimpleRateLimitError::*;
48        match self {
49            InsufficientCapacity => write!(f, "Insufficient capacity (fast path)."),
50            BeyondCapacity => write!(f, "Request exceeds maximum capacity (fast path)."),
51            ExpiredTick => write!(f, "Expired tick (fast path)."),
52            ContentionFailure => write!(f, "Contention failure (fast path)."),
53        }
54    }
55}
56
57// Display trait for VerboseRateLimitError
58impl fmt::Display for VerboseRateLimitError {
59    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
60        use VerboseRateLimitError::*;
61        match self {
62            InsufficientCapacity { acquiring, available, retry_after_ticks } => {
63                write!(
64                    f,
65                    "Insufficient capacity: tried to acquire {}, available {}, retry after {} tick(s).",
66                    acquiring, available, retry_after_ticks
67                )
68            }
69            BeyondCapacity { acquiring, capacity } => {
70                write!(
71                    f,
72                    "Request exceeds maximum capacity: tried to acquire {}, capacity {}. This request cannot succeed.",
73                    acquiring, capacity
74                )
75            }
76            ExpiredTick { min_acceptable_tick } => {
77                write!(
78                    f,
79                    "Expired tick: minimum acceptable tick is {}.",
80                    min_acceptable_tick
81                )
82            }
83            ContentionFailure => {
84                write!(f, "Contention failure: resource is locked by another operation. Please retry.")
85            }
86        }
87    }
88}
89
90impl std::error::Error for SimpleRateLimitError {}
91impl std::error::Error for VerboseRateLimitError {}
rate_guard_core/error.rs

rate_guard_core/
error.rs
