Skip to main content

rig_core/error/
rate_limits.rs

1//! The request and token allowances a provider's reply states in its
2//! rate-limit headers: OpenAI's and Groq's `x-ratelimit-*-requests|tokens`,
3//! Anthropic's `anthropic-ratelimit-*`, OpenRouter's `x-ratelimit-*` and the
4//! IETF draft's `ratelimit-*`. Reading them never touches the clock: the
5//! caller passes the time the reply came, so resets given as a date or a Unix
6//! time become a wait.
7//!
8//! ```
9//! use std::time::{Duration, SystemTime};
10//! use rig_core::error::RateLimits;
11//!
12//! let mut headers = http::HeaderMap::new();
13//! headers.insert("x-ratelimit-limit-requests", "50".parse()?);
14//! headers.insert("x-ratelimit-remaining-requests", "42".parse()?);
15//! headers.insert("x-ratelimit-reset-requests", "34s".parse()?);
16//! let limits = RateLimits::from_headers(&headers, SystemTime::now());
17//! let requests = limits.requests.ok_or("no request allowance")?;
18//! assert_eq!((requests.remaining, requests.limit), (42, 50));
19//! assert_eq!(requests.resets_in, Some(Duration::from_secs(34)));
20//! assert_eq!(limits.tokens, None);
21//! # Ok::<(), Box<dyn std::error::Error>>(())
22//! ```
23
24use std::time::{Duration, SystemTime, UNIX_EPOCH};
25
26use super::retry::{hinted_wait, seconds};
27
28/// Nanoseconds in a second.
29const NANOS: i128 = 1_000_000_000;
30
31/// The `(limit, remaining, reset)` headers of a request allowance; the
32/// first pair present wins.
33const REQUESTS: [[&str; 3]; 4] = [
34    [
35        "x-ratelimit-limit-requests",
36        "x-ratelimit-remaining-requests",
37        "x-ratelimit-reset-requests",
38    ],
39    [
40        "anthropic-ratelimit-requests-limit",
41        "anthropic-ratelimit-requests-remaining",
42        "anthropic-ratelimit-requests-reset",
43    ],
44    [
45        "x-ratelimit-limit",
46        "x-ratelimit-remaining",
47        "x-ratelimit-reset",
48    ],
49    ["ratelimit-limit", "ratelimit-remaining", "ratelimit-reset"],
50];
51
52/// The `(limit, remaining, reset)` headers of a token allowance.
53const TOKENS: [[&str; 3]; 3] = [
54    [
55        "x-ratelimit-limit-tokens",
56        "x-ratelimit-remaining-tokens",
57        "x-ratelimit-reset-tokens",
58    ],
59    [
60        "anthropic-ratelimit-tokens-limit",
61        "anthropic-ratelimit-tokens-remaining",
62        "anthropic-ratelimit-tokens-reset",
63    ],
64    [
65        "anthropic-ratelimit-input-tokens-limit",
66        "anthropic-ratelimit-input-tokens-remaining",
67        "anthropic-ratelimit-input-tokens-reset",
68    ],
69];
70
71/// One allowance as a reply states it.
72#[derive(Debug, Clone, Copy, PartialEq, Eq)]
73pub struct Allowance {
74    /// Requests or tokens per window.
75    pub limit: u64,
76    /// Requests or tokens left in this window.
77    pub remaining: u64,
78    /// How long after the reply the window resets, when the reply said so
79    /// in a form that could be read. It may be as long as a [`Duration`]
80    /// holds, so add it to a clock with `checked_add`.
81    pub resets_in: Option<Duration>,
82}
83
84/// The allowances a reply's rate-limit headers state.
85#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
86pub struct RateLimits {
87    /// The request allowance, when the reply gave its limit and remainder.
88    pub requests: Option<Allowance>,
89    /// The token allowance, when the reply gave its limit and remainder.
90    pub tokens: Option<Allowance>,
91}
92
93impl RateLimits {
94    /// Reads the allowances in `headers`, a reply that came at `now`.
95    ///
96    /// An allowance needs both a limit and a remainder whose values start
97    /// with a whole number (`100` of `100;w=60`). Its reset may be seconds
98    /// (`34`, `1.5`), a Unix time in seconds or milliseconds, a value that
99    /// starts with a Go duration (`6m0s`, `20ms`, `1h1us`), an RFC 3339 date
100    /// (`2026-01-01T00:00:00Z`) or an HTTP date
101    /// (`Thu, 01 Jan 2026 00:00:34 GMT`). A reset already past is zero; any
102    /// other form is none.
103    pub fn from_headers(headers: &http::HeaderMap, now: SystemTime) -> Self {
104        Self {
105            requests: allowance(headers, &REQUESTS, now),
106            tokens: allowance(headers, &TOKENS, now),
107        }
108    }
109}
110
111/// The first allowance of `names` the headers give both a limit and a
112/// remainder for.
113fn allowance(headers: &http::HeaderMap, names: &[[&str; 3]], now: SystemTime) -> Option<Allowance> {
114    let text = |name: &str| headers.get(name)?.to_str().ok().map(str::trim);
115    names.iter().find_map(|[limit, remaining, reset]| {
116        Some(Allowance {
117            limit: leading_number(text(limit)?)?,
118            remaining: leading_number(text(remaining)?)?,
119            resets_in: text(reset).and_then(|reset| reset_in(reset, now)),
120        })
121    })
122}
123
124/// The whole number `text` starts with.
125fn leading_number(text: &str) -> Option<u64> {
126    let end = text
127        .find(|c: char| !c.is_ascii_digit())
128        .unwrap_or(text.len());
129    text.get(..end)?.parse().ok()
130}
131
132/// How long after `now` the reset `text` names comes.
133fn reset_in(text: &str, now: SystemTime) -> Option<Duration> {
134    if plain_decimal(text).is_some() {
135        let number: f64 = text.parse().ok()?;
136        // Numbers this large are Unix times, not waits: no window lasts 30 years.
137        return if number > 1e12 {
138            unix_wait(text, 1_000_000, now)
139        } else if number > 1e9 {
140            unix_wait(text, NANOS, now)
141        } else {
142            // A wait is read in floating point, as `retry_after` reads one.
143            seconds(number)
144        };
145    }
146    if let Some(wait) = hinted_wait(text) {
147        return Some(wait);
148    }
149    let at = match rfc3339(text) {
150        Some(at) => at,
151        None => since_epoch(httpdate::parse_http_date(text).ok()?)?,
152    };
153    until(at, now)
154}
155
156/// The wait from `now` until `at`, in nanoseconds since the Unix epoch;
157/// zero once it has passed.
158fn until(at: i128, now: SystemTime) -> Option<Duration> {
159    nanoseconds(at.checked_sub(since_epoch(now)?)?)
160}
161
162/// `time` in nanoseconds since the Unix epoch, negative before it.
163fn since_epoch(time: SystemTime) -> Option<i128> {
164    match time.duration_since(UNIX_EPOCH) {
165        Ok(after) => i128::try_from(after.as_nanos()).ok(),
166        Err(before) => i128::try_from(before.duration().as_nanos())
167            .ok()
168            .map(|n| -n),
169    }
170}
171
172/// The instant an RFC 3339 date names, in nanoseconds since the Unix epoch:
173/// `2026-01-01T00:00:00Z`, with an optional fraction of a second (digits
174/// past the ninth dropped, not rounded) and a `Z` or `+hh:mm` offset.
175pub(crate) fn rfc3339(text: &str) -> Option<i128> {
176    let (date, time) = text.split_once(['T', 't', ' '])?;
177    let mut date = date.split('-');
178    let year = digits(date.next()?, 4)?;
179    let month = digits(date.next()?, 2)?;
180    let day = digits(date.next()?, 2)?;
181    let (clock, offset) = match time.strip_suffix(['Z', 'z']) {
182        Some(clock) => (clock, 0),
183        None => {
184            let (clock, offset) = time.split_at_checked(time.rfind(['+', '-'])?)?;
185            let sign = if offset.starts_with('-') { -1 } else { 1 };
186            let (hours, minutes) = offset.get(1..)?.split_once(':')?;
187            let (hours, minutes) = (digits(hours, 2)?, digits(minutes, 2)?);
188            if hours > 23 || minutes > 59 {
189                return None;
190            }
191            (clock, sign * (hours * 3600 + minutes * 60))
192        }
193    };
194    let (clock, fraction) = clock.split_once('.').unwrap_or((clock, "0"));
195    if fraction.is_empty() || !fraction.bytes().all(|b| b.is_ascii_digit()) {
196        return None;
197    }
198    // Digits past the nanosecond are dropped, as chrono does.
199    let fraction: i128 = format!("{:0<9}", fraction.get(..9).unwrap_or(fraction))
200        .parse()
201        .ok()?;
202    let mut clock = clock.split(':');
203    let hour = digits(clock.next()?, 2)?;
204    let minute = digits(clock.next()?, 2)?;
205    let second = digits(clock.next()?, 2)?;
206    let days = days_since_epoch(year, month, day)?;
207    let valid = date.next().is_none() && clock.next().is_none();
208    if !valid || hour > 23 || minute > 59 || second > 60 {
209        return None;
210    }
211    let seconds = days * 86_400 + hour * 3600 + minute * 60 + second - offset;
212    i128::from(seconds)
213        .checked_mul(NANOS)?
214        .checked_add(fraction)
215}
216
217/// The wait from `now` until the Unix time `text` names, in units
218/// `unit` nanoseconds long. It is computed exactly from the kept digits and
219/// rounded once to the nearest nanosecond, ties to even; zero once it has
220/// passed.
221fn unix_wait(text: &str, unit: i128, now: SystemTime) -> Option<Duration> {
222    let (whole, fraction, places) = plain_decimal(text)?;
223    let whole = whole.checked_mul(unit)?.checked_sub(since_epoch(now)?)?;
224    let scale = 10_i128.checked_pow(places)?;
225    let fraction = fraction.checked_mul(unit)?;
226    let left = whole.checked_add(fraction.div_euclid(scale))?;
227    let twice = fraction.rem_euclid(scale).checked_mul(2)?;
228    let up = twice > scale || (twice == scale && left.rem_euclid(2) == 1);
229    nanoseconds(left.checked_add(i128::from(up))?)
230}
231
232/// A plain decimal (`34`, `1.5`, `.5`) as its whole part, its fraction's
233/// digits as a whole number and how many decimal places they are. Digits
234/// past the eighteenth decimal place are dropped. `None` for anything else,
235/// such as a sign or an exponent, or a whole part too large for an `i128`.
236fn plain_decimal(text: &str) -> Option<(i128, i128, u32)> {
237    let (whole, fraction) = text.split_once('.').unwrap_or((text, ""));
238    let digits = |part: &str| part.bytes().all(|b| b.is_ascii_digit());
239    if whole.len() + fraction.len() == 0 || !digits(whole) || !digits(fraction) {
240        return None;
241    }
242    let fraction = fraction.get(..18).unwrap_or(fraction);
243    Some((
244        format!("0{whole}").parse().ok()?,
245        format!("0{fraction}").parse().ok()?,
246        u32::try_from(fraction.len()).ok()?,
247    ))
248}
249
250/// `nanos` as a duration, zero when negative.
251fn nanoseconds(nanos: i128) -> Option<Duration> {
252    let nanos = nanos.max(0);
253    let secs = u64::try_from(nanos / NANOS).ok()?;
254    Some(Duration::new(secs, u32::try_from(nanos % NANOS).ok()?))
255}
256
257/// `text` as a number of exactly `width` ASCII digits.
258fn digits(text: &str, width: usize) -> Option<i64> {
259    let ascii = text.len() == width && text.bytes().all(|b| b.is_ascii_digit());
260    ascii.then(|| text.parse().ok())?
261}
262
263/// Days from 1970-01-01 to a date of the proleptic Gregorian calendar, or
264/// `None` for a date that does not exist (Howard Hinnant's `days_from_civil`).
265fn days_since_epoch(year: i64, month: i64, day: i64) -> Option<i64> {
266    let days = |year: i64, month: i64, day: i64| {
267        let year = if month <= 2 { year - 1 } else { year };
268        let era = year.div_euclid(400);
269        let of_era = year - era * 400;
270        let of_year = (153 * ((month + 9) % 12) + 2) / 5 + day - 1;
271        era * 146_097 + of_era * 365 + of_era / 4 - of_era / 100 + of_year - 719_468
272    };
273    let (next_year, next_month) = if month == 12 {
274        (year + 1, 1)
275    } else {
276        (year, month + 1)
277    };
278    let length = days(next_year, next_month, 1) - days(year, month, 1);
279    ((1..=12).contains(&month) && (1..=length).contains(&day)).then(|| days(year, month, day))
280}
281
282#[cfg(test)]
283mod tests;