Clean API

Exposes the skeleton through the root module and sets the pattern for defining more scoring algorithms

Author: joladev

README.md

@@ -9,7 +9,7 @@ HRW (Highest Random Weight) is another name for rendezvous hashing, an alternati
 
 The most common library in the Elixir community to use to solve that problem is ExHashRing by Discord, which is battle-tested and highly performant. However, it requires starting and maintaining processes, and HRW does not. For smaller lists of nodes, `HRW.owner` (O(n)) or `HRW.owners` (O(n log n)) will perform just fine, and is completely stateless, requiring no setup when starting your app.
 
-This library also comes with HRW.Skeleton which uses a clustering mechanism to go from O(n) to O(log n), with the trade-off that you need to create the struct with `HRW.Skeleton.build` and pass to each call of `HRW.Skeleton.owner`.
+For larger node sets, build a skeleton with `HRW.build` and pass it to `HRW.owner` to get O(log n) lookups. The skeleton is plain data — build it once, reuse it across calls.
 
 Additionally, there's `HRW.Bounded` for when you want to control the distribution of keys across nodes to limit skew. Consistent hashing and rendezvous hashing algorithms can easily result in uneven distribution for smaller node counts, and `HRW.Bounded` lets you control that, assuming that you have the whole key set up front.
 
@@ -21,11 +21,11 @@ HRW.owner("192.168.0.1", ["server1", "server2", "server3"])
 HRW.owners("192.168.0.1", ["server1", "server2", "server3"], 2)
 #=> ["server2", "server3"]
 
-# HRW.Skeleton
-skeleton = HRW.Skeleton.build(["server1", "server2", "server3"])
-#=> #HRW.Skeleton<3 nodes, fanout: 3>
+# Skeleton-backed lookup for large node sets
+skeleton = HRW.build(["server1", "server2", "server3"])
+#=> #HRW.Skeleton<3 nodes, fanout: 3, scorer: %HRW{hash_fn: nil}>
 
-HRW.Skeleton.owner("192.168.0.2", skeleton)
+HRW.owner("192.168.0.2", skeleton)
 #=> "server3"
 
 # HRW.Bounded
@@ -39,11 +39,11 @@ tl;dr HRW performs similarly to ExHashRing on smaller node lists, but falls behi
 
 Lookup latency on Apple M4 Pro / Elixir 1.19.5 / OTP 28.5, median per call:
 
-| nodes  | HRW.owner   | HRW.Skeleton.owner | ExHashRing.find_node |
+| nodes  | HRW.owner   | HRW.owner (skeleton) | ExHashRing.find_node |
 |-------:|------------:|-------------------:|---------------------:|
 |     10 |     292 ns  |      292 ns        |        333 ns        |
 |    100 |    2.67 µs  |      875 ns        |        375 ns        |
 |  1,000 |   25.54 µs  |     1.08 µs        |        380 ns        |
 | 10,000 |  253.58 µs  |     1.38 µs        |        420 ns        |
 
-Reproduce with `elixir benches/hrw.exs`.
+Reproduce with `elixir benches/bench.exs`.

benches/bench.exs

@@ -0,0 +1,31 @@
+Mix.install([
+  {:hrw, path: Path.expand("..", __DIR__)},
+  {:benchee, "~> 1.5"},
+  {:ex_hash_ring, "~> 7.0"}
+])
+
+alias ExHashRing.Ring
+
+defmodule Bench do
+  def run do
+    setup = fn n ->
+      nodes = Enum.map(1..n, &"node-#{&1}")
+      {:ok, ring} = Ring.start_link()
+      Ring.set_nodes(ring, nodes, :infinity)
+      %{nodes: nodes, skeleton: HRW.build(nodes), ring: ring}
+    end
+
+    Benchee.run(%{
+      "HRW.owner" => fn %{nodes: nodes} -> HRW.owner("test", nodes) end,
+      "HRW.owner (skeleton)" => fn %{skeleton: skeleton} -> HRW.owner("test", skeleton) end,
+      "ExHashRing.Ring.find_node" => fn %{ring: ring} -> Ring.find_node(ring, "test") end
+    }, inputs: %{
+      "A: 10" => setup.(10),
+      "B: 100" => setup.(100),
+      "C: 1_000" => setup.(1_000),
+      "D: 10_000" => setup.(10_000)
+    })
+  end
+end
+
+Bench.run()

