🪣Implement Token Bucket algorithm

Closes #1

CHANGELOG.md

···
 
 ## [Unreleased]
 
-### Changed
+### Breaking changes
 
-- Deprecated `glimit.handler` and renamed it to the more descriptive `glimit.on_limit_exceeded`.
+- Refactored the code to use a Token Bucket algorithm instead of a Sliding Window algorithm. This has removed some of the library features/API, such as `glimit.applyX` to apply a rate limiter on a function with multiple arguments.
+
+### Added
+
+- Added a `burst_limit` setting to the limiter configuration. This setting allows the user to set the maximum number of tokens that the bucket can hold.
 
 
 ## v0.1.3 - 2024-09-04

README.md

···
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/glimit/)
 [![test](https://github.com/nootr/glimit/actions/workflows/test.yml/badge.svg)](https://github.com/nootr/glimit/actions/workflows/test.yml)
 
-A framework-agnostic rate limiter for Gleam. 💫
+A simple, framework-agnostic, in-memory rate limiter for Gleam. 💫
 
 > ⚠️  This library is still in development, use at your own risk.
+
+
+## Features
+
+* ✨ Simple and easy to use.
+* 📏 Rate limits based on any key (e.g. IP address, or user ID).
+* 🪣 Uses a distributed Token Bucket algorithm to rate limit requests.
+* 🗄️ No back-end service needed; stores rate limit stats in-memory.
 
 
 ## Usage
···
   let limiter =
     glimit.new()
     |> glimit.per_second(10)
-    |> glimit.per_minute(100)
-    |> glimit.per_hour(1000)
     |> glimit.identifier(get_identifier)
     |> glimit.on_limit_exceeded(rate_limit_reached)
     |> glimit.build
···
 ```
 
 
-## How it works
+## Constraints
 
-Once v1.0 is reached, `glimit` will use a distributed Token Bucket algorithm to rate limit requests. It will support multiple backend storage systems, such as Redis and in-memory storage.
+While the in-memory rate limiter is simple and easy to use, it does have an important constraint: it is scoped to the BEAM VM cluster it runs in. This means that if your application is running across multiple BEAM VM clusters, the rate limiter will not be shared between them.
 
-However, at the moment, `glimit` uses a simple Sliding Window algorithm with in-memory storage. This means that the rate limiter is not memory efficient and is not ready for production use.
+There are plans to add support for a centralized data store using Redis in the future.
 
 
 ## Documentation
 
-Further documentation can be found at <https://hexdocs.pm/glimit>.
+Further documentation can be found at <https://hexdocs.pm/glimit/glimit.html>.
 
 
 ## Contributing

gleam.toml

···
 name = "glimit"
 version = "0.1.3"
 
-description = "A framework-agnostic rate limiter for Gleam."
+description = "A simple, framework-agnostic, in-memory rate limiter for Gleam."
 licences = ["MIT"]
 repository = { type = "github", user = "nootr", repo = "glimit" }
 target = "erlang"
+internal_modules = [
+  "glimit/*",
+]
 
 [dependencies]
 gleam_stdlib = ">= 0.34.0 and < 2.0.0"

src/glimit.gleam

···
-//// A framework-agnostic rate limiter for Gleam. 💫
+//// This module provides a distributed rate limiter that can be used to limit the
+//// number of requests or function calls per second for a given identifier.
 ////
-//// This module provides a rate limiter that can be used to limit the number of
-//// requests that can be made to a given function or handler within a given
-//// time frame.
+//// A single actor is used to assign one rate limiter actor per identifier. The
+//// rate limiter actor then uses a Token Bucket algorithm to determine if a
+//// request or function call should be allowed to proceed. A separate process is
+//// polling the rate limiters to remove full buckets to reduce unnecessary memory
+//// usage.
+////
+//// The rate limits are configured using the following two options:
 ////
-//// The rate limiter is implemented as an actor that keeps track of the number
-//// of hits for a given identifier within the last second, minute, and hour.
-//// When a hit is received, the actor checks the rate limits and either allows
-//// the hit to pass or rejects it.
+//// - `per_second`: The rate of new available tokens per second. Think of this
+////   as the steady state rate limit.
+//// - `burst_limit`: The maximum number of available tokens. Think of this as
+////   the burst rate limit. The default value is the `per_second` rate limit.
 ////
-//// The rate limiter can be configured with rate limits per second, minute, and
-//// hour, and a handler function that is called when the rate limit is reached.
 //// The rate limiter can be applied to a function or handler using the `apply`
 //// function, which returns a new function that checks the rate limit before
 //// calling the original function.
···
 //// let limiter =
 ////   glimit.new()
 ////   |> glimit.per_second(10)
-////   |> glimit.per_minute(100)
-////   |> glimit.per_hour(1000)
 ////   |> glimit.identifier(fn(request) { request.ip })
 ////   |> glimit.on_limit_exceeded(fn(_request) { "Rate limit reached" })
 ////   |> glimit.build()
···
 //// ```
 ////
 
-import gleam/erlang/process.{type Subject}
 import gleam/option.{type Option, None, Some}
 import gleam/result
-import glimit/actor
+import glimit/rate_limiter
+import glimit/registry.{type RateLimiterRegistryActor}
 
 /// A rate limiter.
 ///
 pub type RateLimiter(a, b, id) {
   RateLimiter(
-    subject: Subject(actor.Message(id)),
+    rate_limiter_registry: RateLimiterRegistryActor(id),
     on_limit_exceeded: fn(a) -> b,
     identifier: fn(a) -> id,
   )
···
 pub type RateLimiterBuilder(a, b, id) {
   RateLimiterBuilder(
     per_second: Option(Int),
-    per_minute: Option(Int),
-    per_hour: Option(Int),
+    burst_limit: Option(Int),
     identifier: Option(fn(a) -> id),
     on_limit_exceeded: Option(fn(a) -> b),
   )
···
 pub fn new() -> RateLimiterBuilder(a, b, id) {
   RateLimiterBuilder(
     per_second: None,
-    per_minute: None,
-    per_hour: None,
+    burst_limit: None,
     identifier: None,
     on_limit_exceeded: None,
   )
···
 
 /// Set the rate limit per second.
 ///
+/// The value is not only used for the rate at which tokens are added to the bucket, but
+/// also for the maximum number of available tokens. To set a different value fo the
+/// maximum number of available tokens, use the `burst_limit` function.
+///
 pub fn per_second(
   limiter: RateLimiterBuilder(a, b, id),
   limit: Int,
···
   RateLimiterBuilder(..limiter, per_second: Some(limit))
 }
 
-/// Set the rate limit per minute.
+/// Set the maximum number of available tokens.
 ///
-pub fn per_minute(
-  limiter: RateLimiterBuilder(a, b, id),
-  limit: Int,
-) -> RateLimiterBuilder(a, b, id) {
-  RateLimiterBuilder(..limiter, per_minute: Some(limit))
-}
-
-/// Set the rate limit per hour.
+/// The maximum number of available tokens is the maximum number of requests that can be
+/// made in a single second. The default value is the same as the rate limit per second.
 ///
-pub fn per_hour(
+pub fn burst_limit(
   limiter: RateLimiterBuilder(a, b, id),
-  limit: Int,
+  burst_limit: Int,
 ) -> RateLimiterBuilder(a, b, id) {
-  RateLimiterBuilder(..limiter, per_hour: Some(limit))
+  RateLimiterBuilder(..limiter, burst_limit: Some(burst_limit))
 }
 
 /// Set the handler to be called when the rate limit is reached.
 ///
 pub fn on_limit_exceeded(
-  limiter: RateLimiterBuilder(a, b, id),
-  on_limit_exceeded: fn(a) -> b,
-) -> RateLimiterBuilder(a, b, id) {
-  RateLimiterBuilder(..limiter, on_limit_exceeded: Some(on_limit_exceeded))
-}
-
-@deprecated("Use `on_limit_exceeded` instead")
-pub fn handler(
   limiter: RateLimiterBuilder(a, b, id),
   on_limit_exceeded: fn(a) -> b,
 ) -> RateLimiterBuilder(a, b, id) {
···
 
 /// Build the rate limiter.
 ///
-/// Panics if the rate limiter actor cannot be started or if the identifier
-/// function or on_limit_exceeded function is missing.
+/// Panics if the rate limiter registry cannot be started or if the `identifier`
+/// function or `on_limit_exceeded` function is missing.
+///
+/// To handle errors instead of panicking, use `try_build`.
 ///
 pub fn build(config: RateLimiterBuilder(a, b, id)) -> RateLimiter(a, b, id) {
   case try_build(config) {
···
 pub fn try_build(
   config: RateLimiterBuilder(a, b, id),
 ) -> Result(RateLimiter(a, b, id), String) {
-  use subject <- result.try(
-    actor.new(config.per_second, config.per_minute, config.per_hour)
-    |> result.map_error(fn(_) { "Failed to start rate limiter actor" }),
+  use per_second <- result.try(case config.per_second {
+    Some(per_second) -> Ok(per_second)
+    None -> Error("`per_second` rate limit is required")
+  })
+  let burst_limit = case config.burst_limit {
+    Some(burst_limit) -> burst_limit
+    None -> per_second
+  }
+  use rate_limiter_registry <- result.try(
+    registry.new(per_second, burst_limit)
+    |> result.map_error(fn(_) { "Failed to start rate limiter registry" }),
   )
   use identifier <- result.try(case config.identifier {
     Some(identifier) -> Ok(identifier)
···
   })
 
   Ok(RateLimiter(
-    subject: subject,
+    rate_limiter_registry: rate_limiter_registry,
     on_limit_exceeded: on_limit_exceeded,
     identifier: identifier,
   ))
···
 pub fn apply(func: fn(a) -> b, limiter: RateLimiter(a, b, id)) -> fn(a) -> b {
   fn(input: a) -> b {
     let identifier = limiter.identifier(input)
-    case actor.hit(limiter.subject, identifier) {
-      Ok(Nil) -> func(input)
-      Error(Nil) -> limiter.on_limit_exceeded(input)
-    }
-  }
-}
-
-/// Apply the rate limiter to a request handler or function with two arguments.
-///
-/// Note: this function folds the two arguments into a tuple before passing them to the
-/// identifier or on_limit_exceeded functions.
-///
-/// # Example
-///
-/// ```gleam
-/// import glimit
-///
-/// let limiter =
-///   glimit.new()
-///   |> glimit.per_hour(1000)
-///   |> glimit.identifier(fn(i: #(String, String)) {
-///     let #(a, _) = i
-///     a
-///   })
-///   |> glimit.on_limit_exceeded(fn(_) { "Rate limit reached" })
-///   |> glimit.build()
-///
-/// let handler =
-///   fn(a, b) { a <> b }
-///   |> glimit.apply2(limiter)
-/// ```
-pub fn apply2(
-  func: fn(a, b) -> c,
-  limiter: RateLimiter(#(a, b), c, id),
-) -> fn(a, b) -> c {
-  fn(a: a, b: b) -> c {
-    let identifier = limiter.identifier(#(a, b))
-    case actor.hit(limiter.subject, identifier) {
-      Ok(Nil) -> func(a, b)
-      Error(Nil) -> limiter.on_limit_exceeded(#(a, b))
-    }
-  }
-}
-
-/// Apply the rate limiter to a request handler or function with three arguments.
-///
-/// Note: this function folds the three arguments into a tuple before passing them to the
-/// identifier or on_limit_exceeded functions.
-///
-pub fn apply3(
-  func: fn(a, b, c) -> d,
-  limiter: RateLimiter(#(a, b, c), d, id),
-) -> fn(a, b, c) -> d {
-  fn(a: a, b: b, c: c) -> d {
-    let identifier = limiter.identifier(#(a, b, c))
-    case actor.hit(limiter.subject, identifier) {
-      Ok(Nil) -> func(a, b, c)
-      Error(Nil) -> limiter.on_limit_exceeded(#(a, b, c))
-    }
-  }
-}
-
-/// Apply the rate limiter to a request handler or function with four arguments.
-///
-/// Note: this function folds the four arguments into a tuple before passing them to the
-/// identifier or on_limit_exceeded functions.
-///
-/// > ⚠️ For functions with more than four arguments, you'll need to write a custom
-/// > wrapper function that folds the arguments into a tuple before passing them to the
-/// > rate limiter. This is because Gleam does not support variadic functions, because
-/// > the BEAM VM identifies functions by their arity.
-///
-pub fn apply4(
-  func: fn(a, b, c, d) -> e,
-  limiter: RateLimiter(#(a, b, c, d), e, id),
-) -> fn(a, b, c, d) -> e {
-  fn(a: a, b: b, c: c, d: d) -> e {
-    let identifier = limiter.identifier(#(a, b, c, d))
-    case actor.hit(limiter.subject, identifier) {
-      Ok(Nil) -> func(a, b, c, d)
-      Error(Nil) -> limiter.on_limit_exceeded(#(a, b, c, d))
+    case limiter.rate_limiter_registry |> registry.get_or_create(identifier) {
+      Ok(rate_limiter) -> {
+        case rate_limiter |> rate_limiter.hit {
+          Ok(Nil) -> func(input)
+          Error(Nil) -> limiter.on_limit_exceeded(input)
+        }
+      }
+      Error(_) -> panic as "Failed to get rate limiter"
     }
   }
 }

src/glimit/actor.gleam

···
-//// The rate limiter actor.
-////
-
-import gleam/dict
-import gleam/erlang/process.{type Subject}
-import gleam/list
-import gleam/option.{type Option, None, Some}
-import gleam/otp/actor
-import gleam/result
-import glimit/utils
-
-/// The messages that the actor can receive.
-///
-pub type Message(id) {
-  /// Stop the actor.
-  Shutdown
-
-  /// Mark a hit for a given identifier.
-  Hit(identifier: id, reply_with: Subject(Result(Nil, Nil)))
-}
-
-/// The actor state.
-///
-type State(a, b, id) {
-  RateLimiterState(
-    hit_log: dict.Dict(id, List(Int)),
-    per_second: Option(Int),
-    per_minute: Option(Int),
-    per_hour: Option(Int),
-  )
-}
-
-fn handle_message(
-  message: Message(id),
-  state: State(a, b, id),
-) -> actor.Next(Message(id), State(a, b, id)) {
-  case message {
-    Shutdown -> actor.Stop(process.Normal)
-    Hit(identifier, client) -> {
-      // Update hit log
-      let timestamp = utils.now()
-      let hits =
-        state.hit_log
-        |> dict.get(identifier)
-        |> result.unwrap([])
-        |> list.filter(fn(hit) { hit >= timestamp - 60 * 60 })
-        |> list.append([timestamp])
-      let hit_log =
-        state.hit_log
-        |> dict.insert(identifier, hits)
-      let state = RateLimiterState(..state, hit_log: hit_log)
-
-      // Check rate limits
-      // TODO: optimize into a single loop
-      let hits_last_hour = hits |> list.length()
-
-      let hits_last_minute =
-        hits
-        |> list.filter(fn(hit) { hit >= timestamp - 60 })
-        |> list.length()
-
-      let hits_last_second =
-        hits
-        |> list.filter(fn(hit) { hit >= timestamp - 1 })
-        |> list.length()
-
-      let limit_reached = {
-        case state.per_hour {
-          Some(limit) -> hits_last_hour > limit
-          None -> False
-        }
-        || case state.per_minute {
-          Some(limit) -> hits_last_minute > limit
-          None -> False
-        }
-        || case state.per_second {
-          Some(limit) -> hits_last_second > limit
-          None -> False
-        }
-      }
-
-      case limit_reached {
-        True -> process.send(client, Error(Nil))
-        False -> process.send(client, Ok(Nil))
-      }
-
-      actor.continue(state)
-    }
-  }
-}
-
-/// Create a new rate limiter actor.
-///
-pub fn new(
-  per_second: Option(Int),
-  per_minute: Option(Int),
-  per_hour: Option(Int),
-) -> Result(Subject(Message(id)), Nil) {
-  let state =
-    RateLimiterState(
-      hit_log: dict.new(),
-      per_second: per_second,
-      per_minute: per_minute,
-      per_hour: per_hour,
-    )
-  actor.start(state, handle_message)
-  |> result.nil_error
-}
-
-/// Log a hit for a given identifier.
-///
-pub fn hit(subject: Subject(Message(id)), identifier: id) -> Result(Nil, Nil) {
-  actor.call(subject, Hit(identifier, _), 10)
-}
-
-/// Stop the actor.
-///
-pub fn stop(subject: Subject(Message(id))) {
-  actor.send(subject, Shutdown)
-}

src/glimit/rate_limiter.gleam

···
+//// This module contains the implementation of a single rate limiter actor.
+////
+
+import gleam/erlang/process.{type Subject}
+import gleam/int
+import gleam/option.{type Option, None, Some}
+import gleam/otp/actor
+import gleam/result
+import glimit/utils
+
+type State {
+  State(
+    /// The maximum number of tokens.
+    ///
+    max_token_count: Int,
+    /// The rate of token generation per second.
+    ///
+    token_rate: Int,
+    /// The number of tokens available.
+    ///
+    token_count: Int,
+    /// Epoch timestamp of the last time the rate limiter was updated.
+    ///
+    last_update: Option(Int),
+  )
+}
+
+/// Updates the state to reflect the passage of time.
+///
+fn refill_bucket(state: State) -> State {
+  let now = utils.now()
+  let time_diff = case state.last_update {
+    None -> 0
+    Some(last_update) -> now - last_update
+  }
+  let token_count =
+    state.token_count + state.token_rate * time_diff
+    |> int.min(state.max_token_count)
+    |> int.max(0)
+
+  State(..state, token_count: token_count, last_update: Some(now))
+}
+
+/// Updates the state to remove a token.
+///
+fn remove_token(state: State) -> State {
+  State(..state, token_count: state.token_count - 1)
+}
+
+/// The message type for the rate limiter actor.
+///
+pub type Message {
+  /// Stop the actor.
+  ///
+  Shutdown
+
+  /// Mark a hit.
+  ///
+  /// The actor will reply with the result of the hit.
+  ///
+  Hit(reply_with: Subject(Result(Nil, Nil)))
+
+  /// Returns True if the token bucket is full.
+  ///
+  HasFullBucket(reply_with: Subject(Bool))
+}
+
+fn handle_message(message: Message, state: State) -> actor.Next(Message, State) {
+  case message {
+    Shutdown -> actor.Stop(process.Normal)
+
+    Hit(client) -> {
+      let state = refill_bucket(state)
+      let #(result, state) = case state.token_count {
+        0 -> #(Error(Nil), state)
+        _ -> #(Ok(Nil), remove_token(state))
+      }
+
+      actor.send(client, result)
+      actor.continue(state)
+    }
+
+    HasFullBucket(client) -> {
+      let state = refill_bucket(state)
+      let result = state.token_count == state.max_token_count
+
+      actor.send(client, result)
+      actor.continue(state)
+    }
+  }
+}
+
+/// Create a new rate limiter actor.
+///
+pub fn new(
+  max_token_count: Int,
+  token_rate: Int,
+) -> Result(Subject(Message), Nil) {
+  let state =
+    State(
+      max_token_count: max_token_count,
+      token_rate: token_rate,
+      token_count: max_token_count,
+      last_update: None,
+    )
+  actor.start(state, handle_message)
+  |> result.nil_error
+}
+
+/// Mark a hit on the rate limiter actor.
+///
+pub fn hit(rate_limiter: Subject(Message)) -> Result(Nil, Nil) {
+  actor.call(rate_limiter, Hit, 10)
+}
+
+/// Returns True if the token bucket is full.
+///
+pub fn has_full_bucket(rate_limiter: Subject(Message)) -> Bool {
+  actor.call(rate_limiter, HasFullBucket, 10)
+}

src/glimit/registry.gleam

···
+//// This module contains a registry which maps hit identifiers to rate limiter actors.
+////
+
+import gleam/dict.{type Dict}
+import gleam/erlang/process.{type Subject}
+import gleam/list
+import gleam/otp/actor
+import gleam/otp/task
+import gleam/result
+import glimit/rate_limiter
+
+pub type RateLimiterRegistryActor(id) =
+  Subject(Message(id))
+
+/// The rate limiter registry state.
+type State(id) {
+  State(
+    /// The maximum number of tokens.
+    ///
+    max_token_count: Int,
+    /// The rate of token generation per second.
+    ///
+    token_rate: Int,
+    /// The registry of rate limiters.
+    ///
+    registry: Dict(id, Subject(rate_limiter.Message)),
+  )
+}
+
+pub type Message(id) {
+  /// Get the rate limiter for the given id or create a new one if missing.
+  ///
+  GetOrCreate(
+    identifier: id,
+    reply_with: Subject(Result(Subject(rate_limiter.Message), Nil)),
+  )
+  Sweep
+}
+
+fn handle_get_or_create(
+  identifier,
+  state: State(id),
+) -> Result(Subject(rate_limiter.Message), Nil) {
+  case state.registry |> dict.get(identifier) {
+    Ok(rate_limiter) -> {
+      Ok(rate_limiter)
+    }
+    Error(_) -> {
+      use rate_limiter <- result.try(rate_limiter.new(
+        state.max_token_count,
+        state.token_rate,
+      ))
+      Ok(rate_limiter)
+    }
+  }
+}
+
+/// Shutdown and remove all rate limiters that are not alive.
+///
+fn handle_message(
+  message: Message(id),
+  state: State(id),
+) -> actor.Next(Message(id), State(id)) {
+  case message {
+    GetOrCreate(identifier, client) -> {
+      case handle_get_or_create(identifier, state) {
+        Ok(rate_limiter) -> {
+          let registry = state.registry |> dict.insert(identifier, rate_limiter)
+          let state = State(..state, registry: registry)
+          actor.send(client, Ok(rate_limiter))
+          actor.continue(state)
+        }
+        Error(_) -> {
+          actor.send(client, Error(Nil))
+          actor.continue(state)
+        }
+      }
+    }
+    Sweep -> {
+      let full_buckets =
+        state.registry
+        |> dict.to_list
+        |> list.filter(fn(pair) {
+          let #(_, rate_limiter) = pair
+          rate_limiter |> rate_limiter.has_full_bucket
+        })
+        |> list.map(fn(pair) {
+          let #(identifier, rate_limiter) = pair
+          actor.send(rate_limiter, rate_limiter.Shutdown)
+          identifier
+        })
+
+      let registry = state.registry |> dict.drop(full_buckets)
+
+      let state = State(..state, registry: registry)
+
+      actor.continue(state)
+    }
+  }
+}
+
+/// Create a new rate limiter registry.
+///
+pub fn new(
+  per_second: Int,
+  burst_limit: Int,
+) -> Result(RateLimiterRegistryActor(id), Nil) {
+  let state =
+    State(
+      max_token_count: burst_limit,
+      token_rate: per_second,
+      registry: dict.new(),
+    )
+  use registry <- result.try(
+    actor.start(state, handle_message)
+    |> result.nil_error,
+  )
+
+  task.async(fn() { sweep_loop(registry) })
+
+  Ok(registry)
+}
+
+/// Get the rate limiter for the given id or create a new one if missing.
+///
+pub fn get_or_create(
+  registry: RateLimiterRegistryActor(id),
+  identifier: id,
+) -> Result(Subject(rate_limiter.Message), Nil) {
+  actor.call(registry, GetOrCreate(identifier, _), 10)
+}
+
+fn sweep_loop(registry: RateLimiterRegistryActor(id)) {
+  process.sleep(10_000)
+  sweep(registry)
+  sweep_loop(registry)
+}
+
+/// Sweep the registry and remove all rate limiters that have a full bucket.
+///
+pub fn sweep(registry: RateLimiterRegistryActor(id)) {
+  actor.send(registry, Sweep)
+}

test/glimit_rate_limiter_test.gleam

···
+import gleeunit/should
+import glimit/rate_limiter
+
+// TODO: find a way to mock time so we can test the refilling of the rate limiter.
+
+pub fn rate_limiter_test() {
+  let limiter = case rate_limiter.new(2, 2) {
+    Ok(limiter) -> limiter
+    Error(_) -> panic as "Should be able to create rate limiter"
+  }
+
+  limiter
+  |> rate_limiter.hit
+  |> should.be_ok
+
+  limiter
+  |> rate_limiter.hit
+  |> should.be_ok
+
+  limiter
+  |> rate_limiter.hit
+  |> should.be_error
+}

test/glimit_registry_test.gleam

···
+import gleeunit/should
+import glimit/rate_limiter
+import glimit/registry
+
+pub fn same_id_same_actor_test() {
+  let registry = case registry.new(2, 2) {
+    Ok(registry) -> registry
+    Error(_) -> {
+      panic as "Should be able to create a new registry"
+    }
+  }
+
+  let assert Ok(rate_limiter) = registry |> registry.get_or_create("🚀")
+  let assert Ok(same_rate_limiter) = registry |> registry.get_or_create("🚀")
+
+  rate_limiter
+  |> should.equal(same_rate_limiter)
+}
+
+pub fn other_id_other_actor_test() {
+  let registry = case registry.new(2, 2) {
+    Ok(registry) -> registry
+    Error(_) -> {
+      panic as "Should be able to create a new registry"
+    }
+  }
+
+  let assert Ok(rate_limiter) = registry |> registry.get_or_create("🚀")
+  let assert Ok(same_rate_limiter) = registry |> registry.get_or_create("💫")
+
+  rate_limiter
+  |> should.not_equal(same_rate_limiter)
+}
+
+pub fn sweep_full_bucket_test() {
+  let registry = case registry.new(2, 2) {
+    Ok(registry) -> registry
+    Error(_) -> {
+      panic as "Should be able to create a new registry"
+    }
+  }
+
+  let assert Ok(rate_limiter) = registry |> registry.get_or_create("🚀")
+  registry |> registry.sweep
+  let assert Ok(new_rate_limiter) = registry |> registry.get_or_create("🚀")
+
+  rate_limiter
+  |> should.not_equal(new_rate_limiter)
+}
+
+pub fn sweep_not_full_bucket_test() {
+  let registry = case registry.new(2, 2) {
+    Ok(registry) -> registry
+    Error(_) -> {
+      panic as "Should be able to create a new registry"
+    }
+  }
+
+  let assert Ok(rate_limiter) = registry |> registry.get_or_create("🚀")
+
+  let _ = rate_limiter |> rate_limiter.hit
+  registry |> registry.sweep
+
+  let assert Ok(new_rate_limiter) = registry |> registry.get_or_create("🚀")
+
+  rate_limiter
+  |> should.equal(new_rate_limiter)
+}

test/glimit_test.gleam

···
+import gleam/erlang/process
 import gleeunit
 import gleeunit/should
 import glimit
···
   func(Nil) |> should.equal("Stop!")
 }
 
-pub fn single_argument_function_per_minute_test() {
-  let limiter =
-    glimit.new()
-    |> glimit.per_minute(2)
-    |> glimit.identifier(fn(_) { "id" })
-    |> glimit.on_limit_exceeded(fn(_) { "Stop!" })
-    |> glimit.build
-
-  let func =
-    fn(_) { "OK" }
-    |> glimit.apply(limiter)
-
-  func(Nil) |> should.equal("OK")
-  func(Nil) |> should.equal("OK")
-  func(Nil) |> should.equal("Stop!")
-  func(Nil) |> should.equal("Stop!")
-}
-
-pub fn single_argument_function_per_hour_test() {
-  let limiter =
-    glimit.new()
-    |> glimit.per_hour(2)
-    |> glimit.identifier(fn(_) { "id" })
-    |> glimit.on_limit_exceeded(fn(_) { "Stop!" })
-    |> glimit.build
-
-  let func =
-    fn(_) { "OK" }
-    |> glimit.apply(limiter)
-
-  func(Nil) |> should.equal("OK")
-  func(Nil) |> should.equal("OK")
-  func(Nil) |> should.equal("Stop!")
-  func(Nil) |> should.equal("Stop!")
-}
-
 pub fn single_argument_function_different_ids_test() {
   let limiter =
     glimit.new()
···
   func("🚀") |> should.equal("Stop!")
 }
 
-pub fn two_arguments_function_test() {
-  let limiter =
-    glimit.new()
-    |> glimit.per_second(2)
-    |> glimit.identifier(fn(_) { "id" })
-    |> glimit.identifier(fn(i: #(String, String)) {
-      let #(a, _) = i
-      a
-    })
-    |> glimit.on_limit_exceeded(fn(_) { "Stop!" })
-    |> glimit.build
-
-  let func =
-    fn(x, y) { x <> y }
-    |> glimit.apply2(limiter)
-
-  func("O", "K") |> should.equal("OK")
-  func(":", ")") |> should.equal(":)")
-  func("O", "K") |> should.equal("OK")
-  func("O", "K") |> should.equal("Stop!")
-}
-
-pub fn three_arguments_function_test() {
-  let limiter =
-    glimit.new()
-    |> glimit.per_second(2)
-    |> glimit.identifier(fn(_) { "id" })
-    |> glimit.on_limit_exceeded(fn(_) { "Stop!" })
-    |> glimit.build
-
-  let func =
-    fn(x, y, z) { x <> y <> z }
-    |> glimit.apply3(limiter)
-
-  func("O", "K", "!") |> should.equal("OK!")
-  func("O", "K", "!") |> should.equal("OK!")
-  func("O", "K", "!") |> should.equal("Stop!")
-}
-
-pub fn four_arguments_function_test() {
+pub fn burst_limit_test() {
   let limiter =
     glimit.new()
     |> glimit.per_second(2)
+    |> glimit.burst_limit(3)
     |> glimit.identifier(fn(_) { "id" })
     |> glimit.on_limit_exceeded(fn(_) { "Stop!" })
     |> glimit.build
 
   let func =
-    fn(x, y, z, p) { x <> y <> z <> p }
-    |> glimit.apply4(limiter)
+    fn(_) { "OK" }
+    |> glimit.apply(limiter)
 
-  func("O", "K", "?", "!") |> should.equal("OK?!")
-  func("O", "K", "?", "!") |> should.equal("OK?!")
-  func("O", "K", "?", "!") |> should.equal("Stop!")
-}
-
-pub fn try_build_ok_test() {
-  glimit.new()
-  |> glimit.per_second(2)
-  |> glimit.identifier(fn(x) { x })
-  |> glimit.on_limit_exceeded(fn(x) { x })
-  |> glimit.try_build
-  |> should.be_ok()
-}
+  func(Nil) |> should.equal("OK")
+  func(Nil) |> should.equal("OK")
+  func(Nil) |> should.equal("OK")
+  func(Nil) |> should.equal("Stop!")
+  func(Nil) |> should.equal("Stop!")
 
-pub fn try_build_identifier_missing_test() {
-  glimit.new()
-  |> glimit.per_second(2)
-  |> glimit.on_limit_exceeded(fn(x) { x })
-  |> glimit.try_build
-  |> should.equal(Error("`identifier` function is required"))
-}
+  // TODO: mock time to avoid sleeping 😴
+  process.sleep(1000)
 
-pub fn try_build_on_limit_exceeded_missing_test() {
-  glimit.new()
-  |> glimit.per_second(2)
-  |> glimit.identifier(fn(x) { x })
-  |> glimit.try_build
-  |> should.equal(Error("`on_limit_exceeded` function is required"))
+  func(Nil) |> should.equal("OK")
+  func(Nil) |> should.equal("OK")
+  func(Nil) |> should.equal("Stop!")
+  func(Nil) |> should.equal("Stop!")
 }