new ets

.formatter.exs

@@ -1,4 +1,4 @@
 # Used by "mix format"
 [
-  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+  inputs: ["{mix,.formatter}.exs", "{lib,test}/**/*.{ex,exs}"]
 ]

.github/workflows/ci.yml

@@ -18,11 +18,9 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-22.04, ubuntu-20.04]
-        elixir_version: [1.12.3, 1.13.3, 1.14.1]
-        otp_version: [24, 25]
-        exclude:
-          - otp_version: 25
-            elixir_version: 1.12.3
+        elixir_version: [1.13, 1.14, 1.15]
+        otp_version: [24, 25, 26]
+
     steps:
       - uses: actions/checkout@v4
 

.tool-versions

@@ -1 +1 @@
-elixir 1.13.1
+elixir 1.15.7-otp-26

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 7.0.0 - unreleased
+
+- remove `poolboy` dependency
+- improve ETS backend efficiency ~15x
+- fix ETS backend overload
+- remove global supervisor
+
 ## 6.1.0 - 2022-06-13
 
 ### Changed

README.md

@@ -21,7 +21,7 @@ by adding `:hammer` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:hammer, "~> 6.1"}
+    {:hammer, "~> 7.0"}
   ]
 end
 ```
@@ -38,7 +38,6 @@ Example:
 
 ```elixir
 defmodule MyApp.VideoUpload do
-
   def upload(video_data, user_id) do
     case Hammer.check_rate("upload_video:#{user_id}", 60_000, 5) do
       {:allow, _count} ->
@@ -47,7 +46,6 @@ defmodule MyApp.VideoUpload do
         # deny the request
     end
   end
