Crate actix_ratelimit

Rate limiting middleware framework for actix-web

This crate provides an asynchronous and concurrent rate limiting middleware based on actor model which can be wraped around an Actix application. Middleware contains a store which is used to identify client request.

Check out the documentation here.

Comments, suggesstions and critiques are welcomed!

Usage

Add this to your Cargo.toml:

[dependencies]
actix-ratelimit = "0.3.1"

Minimal example:

use actix_web::{web, App, HttpRequest, HttpServer, Responder};
use actix_ratelimit::{RateLimiter, MemoryStore, MemoryStoreActor};

async fn greet(req: HttpRequest) -> impl Responder{
    let name = req.match_info().get("name").unwrap_or("World!");
    format!("Hello {}!", &name)
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    // Initialize store
    let store = MemoryStore::new();
    HttpServer::new(move ||{
        App::new()
            // Register the middleware
            // which allows for a maximum of
            // 100 requests per minute per client
            // based on IP address
            .wrap(
                RateLimiter::new(
                MemoryStoreActor::from(store.clone()).start())
                    .with_interval(Duration::from_secs(60))
                    .with_max_requests(100)
            )
            .route("/", web::get().to(greet))
            .route("/{name}", web::get().to(greet))
    })
    .bind("127.0.0.1:8000")?
    .run()
    .await
}

Sending a request returns a response with the ratelimiting headers:

$ curl -i "http://localhost:8000/"

HTTP/1.1 200 OK
content-length: 13
content-type: text/plain; charset=utf-8
x-ratelimit-remaining: 99
x-ratelimit-reset: 52
x-ratelimit-limit: 100
date: Tue, 04 Feb 2020 21:53:27 GMT

Hello World!

Exceeding the limit returns HTTP 429 Error code.

Stores

A store is a data structure, database connection or anything which can be used to store ratelimit data associated with a client. A store actor which acts on this store is responsible for performiing all sorts of operations(SET, GET, DEL, etc). It is Important to note that there are multiple store actors acting on a single store.

Supported

• In-memory (based on concurrent hashmap)
• Redis (based on redis-rs)

Planned

• Memcached (not yet implemented)

Implementing your own store

To implement your own store, you have to implement an Actor which can handle ActorMessage type and return ActorResponse type. Check the module level documentation for more details and a basic example.

Note to developers

• To use redis store, put this to your Cargo.toml:

[dependencies]
actix-ratelimit = {version = "0.3.1", default-features = false, features = ["redis-store"]}

• By default, the client’s IP address is used as the identifier which can be customized using ServiceRequest instance. For example, using api key header to identify client:

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    // Initialize store
    let store = MemoryStore::new();
    HttpServer::new(move ||{
        App::new()
            .wrap(
                RateLimiter::new(
                MemoryStoreActor::from(store.clone()).start())
                    .with_interval(Duration::from_secs(60))
                    .with_max_requests(100)
                    .with_identifier(|req| {
                        let key = req.headers().get("x-api-key").unwrap();
                        let key = key.to_str().unwrap();
                        Ok(key.to_string())
                    })
            )
            .route("/", web::get().to(greet))
            .route("/{name}", web::get().to(greet))
    })
    .bind("127.0.0.1:8000")?
    .run()
    .await
}

• It is important to initialize store before creating HttpServer instance, or else a store will be created for each web worker. This may lead to instability and inconsistency! For example, initializing your app in the following manner would create more than one stores:

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(move ||{
        App::new()
            .wrap(
                RateLimiter::new(
                MemoryStoreActor::from(MemoryStore::new()).start())
                    .with_interval(Duration::from_secs(60))
                    .with_max_requests(100)
            )
            .route("/", web::get().to(greet))
            .route("/{name}", web::get().to(greet))
    })
    .bind("127.0.0.1:8000")?
    .run()
    .await
}

• The exception is redis, where multiple connections will be created for each worker. Since redis store is based on Multiplexed connection, sharing once connection across multiple store actors should suffice for most use cases.

Status

This project has not reached v1.0, so some instability and breaking changes are to be expected till then.

You can use the issue tracker in case you encounter any problems.

LICENSE

This project is licensed under MIT license.

Re-exports

pub use middleware::RateLimiter;

pub use stores::memory::MemoryStore;

pub use stores::memory::MemoryStoreActor;

pub use stores::redis::RedisStore;

pub use stores::redis::RedisStoreActor;

pub use stores::memcached::MemcacheStore;

pub use stores::memcached::MemcacheStoreActor;

Modules

errors

Errors that can occur during middleware processing stage

middleware

RateLimiter middleware for actix application

stores

Type used to store ratelimiter data associated with a client.

Enums

ActorMessage

Represents message that can be handled by a StoreActor

ActorResponse

Represents data returned in response to Messages by a StoreActor

Type Aliases

Output

Wrapper type for Pin<Box<dyn Future>> type