benches/hrw.exs

@@ -4,9 +4,26 @@ defmodule HRW do
   to a node out of a set in a way that stays stable when nodes are added or
   removed.
 
-  This module is stateless. For O(log n) lookups over large node sets, see
-  `HRW.Skeleton`.
+  This module is stateless. For O(log n) lookups over large node sets, build
+  a skeleton with `build/2` and pass it to `owner/3`.
   """
+  @behaviour HRW.Scorer
+
+  defstruct [:hash_fn]
+
+  @type t :: %__MODULE__{hash_fn: (term() -> integer()) | nil}
+
+  @doc """
+  Default scorer. Hashes `{key, node}` with the struct's `hash_fn`, falling
+  back to `:erlang.phash2/1` when `hash_fn` is `nil`.
+
+  Implements `HRW.Scorer`. Called internally whenever the default scorer is
+  selected (no `:scorer` option, or `scorer: %HRW{}` passed explicitly).
+  """
+  @impl HRW.Scorer
+  @spec score(t(), term(), term()) :: integer()
+  def score(%__MODULE__{hash_fn: nil}, key, node), do: :erlang.phash2({key, node})
+  def score(%__MODULE__{hash_fn: hash_fn}, key, node), do: hash_fn.({key, node})
 
   @doc """
   Returns the node responsible for `key`.
@@ -15,32 +32,50 @@ defmodule HRW do
 
   ## Options
 
-    * `:hash_fn` - a function `term -> integer`. Defaults to `&:erlang.phash2/1`.
+    * `:scorer` - scoring strategy struct. Defaults to `%HRW{}`. Ignored when
+      the second argument is a skeleton — pass `:scorer` to `build/2` instead.
 
   ## Examples
 
       iex> HRW.owner("192.168.0.1", ["server1", "server2", "server3"])
       "server2"
 
+      iex> skeleton = HRW.build(["server1", "server2", "server3"])
+      iex> HRW.owner("192.168.0.2", skeleton)
+      "server3"
   """
-  @spec owner(term(), [term()], keyword()) :: term()
-  def owner(key, nodes, opts \\ []) do
-    hash_fn = Keyword.get(opts, :hash_fn, &:erlang.phash2/1)
-
-    nodes
-    |> Enum.uniq()
-    |> Enum.sort()
-    |> Enum.max_by(fn node ->
-      hash_fn.({key, node})
-    end)
+  @spec owner(term(), [term()] | HRW.Skeleton.t(), keyword()) :: term()
+  def owner(key, nodes_or_skeleton, opts \\ [])
+
+  def owner(key, %HRW.Skeleton{} = skeleton, _opts) do
+    HRW.Skeleton.owner(key, skeleton)
+  end
+
+  def owner(key, nodes, opts) do
+    nodes =
+      nodes
+      |> Enum.sort()
+      |> Enum.uniq()
+
+    if scorer = Keyword.get(opts, :scorer) do
+      %mod{} = scorer
+
+      Enum.max_by(nodes, fn node ->
+        mod.score(scorer, key, node)
+      end)
+    else
+      Enum.max_by(nodes, fn node ->
+        :erlang.phash2({key, node})
+      end)
+    end
   end
 
   @doc """
   Returns the top `count` nodes responsible for `key`, in descending weight order.
 
   ## Options
 
-    * `:hash_fn` - a function `term -> integer`. Defaults to `&:erlang.phash2/1`.
+    * `:scorer` - scoring strategy struct. Defaults to `%HRW{}`.
 
   ## Examples
 
