Struct RateLimiter 

pub struct RateLimiter { /* private fields */ }

Process-wide async rate limiter.

Enforces three invariants on every acquire:

1. Global concurrency — at most RateLimits::max_concurrent_fetches in flight at once.
2. Global rate — at most RateLimits::max_fetches_per_second starts in any rolling one-second window.
3. Per-source backoff — at least RateLimits::per_source_backoff_ms between consecutive starts to the same source name.

The returned Permit holds the concurrency slot for the lifetime of the value; drop it when the fetch is done.

429 / Retry-After handling is split: the limiter only exposes the admin hook sleep_for; the actual Retry-After header parse and call lives at the Source::fetch call site, per docs/SOURCES.md §6.

Implementations

impl RateLimiter

pub fn new(limits: RateLimits) -> Self

Construct from the hard-coded RateLimits (the only public path).

pub async fn pace(&self, source: &str)

Wait out the per-source interval for one ADDITIONAL request inside a fetch that already holds a Permit.

#493. arXiv’s terms cap requests, and one arXiv attempt issues two of them – the Atom feed, then the PDF – under a single acquire. The second was previously unpaced, so even a perfectly serialised caller sent two requests back to back.

Does not touch the concurrency slots: the caller already holds them, and taking them again would deadlock at max_concurrent_for == 1, which is exactly the arXiv case.

pub async fn acquire(&self, source: &str) -> Permit

Block until a slot is available, then return a Permit.

Order of waits, in this exact sequence:

1. global concurrency (semaphore acquire),
2. global rate cap (sleep if the rolling-second window is full),
3. per-source backoff (sleep until the source’s next time).

Lock-acquisition order is always global_starts first, THEN per_source_next. Any future call site that needs both locks MUST follow the same order to keep the system deadlock-free.

pub async fn sleep_for(&self, source: &str, dur: Duration)

Tell the limiter to delay further starts to source by at least dur. Used when the source returns 429 with Retry-After.

Trait Implementations

impl Debug for RateLimiter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.