-
 end
 ```
 
@@ -58,14 +56,6 @@ The `Hammer` module provides the following functions:
 - `inspect_bucket(id, scale_ms, limit)`
 - `delete_buckets(id)`
 
-Backends are configured via `Mix.Config`:
-
-```elixir
-config :hammer,
-  backend: {Hammer.Backend.ETS, [expiry_ms: 60_000 * 60 * 4,
-                                 cleanup_interval_ms: 60_000 * 10]}
-```
-
 See the [Tutorial](https://hexdocs.pm/hammer/tutorial.html) for more.
 
 See the [Hammer Testbed](https://github.com/ExHammer/hammer-testbed) app for an example of

lib/hammer.ex

@@ -2,16 +2,20 @@ defmodule Hammer do
   @moduledoc """
   Documentation for Hammer module.
 
-  This is the main API for the Hammer rate-limiter. This module assumes a
-  backend pool has been started, most likely by the Hammer application.
+  This is the main API for the Hammer rate-limiter. This module assumes the
+  backend has been started.
+
+  Example:
+
+      def start(_, _) do
+        children = [{Hammer.Backend.ETS, cleanup_interval_ms: :timer.seconds(5)}]
+        Supervisor.init(children, [])
+      end
+
   """
 
-  alias Hammer.Utils
+  @backend Application.compile_env(:hammer, :backend, Hammer.Backend.ETS)
 
-  @spec check_rate(id :: String.t(), scale_ms :: integer, limit :: integer) ::
-          {:allow, count :: integer}
-          | {:deny, limit :: integer}
-          | {:error, reason :: any}
   @doc """
   Check if the action you wish to perform is within the bounds of the rate-limit.
 
@@ -22,7 +26,7 @@ defmodule Hammer do
   - `scale_ms`: Integer indicating size of bucket in milliseconds
   - `limit`: Integer maximum count of actions within the bucket
 
-  Returns either `{:allow,  count}`, `{:deny,   limit}` or `{:error,  reason}`
+  Returns either `{:allow,  count}`, `{:deny,   limit}`
 
   Example:
 
@@ -34,85 +38,35 @@ defmodule Hammer do
           # render an error page or something
       end
   """
+  @spec check_rate(id :: String.t(), scale_ms :: integer, limit :: integer) ::
+          {:allow, count :: integer} | {:deny, limit :: integer} | {:error, reason :: any}
   def check_rate(id, scale_ms, limit) do
-    check_rate(:single, id, scale_ms, limit)
+    check_rate_inc(id, scale_ms, limit, 1)
   end
 
-  @spec check_rate(backend :: atom, id :: String.t(), scale_ms :: integer, limit :: integer) ::
-          {:allow, count :: integer}
-          | {:deny, limit :: integer}
-          | {:error, reason :: any}
-  @doc """
-  Same as `check_rate/3`, but allows specifying a backend.
-  """
-  def check_rate(backend, id, scale_ms, limit) do
-    {stamp, key} = Utils.stamp_key(id, scale_ms)
-
-    case call_backend(backend, :count_hit, [key, stamp]) do
-      {:ok, count} ->
-        if count > limit do
-          {:deny, limit}
-        else
-          {:allow, count}
-        end
-
-      {:error, reason} ->
-        {:error, reason}
-    end
-  end
-
-  @spec check_rate_inc(
-          id :: String.t(),
-          scale_ms :: integer,
-          limit :: integer,
-          increment :: integer
-        ) ::
-          {:allow, count :: integer}
-          | {:deny, limit :: integer}
-          | {:error, reason :: any}
   @doc """
   Same as check_rate/3, but allows the increment number to be specified.
   This is useful for limiting apis which have some idea of 'cost', where the cost
   of each hit can be specified.
   """
-  def check_rate_inc(id, scale_ms, limit, increment) do
-    check_rate_inc(:single, id, scale_ms, limit, increment)
-  end
-
   @spec check_rate_inc(
-          backend :: atom,
           id :: String.t(),
           scale_ms :: integer,
           limit :: integer,
-          increment :: integer
+          increment :: non_neg_integer
         ) ::
-          {:allow, count :: integer}
-          | {:deny, limit :: integer}
-          | {:error, reason :: any}
-  @doc """
-  Same as check_rate_inc/4, but allows specifying a backend.
-  """
-  def check_rate_inc(backend, id, scale_ms, limit, increment) do
-    {stamp, key} = Utils.stamp_key(id, scale_ms)
-
-    case call_backend(backend, :count_hit, [key, stamp, increment]) do
-      {:ok, count} ->
-        if count > limit do
-          {:deny, limit}
-        else
-          {:allow, count}
-        end
+          {:allow, count :: integer} | {:deny, limit :: integer} | {:error, reason :: any}
+  def check_rate_inc(id, scale_ms, limit, increment) do
+    now = System.system_time(:millisecond)
+    now_bucket = div(now, scale_ms)
+    key = {id, now_bucket}
+    expires_at = (now_bucket + 1) * scale_ms
 
-      {:error, reason} ->
-        {:error, reason}
+    with {:ok, count} <- @backend.count_hit(key, increment, expires_at) do
+      if count <= limit, do: {:allow, count}, else: {:deny, limit}
     end
   end
 
-  @spec inspect_bucket(id :: String.t(), scale_ms :: integer, limit :: integer) ::
-          {:ok,
-           {count :: integer, count_remaining :: integer, ms_to_next_bucket :: integer,
-            created_at :: integer | nil, updated_at :: integer | nil}}
-          | {:error, reason :: any}
   @doc """
   Inspect bucket to get count, count_remaining, ms_to_next_bucket, created_at,
   updated_at. This function is free of side-effects and should be called with
@@ -137,38 +91,29 @@ defmodule Hammer do
       {:ok, {1, 2499, 29381612, 1450281014468, 1450281014468}}
 
   """
-  def inspect_bucket(id, scale_ms, limit) do
-    inspect_bucket(:single, id, scale_ms, limit)
-  end
-
-  @spec inspect_bucket(backend :: atom, id :: String.t(), scale_ms :: integer, limit :: integer) ::
+  @spec inspect_bucket(id :: String.t(), scale_ms :: integer, limit :: integer) ::
           {:ok,
            {count :: integer, count_remaining :: integer, ms_to_next_bucket :: integer,
             created_at :: integer | nil, updated_at :: integer | nil}}
           | {:error, reason :: any}
-  @doc """
-  Same as inspect_bucket/3, but allows specifying a backend
-  """
-  def inspect_bucket(backend, id, scale_ms, limit) do
-    {stamp, key} = Utils.stamp_key(id, scale_ms)
-    ms_to_next_bucket = elem(key, 0) * scale_ms + scale_ms - stamp
-
-    case call_backend(backend, :get_bucket, [key]) do
-      {:ok, nil} ->
-        {:ok, {0, limit, ms_to_next_bucket, nil, nil}}
-
-      {:ok, {_, count, created_at, updated_at}} ->
-        count_remaining = if limit > count, do: limit - count, else: 0
-        {:ok, {count, count_remaining, ms_to_next_bucket, created_at, updated_at}}
-
-      {:error, reason} ->
-        {:error, reason}
+  def inspect_bucket(id, scale_ms, limit) do
+    now = System.system_time(:millisecond)
+    now_bucket = div(now, scale_ms)
+    key = {id, now_bucket}
+    ms_to_next_bucket = now_bucket * scale_ms + scale_ms - now
+
+    with {:ok, count} <- @backend.get_bucket(key) do
+      {:ok,
+       {
+         count,
+         max(limit - count, 0),
+         ms_to_next_bucket,
+         _created_at = nil,
+         _updated_at = nil
+       }}
     end
   end
 
-  @spec delete_buckets(id :: String.t()) ::
-          {:ok, count :: integer}
-          | {:error, reason :: any}
   @doc """
   Delete all buckets belonging to the provided id, including the current one.
   Effectively resets the rate-limit for the id.
@@ -186,79 +131,8 @@ defmodule Hammer do
       {:ok, _count} = delete_buckets("file_uploads:\#{user_id}")
 
   """
+  @spec delete_buckets(id :: String.t()) :: {:ok, count :: integer} | {:error, reason :: any}
   def delete_buckets(id) do
-    delete_buckets(:single, id)
-  end
-
-  @spec delete_buckets(backend :: atom, id :: String.t()) ::
-          {:ok, count :: integer}
-          | {:error, reason :: any}
-  @doc """
-  Same as delete_buckets/1, but allows specifying a backend
-  """
-  def delete_buckets(backend, id) do
-    call_backend(backend, :delete_buckets, [id])
-  end
-
-  @spec make_rate_checker(id_prefix :: String.t(), scale_ms :: integer, limit :: integer) ::
-          (id :: String.t() ->
-             {:allow, count :: integer}
-             | {:deny, limit :: integer}
-             | {:error, reason :: any})
-  @doc """
-  Make a rate-checker function, with the given `id` prefix, scale_ms and limit.
-
-  Arguments:
-
-  - `id_prefix`: String prefix to the `id`
-  - `scale_ms`: Integer indicating size of bucket in milliseconds
-  - `limit`: Integer maximum count of actions within the bucket
-
-  Returns a function which accepts an `id` suffix, which will be combined with
-  the `id_prefix`. Calling this returned function is equivalent to:
-  `Hammer.check_rate("\#{id_prefix}\#{id}", scale_ms, limit)`
-
-  Example:
-
-      chat_rate_limiter = make_rate_checker("send_chat_message:", 60_000, 20)
-      user_id = 203517
-      case chat_rate_limiter.(user_id) do
-        {:allow, _count} ->
-          # allow chat message
-        {:deny, _limit} ->
-          # deny
-      end
-  """
-  def make_rate_checker(id_prefix, scale_ms, limit) do
-    make_rate_checker(:single, id_prefix, scale_ms, limit)
-  end
-
-  @spec make_rate_checker(
-          backend :: atom,
-          id_prefix :: String.t(),
-          scale_ms :: integer,
-          limit :: integer
-        ) ::
-          (id :: String.t() ->
-             {:allow, count :: integer}
-             | {:deny, limit :: integer}
-             | {:error, reason :: any})
-  @doc """
-  """
-  def make_rate_checker(backend, id_prefix, scale_ms, limit) do
-    fn id ->
-      check_rate(backend, "#{id_prefix}#{id}", scale_ms, limit)
-    end
-  end
-
-  defp call_backend(which, function, args) do
-    pool = Utils.pool_name(which)
-    backend = Utils.get_backend_module(which)
-
-    :poolboy.transaction(
-      pool,
-      fn pid -> apply(backend, function, [pid | args]) end,
-      60_000
-    )
+    @backend.delete_buckets(id)
   end
 end