Skip to main content

crossref_client/
limit.rs

1//! Client side rate limiting.
2//!
3//! Crossref publishes the budget it grants a client on every response
4//! (`x-rate-limit-limit` and `x-rate-limit-interval`) and
5//! [expects clients to stay inside it](https://api.crossref.org/swagger-ui/index.html#/Etiquette);
6//! going over earns a `429`. A [`Crossref`](crate::Crossref) spaces its
7//! requests evenly across the reported interval and re-reads the budget from
8//! every response, so a client that moves between the anonymous and the polite
9//! pool adapts on its own; read back what it is working to with
10//! [`Crossref::rate_limit`](crate::Crossref::rate_limit).
11
12use reqwest::header::HeaderMap;
13use std::sync::{Mutex, MutexGuard, PoisonError};
14use std::time::Duration;
15use tokio::time::Instant;
16
17/// The request budget crossref grants a client.
18///
19/// Read back from a live client with [`Crossref::rate_limit`](crate::Crossref::rate_limit).
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub struct RateLimit {
22    /// how many requests are allowed within `interval`
23    pub limit: u32,
24    /// the window that `limit` applies to
25    pub interval: Duration,
26}
27
28impl RateLimit {
29    /// The budget assumed until crossref has reported one.
30    ///
31    /// Deliberately below what either pool actually grants. The first response
32    /// carries the real figure, so guessing low costs nothing but a slightly
33    /// slower first handful of requests, whereas guessing high costs a `429`.
34    pub const CONSERVATIVE: Self = Self {
35        limit: 5,
36        interval: Duration::from_secs(1),
37    };
38
39    /// The gap to leave between two requests to spend the budget evenly.
40    pub fn spacing(&self) -> Duration {
41        self.interval / self.limit.max(1)
42    }
43
44    /// Reads the budget crossref reported on a response.
45    ///
46    /// Returns [`None`] unless both headers are present and understood.
47    pub fn from_headers(headers: &HeaderMap) -> Option<Self> {
48        let limit = header(headers, "x-rate-limit-limit")?.trim().parse().ok()?;
49        let interval = parse_interval(header(headers, "x-rate-limit-interval")?)?;
50        Some(Self { limit, interval })
51    }
52}
53
54impl Default for RateLimit {
55    fn default() -> Self {
56        Self::CONSERVATIVE
57    }
58}
59
60/// Reads a header as a `str`, if it is present and not binary.
61fn header<'a>(headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
62    headers.get(name)?.to_str().ok()
63}
64
65/// Parses the `1s` form crossref uses for `x-rate-limit-interval`.
66fn parse_interval(raw: &str) -> Option<Duration> {
67    let raw = raw.trim();
68    let unit_at = raw.find(|c: char| !c.is_ascii_digit())?;
69    let (amount, unit) = raw.split_at(unit_at);
70    let amount: u64 = amount.parse().ok()?;
71    match unit {
72        "ms" => Some(Duration::from_millis(amount)),
73        "s" => Some(Duration::from_secs(amount)),
74        "m" => Some(Duration::from_secs(amount.checked_mul(60)?)),
75        "h" => Some(Duration::from_secs(amount.checked_mul(3_600)?)),
76        _ => None,
77    }
78}
79
80/// How long crossref asked us to wait, from a `retry-after` header.
81///
82/// Only the delay-seconds form is understood; the HTTP-date form yields
83/// [`None`] and the caller falls back to its own backoff.
84pub(crate) fn retry_after(headers: &HeaderMap) -> Option<Duration> {
85    let seconds = header(headers, "retry-after")?.trim().parse().ok()?;
86    Some(Duration::from_secs(seconds))
87}
88
89/// Paces requests so a client stays inside the budget crossref granted it.
90///
91/// Shared between every clone of a [`Crossref`](crate::Crossref), so concurrent
92/// callers queue against one another rather than each getting a full budget.
93#[derive(Debug)]
94pub(crate) struct Limiter {
95    state: Mutex<State>,
96}
97
98#[derive(Debug)]
99struct State {
100    /// the budget, as last reported by crossref
101    rate: RateLimit,
102    /// the earliest instant at which the next request may leave
103    next_slot: Option<Instant>,
104    /// the pool crossref sorted the last request into, from `x-api-pool`
105    pool: Option<String>,
106}
107
108impl Limiter {
109    /// A limiter that assumes `rate` until crossref reports otherwise.
110    pub(crate) fn new(rate: RateLimit) -> Self {
111        Self {
112            state: Mutex::new(State {
113                rate,
114                next_slot: None,
115                pool: None,
116            }),
117        }
118    }
119
120    /// Waits until the next request fits inside the budget.
121    ///
122    /// Claims the slot before sleeping, so concurrent callers spread out
123    /// instead of all waking into the same one.
124    pub(crate) async fn acquire(&self) {
125        let slot = {
126            let mut state = self.lock();
127            let now = Instant::now();
128            let slot = state.next_slot.map_or(now, |slot| slot.max(now));
129            state.next_slot = Some(slot + state.rate.spacing());
130            slot
131        };
132        tokio::time::sleep_until(slot).await;
133    }
134
135    /// Re-reads the budget and the pool from a response.
136    pub(crate) fn observe(&self, headers: &HeaderMap) {
137        let rate = RateLimit::from_headers(headers);
138        let pool = header(headers, "x-api-pool").map(str::to_owned);
139
140        let mut state = self.lock();
141        if let Some(rate) = rate {
142            state.rate = rate;
143        }
144        if pool.is_some() {
145            state.pool = pool;
146        }
147    }
148
149    /// Holds every request back for at least `delay`.
150    ///
151    /// A `429` means the budget we believed in was wrong, so the pause has to
152    /// apply to everything sharing this limiter, not only to the request that
153    /// happened to be rejected.
154    pub(crate) fn back_off(&self, delay: Duration) {
155        let mut state = self.lock();
156        let resume = Instant::now() + delay;
157        state.next_slot = Some(state.next_slot.map_or(resume, |slot| slot.max(resume)));
158    }
159
160    /// The budget crossref last reported.
161    pub(crate) fn rate(&self) -> RateLimit {
162        self.lock().rate
163    }
164
165    /// The pool crossref last sorted a request into.
166    pub(crate) fn pool(&self) -> Option<String> {
167        self.lock().pool.clone()
168    }
169
170    /// The lock is only ever held across arithmetic, so a panic cannot leave
171    /// the state half-updated and poisoning carries no information.
172    fn lock(&self) -> MutexGuard<'_, State> {
173        self.state.lock().unwrap_or_else(PoisonError::into_inner)
174    }
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180    use reqwest::header::{HeaderMap, HeaderValue};
181
182    fn headers(pairs: &[(&'static str, &str)]) -> HeaderMap {
183        let mut headers = HeaderMap::new();
184        for (name, value) in pairs {
185            headers.insert(*name, HeaderValue::from_str(value).unwrap());
186        }
187        headers
188    }
189
190    #[test]
191    fn the_budget_is_read_from_the_headers_crossref_sends() {
192        let rate = RateLimit::from_headers(&headers(&[
193            ("x-rate-limit-limit", "50"),
194            ("x-rate-limit-interval", "1s"),
195        ]));
196
197        assert_eq!(
198            Some(RateLimit {
199                limit: 50,
200                interval: Duration::from_secs(1)
201            }),
202            rate
203        );
204    }
205
206    #[test]
207    fn a_half_reported_budget_is_no_budget() {
208        assert_eq!(
209            None,
210            RateLimit::from_headers(&headers(&[("x-rate-limit-limit", "50")]))
211        );
212        assert_eq!(
213            None,
214            RateLimit::from_headers(&headers(&[
215                ("x-rate-limit-limit", "50"),
216                ("x-rate-limit-interval", "1 fortnight"),
217            ]))
218        );
219    }
220
221    #[test]
222    fn every_interval_unit_crossref_might_use_parses() {
223        assert_eq!(Some(Duration::from_millis(500)), parse_interval("500ms"));
224        assert_eq!(Some(Duration::from_secs(1)), parse_interval("1s"));
225        assert_eq!(Some(Duration::from_secs(120)), parse_interval("2m"));
226        assert_eq!(Some(Duration::from_secs(3_600)), parse_interval("1h"));
227        assert_eq!(None, parse_interval("s"));
228        assert_eq!(None, parse_interval("12"));
229    }
230
231    #[test]
232    fn spacing_divides_the_interval_across_the_budget() {
233        let rate = RateLimit {
234            limit: 50,
235            interval: Duration::from_secs(1),
236        };
237        assert_eq!(Duration::from_millis(20), rate.spacing());
238    }
239
240    #[test]
241    fn a_zero_budget_does_not_divide_by_zero() {
242        let rate = RateLimit {
243            limit: 0,
244            interval: Duration::from_secs(1),
245        };
246        assert_eq!(Duration::from_secs(1), rate.spacing());
247    }
248
249    #[test]
250    fn retry_after_seconds_are_understood_and_dates_are_not() {
251        assert_eq!(
252            Some(Duration::from_secs(30)),
253            retry_after(&headers(&[("retry-after", "30")]))
254        );
255        assert_eq!(
256            None,
257            retry_after(&headers(&[(
258                "retry-after",
259                "Wed, 21 Oct 2015 07:28:00 GMT"
260            )]))
261        );
262    }
263
264    #[tokio::test(start_paused = true)]
265    async fn requests_are_spaced_across_the_interval() {
266        let limiter = Limiter::new(RateLimit {
267            limit: 4,
268            interval: Duration::from_secs(1),
269        });
270        let start = Instant::now();
271
272        for _ in 0..4 {
273            limiter.acquire().await;
274        }
275
276        // the first request leaves immediately, the other three are spaced 250ms
277        assert_eq!(Duration::from_millis(750), start.elapsed());
278    }
279
280    #[tokio::test(start_paused = true)]
281    async fn a_backoff_holds_back_the_next_request() {
282        let limiter = Limiter::new(RateLimit::CONSERVATIVE);
283        limiter.acquire().await;
284        let start = Instant::now();
285
286        limiter.back_off(Duration::from_secs(5));
287        limiter.acquire().await;
288
289        assert_eq!(Duration::from_secs(5), start.elapsed());
290    }
291
292    #[test]
293    fn observing_a_response_replaces_the_assumed_budget() {
294        let limiter = Limiter::new(RateLimit::CONSERVATIVE);
295
296        limiter.observe(&headers(&[
297            ("x-rate-limit-limit", "50"),
298            ("x-rate-limit-interval", "1s"),
299            ("x-api-pool", "polite"),
300        ]));
301
302        assert_eq!(50, limiter.rate().limit);
303        assert_eq!(Some("polite".to_string()), limiter.pool());
304
305        // a response without the headers leaves what we already know alone
306        limiter.observe(&HeaderMap::new());
307
308        assert_eq!(50, limiter.rate().limit);
309        assert_eq!(Some("polite".to_string()), limiter.pool());
310    }
311}