1use reqwest::header::HeaderMap;
13use std::sync::{Mutex, MutexGuard, PoisonError};
14use std::time::Duration;
15use tokio::time::Instant;
16
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub struct RateLimit {
22 pub limit: u32,
24 pub interval: Duration,
26}
27
28impl RateLimit {
29 pub const CONSERVATIVE: Self = Self {
35 limit: 5,
36 interval: Duration::from_secs(1),
37 };
38
39 pub fn spacing(&self) -> Duration {
41 self.interval / self.limit.max(1)
42 }
43
44 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
60fn header<'a>(headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
62 headers.get(name)?.to_str().ok()
63}
64
65fn 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
80pub(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#[derive(Debug)]
94pub(crate) struct Limiter {
95 state: Mutex<State>,
96}
97
98#[derive(Debug)]
99struct State {
100 rate: RateLimit,
102 next_slot: Option<Instant>,
104 pool: Option<String>,
106}
107
108impl Limiter {
109 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 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 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 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 pub(crate) fn rate(&self) -> RateLimit {
162 self.lock().rate
163 }
164
165 pub(crate) fn pool(&self) -> Option<String> {
167 self.lock().pool.clone()
168 }
169
170 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 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 limiter.observe(&HeaderMap::new());
307
308 assert_eq!(50, limiter.rate().limit);
309 assert_eq!(Some("polite".to_string()), limiter.pool());
310 }
311}