@@ -50,12 +85,42 @@ defmodule HRW do
   """
   @spec owners(term(), [term()], non_neg_integer(), keyword()) :: [term()]
   def owners(key, nodes, count, opts \\ []) do
-    hash_fn = Keyword.get(opts, :hash_fn, &:erlang.phash2/1)
+    nodes =
+      nodes
+      |> Enum.sort()
+      |> Enum.uniq()
+
+    if scorer = Keyword.get(opts, :scorer) do
+      %mod{} = scorer
+
+      nodes
+      |> Enum.sort_by(fn node -> mod.score(scorer, key, node) end, :desc)
+      |> Enum.take(count)
+    else
+      nodes
+      |> Enum.sort_by(fn node -> :erlang.phash2({key, node}) end, :desc)
+      |> Enum.take(count)
+    end
+  end
 
-    nodes
-    |> Enum.uniq()
-    |> Enum.sort()
-    |> Enum.sort_by(fn node -> hash_fn.({key, node}) end, :desc)
-    |> Enum.take(count)
+  @doc """
+  Builds a skeleton from `nodes` for O(log n) lookups.
+
+  Pass the result to `owner/3`.
+
+  ## Options
+
+    * `:fanout` - branching factor of the virtual tree. Defaults to `3`.
+    * `:cluster_size` - target number of nodes per cluster. Defaults to `16`.
+    * `:scorer` - scoring strategy struct. Defaults to `%HRW{}`.
+
+  ## Examples
+
+      iex> HRW.build(["server1", "server2", "server3"])
+      #HRW.Skeleton<3 nodes, fanout: 3, scorer: %HRW{hash_fn: nil}>
+  """
+  @spec build([term()], keyword()) :: HRW.Skeleton.t()
+  def build(nodes, opts \\ []) do
+    HRW.Skeleton.build(nodes, opts)
   end
 end

lib/hrw.ex

@@ -0,0 +1,12 @@
+defmodule HRW.Scorer do
+  @moduledoc """
+  Behaviour for HRW scoring strategies. Each variant module (`HRW`, future
+  `HRW.Weighted`, etc.) defines a struct holding its configuration and
+  implements `score/3` returning an integer score for a `(key, node)` pair.
+
+  Pass an instance via the `:scorer` option to `HRW.owner/3`, `HRW.owners/4`,
+  or `HRW.build/2`. The highest-scoring node wins.
+  """
+
+  @callback score(scorer :: struct(), key :: term(), node :: term()) :: integer()
+end

lib/hrw/scorer.ex

@@ -1,34 +1,22 @@
 defmodule HRW.Skeleton do
   @moduledoc """
-  A skeleton-based variant of HRW that gives O(log n) lookups by grouping
-  nodes into clusters and routing keys through a virtual tree.
+  Internal data structure backing `HRW.build/2` and `HRW.owner/3` for
+  O(log n) lookups. Nodes are grouped into clusters and routed through a
+  virtual tree. Plain data, not a process.
 
-  Build the skeleton once with `build/2`, then pass it to each `owner/3` call.
-  The skeleton is plain data, not a process.
+  Not intended for direct use — go through `HRW`.
   """
 
-  defstruct [:clusters, :fanout, :levels]
+  defstruct [:clusters, :fanout, :levels, :scorer]
 
   @type t :: %__MODULE__{
           clusters: tuple(),
           fanout: pos_integer(),
-          levels: non_neg_integer()
+          levels: non_neg_integer(),
+          scorer: struct() | nil
         }
 
-  @doc """
-  Builds a skeleton from `nodes`.
-
-  ## Options
-
-    * `:fanout` - branching factor of the virtual tree. Defaults to `3`.
-    * `:cluster_size` - target number of nodes per cluster. Defaults to `16`.
-
-  ## Examples
-
-      iex> HRW.Skeleton.build(["server1", "server2", "server3"])
-      #HRW.Skeleton<3 nodes, fanout: 3>
-
-  """
+  @doc false
   @spec build([term()], keyword()) :: t()
   def build(nodes, opts \\ [])
 
@@ -39,6 +27,7 @@ defmodule HRW.Skeleton do
   def build(nodes, opts) do
     fanout = Keyword.get(opts, :fanout, 3)
     size = Keyword.get(opts, :cluster_size, 16)
+    scorer = Keyword.get(opts, :scorer, %HRW{})
 
     cluster_list = chunk_redistribute(nodes, size)
     clusters = List.to_tuple(cluster_list)
@@ -48,46 +37,52 @@ defmodule HRW.Skeleton do
     %__MODULE__{
       clusters: clusters,
       fanout: fanout,
-      levels: levels
+      levels: levels,
+      scorer: scorer
     }
   end
 
-  @doc """
-  Returns the node responsible for `key` in the given skeleton.
-
-  ## Options
-
-    * `:hash_fn` - a function `term -> integer`. Defaults to `&:erlang.phash2/1`.
+  @doc false
+  def owner(key, %__MODULE__{} = skeleton) do
+    do_owner(key, skeleton, 0)
+  end
 
