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 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259
//! Limitador is a generic rate-limiter. //! //! # Basic operation //! //! Limitador can store the limits in memory or in Redis. Storing them in memory //! is faster, but the limits cannot be shared between several instances of //! Limitador. Storing the limits in Redis is slower, but they can be shared //! between instances. //! //! By default, the rate limiter is configured to store the limits in memory: //! ``` //! use limitador::RateLimiter; //! let rate_limiter = RateLimiter::default(); //! ``` //! //! To use Redis: //! ``` //! use limitador::RateLimiter; //! use limitador::storage::redis::RedisStorage; //! //! // Default redis URL (redis://localhost:6379). //! let rate_limiter = RateLimiter::new_with_storage(Box::new(RedisStorage::default())); //! //! // Custom redis URL //! let rate_limiter = RateLimiter::new_with_storage( //! Box::new(RedisStorage::new("redis://127.0.0.1:7777")) //! ); //! ``` //! //! # Limits //! //! The definition of a limit includes: //! - A namespace that identifies the resource to limit. It could be an API, a //! Kubernetes service, a proxy ID, etc. //! - A value. //! - The length of the period in seconds. //! - Conditions that define when to apply the limit. //! - A set of variables. For example, if we need to define the same limit for //! each "user_id", instead of creating a limit for each hardcoded ID, we just //! need to define "user_id" as a variable. //! //! If we used Limitador in a context where it receives an HTTP request we could //! define a limit like this to allow 10 requests per minute and per user_id //! when the HTTP method is "GET". //! //! ``` //! use limitador::limit::Limit; //! let limit = Limit::new( //! "my_namespace", //! 10, //! 60, //! vec!["req.method == GET"], //! vec!["user_id"], //! ); //! ``` //! //! Notice that the keys and variables are generic, so they do not necessarily //! have to refer to an HTTP request. //! //! # Manage limits //! //! ``` //! use limitador::RateLimiter; //! use limitador::limit::Limit; //! let limit = Limit::new( //! "my_namespace", //! 10, //! 60, //! vec!["req.method == GET"], //! vec!["user_id"], //! ); //! let mut rate_limiter = RateLimiter::default(); //! //! // Add a limit //! rate_limiter.add_limit(&limit); //! //! // Delete the limit //! rate_limiter.delete_limit(&limit); //! //! // Get all the limits in a namespace //! rate_limiter.get_limits("my_namespace"); //! //! // Delete all the limits in a namespace //! rate_limiter.delete_limits("my_namespace"); //! ``` //! //! # Apply limits //! //! ``` //! use limitador::RateLimiter; //! use limitador::limit::Limit; //! use std::collections::HashMap; //! //! let mut rate_limiter = RateLimiter::default(); //! //! let limit = Limit::new( //! "my_namespace", //! 2, //! 60, //! vec!["req.method == GET"], //! vec!["user_id"], //! ); //! rate_limiter.add_limit(&limit); //! //! // We've defined a limit of 2. So we can report 2 times before being //! // rate-limited //! let mut values_to_report: HashMap<String, String> = HashMap::new(); //! values_to_report.insert("req.method".to_string(), "GET".to_string()); //! values_to_report.insert("user_id".to_string(), "1".to_string()); //! //! // Check if we can report //! assert!(!rate_limiter.is_rate_limited("my_namespace", &values_to_report, 1).unwrap()); //! //! // Report //! rate_limiter.update_counters("my_namespace", &values_to_report, 1).unwrap(); //! //! // Check and report again //! assert!(!rate_limiter.is_rate_limited("my_namespace", &values_to_report, 1).unwrap()); //! rate_limiter.update_counters("my_namespace", &values_to_report, 1).unwrap(); //! //! // We've already reported 2, so reporting another one should not be allowed //! assert!(rate_limiter.is_rate_limited("my_namespace", &values_to_report, 1).unwrap()); //! //! // You can also check and report if not limited in a single call. It's useful //! // for example, when calling Limitador from a proxy. Instead of doing 2 //! // separate calls, we can issue just one: //! rate_limiter.check_rate_limited_and_update("my_namespace", &values_to_report, 1).unwrap(); //! ``` use crate::counter::Counter; use crate::errors::LimitadorError; use crate::limit::Limit; use crate::storage::in_memory::InMemoryStorage; use crate::storage::Storage; use std::collections::{HashMap, HashSet}; pub mod counter; pub mod errors; pub mod limit; pub mod storage; pub struct RateLimiter { storage: Box<dyn Storage>, } impl RateLimiter { pub fn new() -> RateLimiter { RateLimiter { storage: Box::new(InMemoryStorage::default()), } } pub fn new_with_storage(storage: Box<dyn Storage>) -> RateLimiter { RateLimiter { storage } } pub fn add_limit(&mut self, limit: &Limit) -> Result<(), LimitadorError> { self.storage.add_limit(limit).map_err(|err| err.into()) } pub fn delete_limit(&mut self, limit: &Limit) -> Result<(), LimitadorError> { self.storage.delete_limit(limit).map_err(|err| err.into()) } pub fn get_limits(&self, namespace: &str) -> Result<HashSet<Limit>, LimitadorError> { self.storage.get_limits(namespace).map_err(|err| err.into()) } pub fn delete_limits(&mut self, namespace: &str) -> Result<(), LimitadorError> { self.storage .delete_limits(namespace) .map_err(|err| err.into()) } pub fn is_rate_limited( &self, namespace: &str, values: &HashMap<String, String>, delta: i64, ) -> Result<bool, LimitadorError> { let counters = self.counters_that_apply(namespace, values)?; for counter in counters { match self.storage.is_within_limits(&counter, delta) { Ok(within_limits) => { if !within_limits { return Ok(true); } } Err(e) => return Err(e.into()), } } Ok(false) } pub fn update_counters( &mut self, namespace: &str, values: &HashMap<String, String>, delta: i64, ) -> Result<(), LimitadorError> { let counters = self.counters_that_apply(namespace, values)?; counters .iter() .try_for_each(|counter| self.storage.update_counter(&counter, delta)) .map_err(|err| err.into()) } pub fn check_rate_limited_and_update( &mut self, namespace: &str, values: &HashMap<String, String>, delta: i64, ) -> Result<bool, LimitadorError> { match self.is_rate_limited(namespace, values, delta) { Ok(rate_limited) => { if rate_limited { Ok(true) } else { match self.update_counters(namespace, values, delta) { Ok(_) => Ok(false), Err(e) => Err(e), } } } Err(e) => Err(e), } } pub fn get_counters(&mut self, namespace: &str) -> Result<HashSet<Counter>, LimitadorError> { self.storage .get_counters(namespace) .map_err(|err| err.into()) } fn counters_that_apply( &self, namespace: &str, values: &HashMap<String, String>, ) -> Result<Vec<Counter>, LimitadorError> { let limits = self.get_limits(namespace)?; let counters = limits .iter() .filter(|lim| lim.applies(values)) .map(|lim| Counter::new(lim.clone(), values.clone())) .collect(); Ok(counters) } } impl Default for RateLimiter { fn default() -> Self { Self::new() } }