actix_rl/
lib.rs

1//! # `actix-rl`: RateLimiter for `actix-web`
2
3//! ## Description
4//! `actix-rl` is a RateLimit middleware for the `actix-web` library.
5//! It supports asynchronous processing and currently provides two storage options:
6//! in-memory storage (`MemStore`) and Redis storage (`RedisStore`).
7
8//! If you have other storage options, feel free to submit a Pull Request.
9//! PR is welcome.
10
11//! ## Features
12//! |    Feature    |  Component   |                                    Description                                    |
13//! |:-------------:|:------------:|:---------------------------------------------------------------------------------:|
14//! |   `default`   |  `MemStore`  |                               Store data in memory                                |
15//! | `redis-store` | `RedisStore` | Store data using an async connection from [redis](https://crates.io/crates/redis) |
16
17//! ## Usage
18//! 1. Define a `Store` where the program stores information and sets timeouts.
19//! 2. Define a `Controller`. The `Controller` is used to define middleware
20//!    response behaviors, such as how to return HTTP information during exceptions.
21//!    You can also use the library's provided default functions,
22//!    but in most cases, you will need to customize the response to return necessary limit information to the client.
23//! 3. Finally, add a `Middleware` to your HTTP Server using the `wrap` function (from `actix-web`).
24
25//! ### Examples
26//! You can find examples in `examples` folder.
27
28//! ### Store
29//! The `Store` is used to store caching information.
30
31//! Let's take `MemCache` as an example:
32
33//! ```rust
34//! // data timeout for each key is 10 seconds, with 1024 init capacity.
35//! let store = actix_rl::store::mem_store::MemStore::new(1024, chrono::Duration::seconds(10));
36//! ```
37
38//! ### Controller
39//! `Controller` is a set of functions. To create a default one:
40//! ```rust
41//! let controller = actix_rl::controller::Controller::new();
42//! ```
43
44//! You can determine which requests should be checked, by modifying `Controller`:
45//! ```rust
46//! let controller = actix_rl::controller::Controller::new();
47//! let controller = controller.with_do_rate_limit(|req| !req.path().start_with("/healthz"));
48//! ```
49
50//! In this case, only those requests without prefix `/healthz` will be checked by RateLimiter.
51
52//! For more functions, please check the doc of `Controller`.
53
54//! ### RateLimiter
55//! Define a `RateLimiter` and `wrap` to HTTP server:
56
57//! ```rust
58//! let rate_limiter = actix_rl::middleware::RateLimitMiddleware::new(
59//!     store,
60//!     10, // max count is 10, which means max 10 hits per 10 seconds.
61//!     controller,
62//! );
63//! ```
64
65//! Then, add it to `actix-web` HTTP server wrap:
66//! ```rust
67//! App::new()
68//!    .wrap(rate_limiter)
69//!     // ...
70//! ```
71
72pub mod store;
73pub mod middleware;
74pub mod error;
75pub mod controller;
76pub mod utils;