explicit start

.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}"]
 ]

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- make Hammer startup explicit
+
 ## 6.2.1 - 2024-02-23
 
 - Fix issue in OTP 26 and Elixir 1.15 by not using to_existing_atom in configuration

lib/hammer/supervisor.ex

@@ -4,13 +4,65 @@ defmodule Hammer.Supervisor do
 
   Starts a set of poolboy pools based on provided configuration,
   which are latter called to by the `Hammer` module.
-  See the Application module for configuration examples.
+
+  Configured with the `:hammer` environment key:
+
+  - `:backend`, Either a tuple of `{module, config}`, or a keyword-list
+    of separate, named backends. Examples:
+    `{Hammer.Backend.ETS, []}`, `[ets: {Hammer.Backend.ETS, []}, ...]`
+  - `:suppress_logs`, if set to `true`, stops all log messages from Hammer
+
+  ### General Backend Options
+
+  Different backends take different options, but all will accept the following
+  options, and with the same effect:
+
+  - `:expiry_ms` (int): expiry time in milliseconds, after which a bucket will
+    be deleted. The exact mechanism for cleanup will vary by backend. This configuration
+    option is mandatory
+  - `:pool_size` (int): size of the backend worker pool (default=2)
+  - `:pool_max_overflow` int(): number of extra workers the pool is permitted
+    to spawn when under pressure. The worker pool (managed by the poolboy library)
+    will automatically create and destroy workers up to the max-overflow limit
+    (default=0)
+
+  Example of a single backend:
+
+      children = [
+        {Hammer.Supervisor, backend: {Hammer.Backend.ETS, [expiry_ms: 60_000 * 60 * 2]}}
+      ]
+
+  Example of config for multiple-backends:
+
+      children = [
+        {Hammer.Supervisor,
+         backend: [
+           ets: {
+             Hammer.Backend.ETS,
+             [
+               ets_table_name: :hammer_backend_ets_buckets,
+               expiry_ms: 60_000 * 60 * 2,
+               cleanup_interval_ms: 60_000 * 2
+             ]
+           },
+         redis: {
+             Hammer.Backend.Redis,
+             [
+               expiry_ms: 60_000 * 60 * 2,
+               redix_config: [host: "localhost", port: 6379],
+               pool_size: 4
+             ]
+           }
+         ]}
+      ]
+
   """
 
   use Supervisor
 
-  def start_link(config, opts) do
-    Supervisor.start_link(__MODULE__, config, opts)
+  def start_link(config) do
+    backend = Keyword.fetch!(config, :backend)
+    Supervisor.start_link(__MODULE__, backend, name: Hammer.Supervisor)
   end
 
   # Single backend

mix.exs

@@ -20,8 +20,7 @@ defmodule Hammer.Mixfile do
   end
 
   def application do
-    # Specify extra applications you'll use from Erlang/Elixir
-    [mod: {Hammer.Application, []}, extra_applications: [:logger, :runtime_tools]]
+    [extra_applications: []]
   end
 
   defp deps do

test/hammer_test.exs

@@ -1,5 +1,5 @@
 defmodule HammerTest do
-  use ExUnit.Case, async: false
+  use ExUnit.Case
 
   setup _context do
     pool = Hammer.Utils.pool_name()
@@ -41,7 +41,7 @@
     }
   end
 
   test "make_rate_checker" do
     check = Hammer.make_rate_checker("some-prefix:", 10_000, 2)
     assert {:allow, 1} = check.("aaa")
     assert {:allow, 2} = check.("aaa")
@@ -53,25 +53,25 @@
     assert {:deny, 2} = check.("bbb")
   end
 
   test "returns {:ok, 1} tuple on first access", %{bucket: bucket} do
     assert {:allow, 1} = Hammer.check_rate(bucket, 10_000, 10)
   end
 
   test "returns {:ok, 4} tuple on in-limit checks", %{bucket: bucket} do
     assert {:allow, 1} = Hammer.check_rate(bucket, 10_000, 10)
     assert {:allow, 2} = Hammer.check_rate(bucket, 10_000, 10)
     assert {:allow, 3} = Hammer.check_rate(bucket, 10_000, 10)
     assert {:allow, 4} = Hammer.check_rate(bucket, 10_000, 10)
   end
 
   test "returns expected tuples on mix of in-limit and out-of-limit checks", %{bucket: bucket} do
     assert {:allow, 1} = Hammer.check_rate(bucket, 10_000, 2)
     assert {:allow, 2} = Hammer.check_rate(bucket, 10_000, 2)
     assert {:deny, 2} = Hammer.check_rate(bucket, 10_000, 2)
     assert {:deny, 2} = Hammer.check_rate(bucket, 10_000, 2)
   end
 
   test "returns expected tuples on 1000ms bucket check with a sleep in the middle", %{
     bucket: bucket
   } do
     assert {:allow, 1} = Hammer.check_rate(bucket, 1000, 2)
@@ -83,7 +83,7 @@
     assert {:deny, 2} = Hammer.check_rate(bucket, 1000, 2)
   end
 
   test "returns expected tuples on inspect_bucket" do
     assert {:ok, {0, 2, _, nil, nil}} = Hammer.inspect_bucket("inspect_bucket11", 1000, 2)
     assert {:allow, 1} = Hammer.check_rate("inspect_bucket11", 1000, 2)
     assert {:ok, {1, 1, _, _, _}} = Hammer.inspect_bucket("inspect_bucket11", 1000, 2)
@@ -98,7 +98,7 @@
     assert ms_to_next_bucket < 1000
   end
 
   test "returns expected tuples on delete_buckets" do
     assert {:allow, 1} = Hammer.check_rate("my-bucket1", 1000, 2)
     assert {:allow, 2} = Hammer.check_rate("my-bucket1", 1000, 2)
     assert {:deny, 2} = Hammer.check_rate("my-bucket1", 1000, 2)
@@ -112,13 +112,13 @@
     assert {:ok, 0} = Hammer.delete_buckets("unknown-bucket")
   end
 
   test "count_hit_inc" do
     assert {:allow, 4} = Hammer.check_rate_inc("cost-bucket1", 1000, 10, 4)
     assert {:allow, 9} = Hammer.check_rate_inc("cost-bucket1", 1000, 10, 5)
     assert {:deny, 10} = Hammer.check_rate_inc("cost-bucket1", 1000, 10, 3)
   end
 
   test "mixing count_hit with count_hit_inc" do
     assert {:allow, 3} = Hammer.check_rate_inc("cost-bucket2", 1000, 10, 3)
     assert {:allow, 4} = Hammer.check_rate("cost-bucket2", 1000, 10)
     assert {:allow, 5} = Hammer.check_rate("cost-bucket2", 1000, 10)

test/hammer_util_test.exs

@@ -1,6 +1,21 @@
 defmodule UtilsTest do
   use ExUnit.Case
 
+  setup do
+    start_supervised!(
+      {Hammer.Supervisor,
+       backend: [
+         ets:
+           {Hammer.Backend.ETS,
+            ets_table_name: :utils_test,
+            expiry_ms: 60_000 * 60 * 2,
+            cleanup_interval_ms: 60_000 * 2}
+       ]}
+    )
+
+    :ok
+  end
+
   test "timestamp" do
     assert is_integer(Hammer.Utils.timestamp())
   end
@@ -15,7 +30,7 @@
     assert b_id == id
   end
 
   test "get_backend_module" do
     # With :single and default backend config
     assert Hammer.Utils.get_backend_module(:single) == Hammer.Backend.ETS