governor/
lib.rs

1//! # governor - a rate-limiting library for rust.
2//!
3//! Governor aims to be a very efficient and ergonomic way to enforce
4//! rate limits in Rust programs. It implements the [Generic Cell Rate
5//! Algorithm](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm)
6//! and keeps state in a very efficient way.
7//!
8//! For detailed information on usage, please see the [user's guide][crate::_guide].
9//!
10//! # Quick example
11//!
12//! In this example, we set up a rate limiter to allow 50 elements per
13//! second, and check that a single element can pass through.
14//!
15//! ``` rust
16//! use std::num::NonZeroU32;
17//! use nonzero_ext::*;
18//! use governor::{Quota, RateLimiter};
19//!
20//! # #[cfg(feature = "std")]
21//! # fn main () {
22//! let mut lim = RateLimiter::direct(Quota::per_second(nonzero!(50u32))); // Allow 50 units per second
23//! assert_eq!(Ok(()), lim.check());
24//! # }
25//! # #[cfg(not(feature = "std"))]
26//! # fn main() {}
27//! ```
28//!
29
30#![cfg_attr(docsrs, feature(doc_auto_cfg))]
31#![cfg_attr(not(feature = "std"), no_std)]
32// Clippy config: Deny warnings but allow unknown lint configuration (so I can use nightly)
33#![deny(warnings)]
34#![allow(unknown_lints)]
35// Unfortunately necessary, otherwise features aren't supported in doctests:
36#![allow(clippy::needless_doctest_main)]
37
38extern crate alloc;
39
40pub mod r#_guide;
41pub mod clock;
42mod errors;
43mod gcra;
44#[cfg(any(feature = "std", feature = "jitter"))]
45mod jitter;
46pub mod middleware;
47pub mod nanos;
48mod quota;
49pub mod state;
50
51pub use errors::*;
52pub use gcra::NotUntil;
53#[cfg(feature = "jitter")]
54pub use jitter::Jitter;
55#[cfg(all(feature = "std", not(feature = "jitter")))]
56pub(crate) use jitter::Jitter;
57pub use quota::Quota;
58#[doc(inline)]
59pub use state::RateLimiter;
60
61#[cfg(feature = "std")]
62pub use state::direct::RatelimitedSink;
63#[cfg(feature = "std")]
64pub use state::direct::RatelimitedStream;
65
66/// The collection of asynchronous traits exported from this crate.
67pub mod prelude {
68    #[cfg(feature = "std")]
69    pub use crate::state::direct::SinkRateLimitExt;
70    #[cfg(feature = "std")]
71    pub use crate::state::direct::StreamRateLimitExt;
72}
73
74/// A rate limiter representing a single item of state in memory, running on the default clock.
75///
76/// See the [`RateLimiter`] documentation for details.
77pub type DefaultDirectRateLimiter<
78    MW = middleware::NoOpMiddleware<<clock::DefaultClock as clock::Clock>::Instant>,
79> = RateLimiter<state::direct::NotKeyed, state::InMemoryState, clock::DefaultClock, MW>;
80
81/// A rate limiter with one state per key, running on the default clock.
82///
83/// See the [`RateLimiter`] documentation for details.
84pub type DefaultKeyedRateLimiter<
85    K,
86    MW = middleware::NoOpMiddleware<<clock::DefaultClock as clock::Clock>::Instant>,
87    S = state::keyed::DefaultHasher,
88> = RateLimiter<K, state::keyed::DefaultKeyedStateStore<K, S>, clock::DefaultClock, MW>;
governor/lib.rs

governor/
lib.rs