-  ## Examples
+  # We take the fast path when scorer and hash_fn are not overridden.
+  defp do_owner(key, %__MODULE__{clusters: {cluster}, scorer: %HRW{hash_fn: nil}}, _salt) do
+    Enum.max_by(cluster, fn node -> :erlang.phash2({key, node}) end)
+  end
 
-      iex> skeleton = HRW.Skeleton.build(["server1", "server2", "server3"])
-      iex> HRW.Skeleton.owner("192.168.0.2", skeleton)
-      "server3"
+  defp do_owner(key, %__MODULE__{scorer: %HRW{hash_fn: nil}} = skeleton, salt) do
+    index =
+      Enum.reduce(0..(skeleton.levels - 1), 0, fn level, acc ->
+        digit = Enum.max_by(0..(skeleton.fanout - 1), &:erlang.phash2({{key, salt, level}, &1}))
+        acc * skeleton.fanout + digit
+      end)
 
-  """
-  @spec owner(term(), t(), keyword()) :: term()
-  def owner(key, %__MODULE__{} = skeleton, opts \\ []) do
-    hash_fn = Keyword.get(opts, :hash_fn, &:erlang.phash2/1)
-    do_owner(key, skeleton, 0, hash_fn)
+    if index < tuple_size(skeleton.clusters) do
+      cluster = elem(skeleton.clusters, index)
+      Enum.max_by(cluster, fn node -> :erlang.phash2({{key, salt, index}, node}) end)
+    else
+      do_owner(key, skeleton, salt + 1)
+    end
   end
 
-  defp do_owner(key, %__MODULE__{clusters: {cluster}}, _salt, hash_fn) do
-    Enum.max_by(cluster, fn node -> hash_fn.({key, node}) end)
+  defp do_owner(key, %__MODULE__{clusters: {cluster}, scorer: %mod{} = scorer}, _salt) do
+    Enum.max_by(cluster, fn node -> mod.score(scorer, key, node) end)
   end
 
-  defp do_owner(key, skeleton, salt, hash_fn) do
+  defp do_owner(key, %__MODULE__{scorer: %mod{} = scorer} = skeleton, salt) do
     index =
       Enum.reduce(0..(skeleton.levels - 1), 0, fn level, acc ->
-        digit = Enum.max_by(0..(skeleton.fanout - 1), &hash_fn.({key, salt, level, &1}))
+        digit = Enum.max_by(0..(skeleton.fanout - 1), &mod.score(scorer, {key, salt, level}, &1))
         acc * skeleton.fanout + digit
       end)
 
     if index < tuple_size(skeleton.clusters) do
       cluster = elem(skeleton.clusters, index)
-      Enum.max_by(cluster, fn node -> hash_fn.({key, salt, index, node}) end)
+      Enum.max_by(cluster, fn node -> mod.score(scorer, {key, salt, index}, node) end)
     else
-      do_owner(key, skeleton, salt + 1, hash_fn)
+      do_owner(key, skeleton, salt + 1)
     end
   end
 
@@ -117,13 +112,13 @@ defmodule HRW.Skeleton do
 end
 
 defimpl Inspect, for: HRW.Skeleton do
-  def inspect(%HRW.Skeleton{clusters: clusters, fanout: fanout}, _opts) do
+  def inspect(%HRW.Skeleton{clusters: clusters, fanout: fanout, scorer: scorer}, _opts) do
     nodes =
       clusters
       |> Tuple.to_list()
       |> Enum.reduce(0, fn cluster, acc -> acc + length(cluster) end)
 
     label = if nodes == 1, do: "node", else: "nodes"
-    "#HRW.Skeleton<#{nodes} #{label}, fanout: #{fanout}>"
+    "#HRW.Skeleton<#{nodes} #{label}, fanout: #{fanout}, scorer: #{inspect(scorer)}>"
   end
 end