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}