🌄 Initial commit

.github/workflows/test.yml

···
+name: test
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: "26.0.2"
+          gleam-version: "1.4.1"
+          rebar3-version: "3"
+          # elixir-version: "1.15.4"
+      - run: gleam deps download
+      - run: gleam test
+      - run: gleam format --check src test

.gitignore

···
+*.beam
+*.ez
+/build
+erl_crash.dump

README.md

···
+# glimit
+
+[![Package Version](https://img.shields.io/hexpm/v/glimit)](https://hex.pm/packages/glimit)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/glimit/)
+
+A framework-agnostic rate limiter for Gleam. 💫
+
+> ⚠️  This library is still in development, use at your own risk.
+
+
+## Installation
+
+```sh
+gleam add glimit
+```
+
+
+## Example usage
+
+Glimit could be used to rate limit requests to a mist HTTP server:
+
+```gleam
+import glimit
+import gleam/bytes_builder
+
+
+fn handle_request(req: Request(Connection)) -> Response(ResponseData) {
+  let index =
+    response.new(200)
+    |> response.set_body(mist.Bytes(bytes_builder.new()))
+  let not_found =
+    response.new(404)
+    |> response.set_body(mist.Bytes(bytes_builder.new()))
+
+  case request.path_segments(req) {
+    [] -> index
+    _ -> not_found
+  }
+}
+
+pub fn main() {
+  let limiter =
+    glimit.new()
+    |> glimit.per_second(10)
+    |> glimit.per_minute(100)
+    |> glimit.per_hour(1000)
+    |> glimit.identifier(fn(req: Request(Connection)) {
+      req.body
+      |> get_client_info
+      |> result.map(fn(client_info: ConnectionInfo) {
+        client_info.ip_address |> string.inspect
+      })
+      |> result.unwrap("unknown IP address")
+    })
+    |> glimit.handler(fn(_req) {
+      response.new(429)
+      |> response.set_body(mist.Bytes(bytes_builder.new()))
+    })
+    |> glimit.build
+
+  let assert Ok(_) =
+    handle_request
+    |> glimit.apply(limiter)
+    |> mist.new
+    |> mist.port(8080)
+    |> mist.start_http
+
+  process.sleep_forever()
+}
+```
+
+Further documentation can be found at <https://hexdocs.pm/glimit>.
+
+## Development
+
+```sh
+gleam test  # Run the tests
+```

gleam.toml

···
+name = "glimit"
+version = "1.0.0"
+
+description = "A framework-agnostic rate limiter for Gleam."
+licences = ["MIT"]
+repository = { type = "github", user = "nootr", repo = "glimit" }
+target = "erlang"
+
+[dependencies]
+gleam_stdlib = ">= 0.34.0 and < 2.0.0"
+gleam_erlang = ">= 0.25.0 and < 1.0.0"
+gleam_otp = ">= 0.11.2 and < 1.0.0"
+
+[dev-dependencies]
+gleeunit = ">= 1.0.0 and < 2.0.0"

manifest.toml

···
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "gleam_erlang", version = "0.25.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "054D571A7092D2A9727B3E5D183B7507DAB0DA41556EC9133606F09C15497373" },
+  { name = "gleam_otp", version = "0.11.2", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "gleam_otp", source = "hex", outer_checksum = "517FFB679E44AD71D059F3EF6A17BA6EFC8CB94FA174D52E22FB6768CF684D78" },
+  { name = "gleam_stdlib", version = "0.40.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "86606B75A600BBD05E539EB59FABC6E307EEEA7B1E5865AFB6D980A93BCB2181" },
+  { name = "gleeunit", version = "1.2.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "F7A7228925D3EE7D0813C922E062BFD6D7E9310F0BEE585D3A42F3307E3CFD13" },
+]
+
+[requirements]
+gleam_erlang = { version = ">= 0.25.0 and < 1.0.0" }
+gleam_otp = { version = ">= 0.11.2 and < 1.0.0" }
+gleam_stdlib = { version = ">= 0.34.0 and < 2.0.0" }
+gleeunit = { version = ">= 1.0.0 and < 2.0.0" }

src/glimit.gleam

···
+//// A framework-agnostic rate limiter.
+////
+
+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(a) {
+  /// Stop the actor.
+  Shutdown
+
+  /// Mark a hit for a given identifier.
+  Hit(input: a, reply_with: Subject(Result(Nil, Nil)))
+}
+
+/// The rate limiter's public interface.
+///
+pub type RateLimiter(a, b) {
+  RateLimiter(subject: Subject(Message(a)), handler: fn(a) -> b)
+}
+
+/// A rate limiter.
+///
+pub type RateLimiterBuilder(a, b, id) {
+  RateLimiterBuilder(
+    per_second: Option(Int),
+    per_minute: Option(Int),
+    per_hour: Option(Int),
+    identifier: fn(a) -> id,
+    handler: fn(a) -> b,
+  )
+}
+
+/// The actor state of the actor.
+///
+/// The state is a dictionary where the key is the identifier and the value is a list of epoch timestamps.
+///
+pub 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),
+    identifier: fn(a) -> id,
+    handler: fn(a) -> b,
+  )
+}
+
+fn handle_message(
+  message: Message(a),
+  state: State(a, b, id),
+) -> actor.Next(Message(a), State(a, b, id)) {
+  case message {
+    Shutdown -> actor.Stop(process.Normal)
+    Hit(input, client) -> {
+      let identifier = state.identifier(input)
+
+      // 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 builder.
+///
+/// Panics when the rate limit hit counter cannot be created.
+///
+pub fn new() -> RateLimiterBuilder(a, b, id) {
+  RateLimiterBuilder(
+    per_second: None,
+    per_minute: None,
+    per_hour: None,
+    identifier: fn(_) { panic as "No identifier configured" },
+    handler: fn(_) { panic as "Rate limit reached" },
+  )
+}
+
+/// Set the rate limit per second.
+///
+pub fn per_second(
+  limiter: RateLimiterBuilder(a, b, id),
+  limit: Int,
+) -> RateLimiterBuilder(a, b, id) {
+  RateLimiterBuilder(..limiter, per_second: Some(limit))
+}
+
+/// Set the rate limit per minute.
+///
+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.
+///
+pub fn per_hour(
+  limiter: RateLimiterBuilder(a, b, id),
+  limit: Int,
+) -> RateLimiterBuilder(a, b, id) {
+  RateLimiterBuilder(..limiter, per_hour: Some(limit))
+}
+
+/// Set the handler to be called when the rate limit is reached.
+///
+pub fn handler(
+  limiter: RateLimiterBuilder(a, b, id),
+  handler: fn(a) -> b,
+) -> RateLimiterBuilder(a, b, id) {
+  RateLimiterBuilder(..limiter, handler: handler)
+}
+
+/// Set the identifier function to be used to identify the rate limit.
+///
+pub fn identifier(
+  limiter: RateLimiterBuilder(a, b, id),
+  identifier: fn(a) -> id,
+) -> RateLimiterBuilder(a, b, id) {
+  RateLimiterBuilder(..limiter, identifier: identifier)
+}
+
+/// Build the rate limiter.
+///
+pub fn build(config: RateLimiterBuilder(a, b, id)) -> RateLimiter(a, b) {
+  let state =
+    RateLimiterState(
+      hit_log: dict.new(),
+      per_second: config.per_second,
+      per_minute: config.per_minute,
+      per_hour: config.per_hour,
+      identifier: config.identifier,
+      handler: config.handler,
+    )
+  let subject = case actor.start(state, handle_message) {
+    Ok(actor) -> actor
+    Error(_) -> panic as "Failed to start rate limiter actor"
+  }
+  RateLimiter(subject: subject, handler: config.handler)
+}
+
+/// Apply the rate limiter to a request handler or function.
+///
+pub fn apply(func: fn(a) -> b, limiter: RateLimiter(a, b)) -> fn(a) -> b {
+  fn(input: a) -> b {
+    case actor.call(limiter.subject, Hit(input, _), 10) {
+      Ok(Nil) -> func(input)
+      Error(Nil) -> limiter.handler(input)
+    }
+  }
+}
+
+/// Stop the rate limiter agent.
+///
+pub fn stop(limiter: RateLimiter(a, b)) {
+  actor.send(limiter.subject, Shutdown)
+}

src/glimit/utils.gleam

···
+//// A module containing utility functions.
+////
+
+@external(erlang, "os", "timestamp")
+fn now_erlang() -> #(Int, Int, Int)
+
+/// Get the current time in epoch seconds.
+pub fn now() -> Int {
+  let #(megaseconds, seconds, _) = now_erlang()
+  megaseconds * 1_000_000 + seconds
+}

test/glimit_test.gleam

···
+import gleeunit
+import gleeunit/should
+import glimit
+
+pub fn main() {
+  gleeunit.main()
+}
+
+pub fn single_argument_function_different_ids_test() {
+  let limiter =
+    glimit.new()
+    |> glimit.per_second(2)
+    |> glimit.identifier(fn(x) { x })
+    |> glimit.handler(fn(_) { "Stop!" })
+    |> glimit.build
+
+  let func =
+    fn(_x) { "OK" }
+    |> glimit.apply(limiter)
+
+  func("a") |> should.equal("OK")
+  func("b") |> should.equal("OK")
+  func("b") |> should.equal("OK")
+  func("b") |> should.equal("Stop!")
+  func("a") |> should.equal("OK")
+  func("a") |> should.equal("Stop!")
+}
+
+pub fn single_argument_function_per_second_test() {
+  let limiter =
+    glimit.new()
+    |> glimit.per_second(2)
+    |> glimit.identifier(fn(_) { "id" })
+    |> glimit.handler(fn(_) { "Stop!" })
+    |> glimit.build
+
+  let func =
+    fn(_x) { "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_minute_test() {
+  let limiter =
+    glimit.new()
+    |> glimit.per_minute(2)
+    |> glimit.identifier(fn(_) { "id" })
+    |> glimit.handler(fn(_) { "Stop!" })
+    |> glimit.build
+
+  let func =
+    fn(_x) { "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.handler(fn(_) { "Stop!" })
+    |> glimit.build
+
+  let func =
+    fn(_x) { "OK" }
+    |> glimit.apply(limiter)
+
+  func(Nil) |> should.equal("OK")
+  func(Nil) |> should.equal("OK")
+  func(Nil) |> should.equal("Stop!")
+  func(Nil) |> should.equal("Stop!")
+}