use std::collections::HashMap;
use std::sync::{Mutex, OnceLock};
use std::time::{Duration, Instant};
type RateLimitPauses = HashMap<String, (Instant, Duration)>;
#[derive(Debug, Clone)]
pub struct RetryBanner {
pub attempt: u32,
pub deadline: Instant,
pub reason: String,
}
#[derive(Debug, Clone, Default)]
pub enum RetryState {
#[default]
Idle,
Active(RetryBanner),
Failed { reason: String, since: Instant },
}
impl RetryState {
#[cfg(any(test, feature = "test-support"))]
#[must_use]
pub fn seconds_remaining(&self) -> Option<u64> {
match self {
Self::Active(banner) => Some(
banner
.deadline
.saturating_duration_since(Instant::now())
.as_secs(),
),
_ => None,
}
}
#[cfg(any(test, feature = "test-support"))]
#[must_use]
pub fn is_failed(&self) -> bool {
matches!(self, Self::Failed { .. })
}
}
#[cfg(not(any(test, all(feature = "test-thread-scoped-state", debug_assertions))))]
fn with_state<R>(f: impl FnOnce(&mut RetryState) -> R) -> R {
static STATE: OnceLock<Mutex<RetryState>> = OnceLock::new();
let mut state = STATE
.get_or_init(|| Mutex::new(RetryState::Idle))
.lock()
.unwrap_or_else(|error| error.into_inner());
f(&mut state)
}
#[cfg(not(any(test, all(feature = "test-thread-scoped-state", debug_assertions))))]
fn with_rate_limit<R>(f: impl FnOnce(&mut RateLimitPauses) -> R) -> R {
static STATE: OnceLock<Mutex<RateLimitPauses>> = OnceLock::new();
let mut state = STATE
.get_or_init(|| Mutex::new(HashMap::new()))
.lock()
.unwrap_or_else(|error| error.into_inner());
f(&mut state)
}
#[cfg(any(test, all(feature = "test-thread-scoped-state", debug_assertions)))]
fn with_state<R>(f: impl FnOnce(&mut RetryState) -> R) -> R {
#[allow(clippy::type_complexity)]
static STATE: OnceLock<Mutex<std::collections::HashMap<std::thread::ThreadId, RetryState>>> =
OnceLock::new();
let mut by_thread = STATE
.get_or_init(|| Mutex::new(std::collections::HashMap::new()))
.lock()
.unwrap_or_else(|error| error.into_inner());
f(by_thread
.entry(std::thread::current().id())
.or_insert(RetryState::Idle))
}
#[cfg(any(test, all(feature = "test-thread-scoped-state", debug_assertions)))]
fn with_rate_limit<R>(f: impl FnOnce(&mut RateLimitPauses) -> R) -> R {
static STATE: OnceLock<Mutex<HashMap<std::thread::ThreadId, RateLimitPauses>>> =
OnceLock::new();
let mut by_thread = STATE
.get_or_init(|| Mutex::new(HashMap::new()))
.lock()
.unwrap_or_else(|error| error.into_inner());
f(by_thread.entry(std::thread::current().id()).or_default())
}
#[cfg(any(test, feature = "test-support"))]
#[must_use]
pub fn snapshot() -> RetryState {
with_state(|state| state.clone())
}
pub const MAX_PROVIDER_PAUSE: Duration = Duration::from_secs(3600);
pub fn note_rate_limit(scope: &str, delay: Duration) {
let delay = delay.min(MAX_PROVIDER_PAUSE);
with_rate_limit(|pauses| {
let now = Instant::now();
pauses.retain(|_, (observed, delay)| {
!delay
.saturating_sub(now.saturating_duration_since(*observed))
.is_zero()
});
let current = pauses.entry(scope.to_string()).or_insert((now, delay));
if current
.1
.saturating_sub(now.saturating_duration_since(current.0))
< delay
{
*current = (now, delay);
}
});
}
#[must_use]
pub fn rate_limit_remaining(scope: &str) -> Option<Duration> {
let now = Instant::now();
with_rate_limit(|pauses| {
let (observed, delay) = pauses.get(scope).copied()?;
let remaining = delay.saturating_sub(now.saturating_duration_since(observed));
if remaining.is_zero() {
pauses.remove(scope);
None
} else {
Some(remaining)
}
})
}
pub fn start(attempt: u32, delay: Duration, reason: impl Into<String>) {
let delay = delay.min(MAX_PROVIDER_PAUSE);
let banner = RetryBanner {
attempt,
deadline: Instant::now() + delay,
reason: reason.into(),
};
with_state(|state| *state = RetryState::Active(banner));
}
pub fn succeeded() {
with_state(|state| *state = RetryState::Idle);
}
pub fn failed(reason: impl Into<String>) {
with_state(|state| {
*state = RetryState::Failed {
reason: reason.into(),
since: Instant::now(),
};
});
}
pub fn clear() {
with_state(|state| *state = RetryState::Idle);
}
#[cfg(any(test, feature = "test-support"))]
pub fn clear_rate_limit() {
with_rate_limit(HashMap::clear);
}
#[cfg(any(test, feature = "test-support"))]
pub fn test_guard() -> std::sync::MutexGuard<'static, ()> {
static GUARD: Mutex<()> = Mutex::new(());
GUARD.lock().unwrap_or_else(|e| e.into_inner())
}
#[cfg(test)]
mod tests {
use super::*;
fn setup() -> std::sync::MutexGuard<'static, ()> {
let g = test_guard();
clear();
clear_rate_limit();
g
}
#[test]
fn idle_by_default_after_clear() {
let _g = setup();
assert!(matches!(snapshot(), RetryState::Idle));
assert_eq!(snapshot().seconds_remaining(), None);
}
#[test]
fn start_then_succeeded_returns_to_idle() {
let _g = setup();
start(1, Duration::from_secs(5), "rate limited");
let s = snapshot();
assert!(matches!(s, RetryState::Active(_)));
let remaining = s.seconds_remaining().unwrap();
assert!(remaining <= 5, "{remaining}");
succeeded();
assert!(matches!(snapshot(), RetryState::Idle));
}
#[test]
fn failed_persists_until_clear() {
let _g = setup();
failed("upstream 500");
let s = snapshot();
assert!(s.is_failed());
if let RetryState::Failed { reason, .. } = s {
assert_eq!(reason, "upstream 500");
} else {
panic!("expected Failed");
}
clear();
assert!(matches!(snapshot(), RetryState::Idle));
}
#[test]
fn deadline_in_past_yields_zero_remaining() {
let _g = setup();
with_state(|state| {
*state = RetryState::Active(RetryBanner {
attempt: 2,
deadline: Instant::now() - Duration::from_secs(1),
reason: "test".into(),
});
});
assert_eq!(snapshot().seconds_remaining(), Some(0));
clear();
}
#[test]
fn rate_limit_deadline_survives_banner_clear() {
let _g = setup();
note_rate_limit("provider-a", Duration::from_secs(5));
start(1, Duration::from_secs(5), "rate limited");
succeeded();
assert!(
rate_limit_remaining("provider-a").is_some(),
"provider rate limit pause must not be cleared by an unrelated success"
);
clear_rate_limit();
}
#[test]
fn rate_limit_bounds_unrepresentable_instant_minimum() {
let _g = setup();
note_rate_limit("extreme-minimum", Duration::from_secs(u64::MAX));
note_rate_limit("extreme-minimum", Duration::from_secs(1));
let remaining = rate_limit_remaining("extreme-minimum").unwrap();
assert!(remaining <= MAX_PROVIDER_PAUSE);
assert!(remaining > Duration::from_secs(3598));
clear_rate_limit();
}
#[test]
fn one_providers_rate_limit_does_not_pause_another() {
let _g = setup();
note_rate_limit("provider-a@api.a.example", Duration::from_secs(30));
assert!(rate_limit_remaining("provider-a@api.a.example").is_some());
assert_eq!(rate_limit_remaining("ollama@127.0.0.1:11434"), None);
note_rate_limit("provider-a@api.a.example", Duration::from_secs(1));
assert!(
rate_limit_remaining("provider-a@api.a.example").unwrap() > Duration::from_secs(20)
);
clear_rate_limit();
assert_eq!(rate_limit_remaining("provider-a@api.a.example"), None);
}
}