Skip to main content

opencitations_client/
limit.rs

1//! Client side rate limiting.
2//!
3//! OpenCitations documents a limit of
4//! [180 requests a minute per ip address](https://api.opencitations.net/index/v2)
5//! and, unlike crossref, reports nothing about it on a response -- there is no
6//! header saying what the budget is or how much of it is left. So the pacing
7//! here is blind: it spaces requests evenly across the rate it was configured
8//! with and never learns better. The one thing a response does tell us is that
9//! we got it wrong, which arrives as a `429` and is handled by backing off.
10
11use reqwest::header::HeaderMap;
12use std::sync::{Mutex, MutexGuard, PoisonError};
13use std::time::Duration;
14use tokio::time::Instant;
15
16/// How many requests may be sent in a window.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct RateLimit {
19    /// how many requests are allowed within `interval`
20    pub limit: u32,
21    /// the window that `limit` applies to
22    pub interval: Duration,
23}
24
25impl RateLimit {
26    /// The rate OpenCitations documents: 180 requests a minute, one every third
27    /// of a second.
28    ///
29    /// Used unless [`OpenCitationsBuilder::rate_limit`](crate::OpenCitationsBuilder::rate_limit)
30    /// says otherwise. It is a per-address limit rather than a per-client one,
31    /// so it is worth lowering when something else on the same machine is also
32    /// querying.
33    pub const DOCUMENTED: Self = Self {
34        limit: 180,
35        interval: Duration::from_secs(60),
36    };
37
38    /// The gap to leave between two requests to spend the budget evenly.
39    pub fn spacing(&self) -> Duration {
40        self.interval / self.limit.max(1)
41    }
42}
43
44impl Default for RateLimit {
45    fn default() -> Self {
46        Self::DOCUMENTED
47    }
48}
49
50/// How long OpenCitations asked us to wait, from a `retry-after` header.
51///
52/// Only the delay-seconds form is understood; the HTTP-date form yields
53/// [`None`] and the caller falls back to its own backoff.
54pub(crate) fn retry_after(headers: &HeaderMap) -> Option<Duration> {
55    let seconds = headers
56        .get("retry-after")?
57        .to_str()
58        .ok()?
59        .trim()
60        .parse()
61        .ok()?;
62    Some(Duration::from_secs(seconds))
63}
64
65/// Paces requests so a client stays inside the documented rate.
66///
67/// Shared between every clone of an [`OpenCitations`](crate::OpenCitations), so
68/// concurrent callers queue against one another rather than each getting a full
69/// budget.
70#[derive(Debug)]
71pub(crate) struct Limiter {
72    state: Mutex<State>,
73}
74
75#[derive(Debug)]
76struct State {
77    rate: RateLimit,
78    /// the earliest instant at which the next request may leave
79    next_slot: Option<Instant>,
80}
81
82impl Limiter {
83    /// A limiter pacing at `rate`.
84    pub(crate) fn new(rate: RateLimit) -> Self {
85        Self {
86            state: Mutex::new(State {
87                rate,
88                next_slot: None,
89            }),
90        }
91    }
92
93    /// Waits until the next request fits inside the budget.
94    ///
95    /// Claims the slot before sleeping, so concurrent callers spread out
96    /// instead of all waking into the same one.
97    pub(crate) async fn acquire(&self) {
98        let slot = {
99            let mut state = self.lock();
100            let now = Instant::now();
101            let slot = state.next_slot.map_or(now, |slot| slot.max(now));
102            state.next_slot = Some(slot + state.rate.spacing());
103            slot
104        };
105        tokio::time::sleep_until(slot).await;
106    }
107
108    /// Holds every request back for at least `delay`.
109    ///
110    /// A `429` means the rate we were pacing at was wrong, so the pause has to
111    /// apply to everything sharing this limiter, not only to the request that
112    /// happened to be rejected.
113    pub(crate) fn back_off(&self, delay: Duration) {
114        let mut state = self.lock();
115        let resume = Instant::now() + delay;
116        state.next_slot = Some(state.next_slot.map_or(resume, |slot| slot.max(resume)));
117    }
118
119    /// The rate this limiter is pacing at.
120    pub(crate) fn rate(&self) -> RateLimit {
121        self.lock().rate
122    }
123
124    /// A poisoned limiter is still a usable one: the worst a panic mid-update
125    /// can leave behind is a stale slot, which costs a request's spacing.
126    fn lock(&self) -> MutexGuard<'_, State> {
127        self.state.lock().unwrap_or_else(PoisonError::into_inner)
128    }
129}
130
131#[cfg(test)]
132mod tests {
133    use super::*;
134
135    #[test]
136    fn the_documented_rate_spaces_requests_a_third_of_a_second_apart() {
137        assert_eq!(
138            RateLimit::DOCUMENTED.spacing(),
139            Duration::from_secs(60) / 180
140        );
141        // a third of a second, give or take the rounding of a division
142        assert!(RateLimit::DOCUMENTED.spacing() >= Duration::from_millis(333));
143        assert!(RateLimit::DOCUMENTED.spacing() < Duration::from_millis(334));
144    }
145
146    /// A limit of zero would divide by zero rather than mean "no requests".
147    #[test]
148    fn a_rate_of_zero_does_not_divide_by_zero() {
149        let rate = RateLimit {
150            limit: 0,
151            interval: Duration::from_secs(1),
152        };
153        assert_eq!(rate.spacing(), Duration::from_secs(1));
154    }
155
156    #[tokio::test(start_paused = true)]
157    async fn requests_are_spaced_by_the_rate() {
158        let limiter = Limiter::new(RateLimit {
159            limit: 2,
160            interval: Duration::from_secs(1),
161        });
162
163        let start = Instant::now();
164        limiter.acquire().await;
165        limiter.acquire().await;
166        limiter.acquire().await;
167
168        // the first leaves at once, the next two half a second apart
169        assert_eq!(start.elapsed(), Duration::from_secs(1));
170    }
171
172    #[tokio::test(start_paused = true)]
173    async fn backing_off_holds_everything_back() {
174        let limiter = Limiter::new(RateLimit::DOCUMENTED);
175
176        let start = Instant::now();
177        limiter.back_off(Duration::from_secs(5));
178        limiter.acquire().await;
179
180        assert_eq!(start.elapsed(), Duration::from_secs(5));
181    }
182}