actix-web-ratelimit 0.1.2

A simple and highly customizable rate limiter for actix-web 4
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

# actix-web-ratelimit

A simple and highly customizable rate limiting middleware for actix-web 4.

[![Crates.io](https://img.shields.io/crates/v/actix-web-ratelimit.svg)](https://crates.io/crates/actix-web-ratelimit)
[![Documentation](https://docs.rs/actix-web-ratelimit/badge.svg)](https://docs.rs/actix-web-ratelimit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://img.shields.io/github/actions/workflow/status/bigyao25/actix-web-ratelimit/CI.yml?branch=main)](https://github.com/bigyao25/actix-web-ratelimit/actions/workflows/CI.yml)

[中文文档](README-cn.md)

## Features

- **actix-web 4 Compatible**: Built specifically for actix-web 4
- **Simple & Easy to Use**: Minimal configuration required
- **Expandable Store**: easy to create your own store, In-Memory store and Redis store have been provided
- **High Performance**: Efficient sliding window algorithm
- **Customizable**: Custom client identification and rate limit exceeded handlers
- **Thread Safe**: Concurrent request handling with DashMap

## Quick Start

Add this to your `Cargo.toml`:

```toml
[dependencies]
actix-web-ratelimit = "0.1"

# Or, for Redis support
actix-web-ratelimit = { version = "0.1", features = ["redis"] }
```

## Usage

### Basic Usage with In-Memory Store

```rust
    // Configure rate limiting: allow 3 requests per 10-second window
    let config = RateLimitConfig::default().max_requests(3).window_secs(10);
    // Create in-memory store for tracking request timestamps
    let store = Arc::new(MemoryStore::new());

    HttpServer::new(move || {
        App::new()
            // create and register the rate limit middleware
            .wrap(RateLimit::new(config.clone(), store.clone()))
            .route("/", web::get().to(index))
    })
    .bind(("127.0.0.1", 8080))?
    .run()
    .await
```

### Advanced Configuration

```rust
    let store = Arc::new(MemoryStore::new());
    let config = RateLimitConfig::default()
        .max_requests(3)
        .window_secs(10)
        // Extract client identifier from req. It is IP (realip_remote_addr) by default.
        .id(|req| {
            req.headers()
                .get("X-Client-Id")
                .and_then(|h| h.to_str().ok())
                .unwrap_or("anonymous")
                .to_string()
        })
        // Custom handler for rate limit exceeded. It returns a 429 response by default.
        .exceeded(|id, config, _req| {
            HttpResponse::TooManyRequests().body(format!(
                "429 caused: client-id: {}, limit: {}req/{:?}",
                id, config.max_requests, config.window_secs
            ))
        });

    HttpServer::new(move || {
        App::new()
            .wrap(RateLimit::new(config.clone(), store.clone()))
            .route("/", web::get().to(index))
    })
    .bind(("127.0.0.1", 8080))?
    .run()
    .await
```

### Redis Store

first set feature `redis` enable:

```toml
actix-web-ratelimit = { version = "0.1", features = [ "redis" ] }
```

then you can use it:

```rust
    let store = Arc::new(
        RedisStore::new("redis://127.0.0.1/0")
            .expect("Failed to connect to Redis")
            // Custom prefix for Redis keys
            .with_prefix("myapp:ratelimit:"),
    );
    let config = RateLimitConfig::default().max_requests(3).window_secs(10);

    HttpServer::new(move || {
        App::new()
            .wrap(RateLimit::new(config.clone(), store.clone()))
            .route("/", web::get().to(index))
    })
    .bind(("127.0.0.1", 8080))?
    .run()
    .await
```

## Configuration Options

### RateLimitConfig

| Method | Description | Default |
| ------ | ------ | -------- |
| `max_requests(usize)` | Maximum requests per window | 10 |
| `window_secs(u64)` | Time window in seconds | 100 |
| `id(fn)` | Client identification function | IP address |
| `exceeded(fn)` | Rate limit exceeded handler | 429 response |

### Storage Backends

#### MemoryStore

- **Pros**: Fast, no external dependencies
- **Cons**: Not distributed, data lost on restart
- **Use case**: Single instance applications

#### RedisStore (requires `redis` feature)

- **Pros**: Distributed, persistent, scalable
- **Cons**: Requires Redis server
- **Use case**: Multi-instance applications

## Algorithm

This middleware uses a **sliding window** algorithm:

1. Extract client identifier from request
2. Retrieve stored request timestamps for the client
3. Remove expired timestamps outside the time window
4. Check if remaining request count exceeds the limit
5. If not exceeded, record new timestamp and allow request
6. If exceeded, call the rate limit handler

## Examples

Run the example:

```bash
cargo run --example simple
```

Then test the rate limiting:

```bash
# This should work
curl http://localhost:8080/

# Exceed rate limit by making many requests
for i in {1..5}; do echo "$(curl -s http://localhost:8080)\r"; done
```

## [features]

- `redis`: Enables Redis storage backend support

## License

This project is licensed under the [MIT License](LICENSE).