opencitations-client 0.1.0

An async Rust client for the OpenCitations Index and Meta REST APIs
Documentation
//! Client side rate limiting.
//!
//! OpenCitations documents a limit of
//! [180 requests a minute per ip address](https://api.opencitations.net/index/v2)
//! and, unlike crossref, reports nothing about it on a response -- there is no
//! header saying what the budget is or how much of it is left. So the pacing
//! here is blind: it spaces requests evenly across the rate it was configured
//! with and never learns better. The one thing a response does tell us is that
//! we got it wrong, which arrives as a `429` and is handled by backing off.

use reqwest::header::HeaderMap;
use std::sync::{Mutex, MutexGuard, PoisonError};
use std::time::Duration;
use tokio::time::Instant;

/// How many requests may be sent in a window.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RateLimit {
    /// how many requests are allowed within `interval`
    pub limit: u32,
    /// the window that `limit` applies to
    pub interval: Duration,
}

impl RateLimit {
    /// The rate OpenCitations documents: 180 requests a minute, one every third
    /// of a second.
    ///
    /// Used unless [`OpenCitationsBuilder::rate_limit`](crate::OpenCitationsBuilder::rate_limit)
    /// says otherwise. It is a per-address limit rather than a per-client one,
    /// so it is worth lowering when something else on the same machine is also
    /// querying.
    pub const DOCUMENTED: Self = Self {
        limit: 180,
        interval: Duration::from_secs(60),
    };

    /// The gap to leave between two requests to spend the budget evenly.
    pub fn spacing(&self) -> Duration {
        self.interval / self.limit.max(1)
    }
}

impl Default for RateLimit {
    fn default() -> Self {
        Self::DOCUMENTED
    }
}

/// How long OpenCitations asked us to wait, from a `retry-after` header.
///
/// Only the delay-seconds form is understood; the HTTP-date form yields
/// [`None`] and the caller falls back to its own backoff.
pub(crate) fn retry_after(headers: &HeaderMap) -> Option<Duration> {
    let seconds = headers
        .get("retry-after")?
        .to_str()
        .ok()?
        .trim()
        .parse()
        .ok()?;
    Some(Duration::from_secs(seconds))
}

/// Paces requests so a client stays inside the documented rate.
///
/// Shared between every clone of an [`OpenCitations`](crate::OpenCitations), so
/// concurrent callers queue against one another rather than each getting a full
/// budget.
#[derive(Debug)]
pub(crate) struct Limiter {
    state: Mutex<State>,
}

#[derive(Debug)]
struct State {
    rate: RateLimit,
    /// the earliest instant at which the next request may leave
    next_slot: Option<Instant>,
}

impl Limiter {
    /// A limiter pacing at `rate`.
    pub(crate) fn new(rate: RateLimit) -> Self {
        Self {
            state: Mutex::new(State {
                rate,
                next_slot: None,
            }),
        }
    }

    /// Waits until the next request fits inside the budget.
    ///
    /// Claims the slot before sleeping, so concurrent callers spread out
    /// instead of all waking into the same one.
    pub(crate) async fn acquire(&self) {
        let slot = {
            let mut state = self.lock();
            let now = Instant::now();
            let slot = state.next_slot.map_or(now, |slot| slot.max(now));
            state.next_slot = Some(slot + state.rate.spacing());
            slot
        };
        tokio::time::sleep_until(slot).await;
    }

    /// Holds every request back for at least `delay`.
    ///
    /// A `429` means the rate we were pacing at was wrong, so the pause has to
    /// apply to everything sharing this limiter, not only to the request that
    /// happened to be rejected.
    pub(crate) fn back_off(&self, delay: Duration) {
        let mut state = self.lock();
        let resume = Instant::now() + delay;
        state.next_slot = Some(state.next_slot.map_or(resume, |slot| slot.max(resume)));
    }

    /// The rate this limiter is pacing at.
    pub(crate) fn rate(&self) -> RateLimit {
        self.lock().rate
    }

    /// A poisoned limiter is still a usable one: the worst a panic mid-update
    /// can leave behind is a stale slot, which costs a request's spacing.
    fn lock(&self) -> MutexGuard<'_, State> {
        self.state.lock().unwrap_or_else(PoisonError::into_inner)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_documented_rate_spaces_requests_a_third_of_a_second_apart() {
        assert_eq!(
            RateLimit::DOCUMENTED.spacing(),
            Duration::from_secs(60) / 180
        );
        // a third of a second, give or take the rounding of a division
        assert!(RateLimit::DOCUMENTED.spacing() >= Duration::from_millis(333));
        assert!(RateLimit::DOCUMENTED.spacing() < Duration::from_millis(334));
    }

    /// A limit of zero would divide by zero rather than mean "no requests".
    #[test]
    fn a_rate_of_zero_does_not_divide_by_zero() {
        let rate = RateLimit {
            limit: 0,
            interval: Duration::from_secs(1),
        };
        assert_eq!(rate.spacing(), Duration::from_secs(1));
    }

    #[tokio::test(start_paused = true)]
    async fn requests_are_spaced_by_the_rate() {
        let limiter = Limiter::new(RateLimit {
            limit: 2,
            interval: Duration::from_secs(1),
        });

        let start = Instant::now();
        limiter.acquire().await;
        limiter.acquire().await;
        limiter.acquire().await;

        // the first leaves at once, the next two half a second apart
        assert_eq!(start.elapsed(), Duration::from_secs(1));
    }

    #[tokio::test(start_paused = true)]
    async fn backing_off_holds_everything_back() {
        let limiter = Limiter::new(RateLimit::DOCUMENTED);

        let start = Instant::now();
        limiter.back_off(Duration::from_secs(5));
        limiter.acquire().await;

        assert_eq!(start.elapsed(), Duration::from_secs(5));
    }
}