feat(strategies): add strategy adapter support with compile-time branching

Introduce strategy adapters as a new adapter type that wraps underlying
cache adapters. When adapter is a tuple `{strategy_module, config}`,
generate strategy-specific code paths that:

- Pass strategy config separately to strategy module functions
- Skip term encoding/decoding (delegated to strategy layer)
- Inject `__cache_module__` into adapter options for strategy use
- Validate strategy-specific options at compile time

Author: MikaAK

lib/cache.ex

@@ -0,0 +1,224 @@
+defmodule Cache.MultiLayer do
+  @moduledoc """
+  Multi-layer caching strategy that cascades through multiple cache layers.
+
+  Keys are read from fastest to slowest, with automatic backfill on cache hits
+  from slower layers. Writes go slowest-first to avoid polluting fast layers
+  with data that failed to persist in slow ones.
+
+  ## Usage
+
+  Pass a list of layers as the strategy config. Each element can be:
+
+  - A module that implements `Cache` (already running, not supervised by this adapter)
+  - An adapter module (e.g. `Cache.ETS`) — will be auto-started and supervised
+  - A tuple `{AdapterModule, opts}` — adapter with inline opts
+
+  ```elixir
+  defmodule MyApp.LayeredCache do
+    use Cache,
+      adapter: {Cache.MultiLayer, [Cache.ETS, MyApp.RedisCache]},
+      name: :layered_cache,
+      opts: []
+  end
+  ```
+
+  ## `__MODULE__` in Layers
+
+  You may include `__MODULE__` in the layer list to position the current
+  module's own underlying cache within the chain. If `__MODULE__` is omitted,
+  no local cache is created for the defining module—it acts as a pure facade.
+
+  ```elixir
+  defmodule MyApp.LayeredCache do
+    use Cache,
+      adapter: {Cache.MultiLayer, [Cache.ETS, __MODULE__, MyApp.RedisCache]},
+      name: :layered_cache,
+      opts: [uri: "redis://localhost"]
+  end
+  ```
+
+  ## Read Behaviour
+
+  Layers are iterated fastest → slowest (list order). On a hit from layer N,
+  the value is backfilled into layers 1..N-1.
+
+  ## Write Behaviour
+
+  Layers are written slowest → fastest (reverse list order). If a slow write
+  fails, the write stops and an error is returned — preventing polluting faster
+  layers with potentially-unsaved data.
+
+  ## Fetch Callback (Optional)
+
+  If all layers miss, an optional fetch callback can supply the value. The
+  fetched value is then backfilled into all layers.
+
+  Define it as a module callback or pass it via opts:
+
+  ```elixir
+  defmodule MyApp.LayeredCache do
+    use Cache,
+      adapter: {Cache.MultiLayer, [Cache.ETS, MyApp.RedisCache]},
+      name: :layered_cache,
+      opts: [on_fetch: &__MODULE__.fetch/1]
+
+    def fetch(key) do
+      {:ok, "value_for_\#{key}"}
+    end
+  end
+  ```
+
+  ## Options
+
+  #{NimbleOptions.docs([
+    on_fetch: [
+      type: {:or, [:mfa, {:fun, 1}]},
+      doc: "Optional fetch callback invoked on total cache miss. Receives the key, returns `{:ok, value}` or `{:error, reason}`."
+    ],
+    backfill_ttl: [
+      type: {:or, [:pos_integer, nil]},
+      doc: "TTL in milliseconds to use when backfilling layers on a hit from a slower layer. Defaults to nil (no expiry)."
+    ]
+  ])}
+  """
+
+  @behaviour Cache.Strategy
+
+  @opts_definition [
+    on_fetch: [
+      type: {:or, [:mfa, {:fun, 1}]},
+      doc: "Optional fetch callback for cache miss."
+    ],
+    backfill_ttl: [
+      type: {:or, [:pos_integer, nil]},
+      doc: "TTL for backfilled entries."
+    ]
+  ]
+
+  @impl Cache.Strategy
+  def opts_definition, do: @opts_definition
+
+  @impl Cache.Strategy
+  def child_spec({cache_name, _layers, _adapter_opts}) do
+    %{
+      id: :"#{cache_name}_multi_layer",
+      start: {Agent, :start_link, [fn -> :ok end, [name: :"#{cache_name}_multi_layer"]]}
+    }
+  end
+
+  @impl Cache.Strategy
+  def get(cache_name, key, layers, adapter_opts) do
+    backfill_ttl = adapter_opts[:backfill_ttl]
+
+    case get_from_layers(cache_name, key, layers, adapter_opts, []) do
+      {:hit, value, layers_to_backfill} ->
+        backfill_layers(cache_name, key, layers_to_backfill, value, backfill_ttl)
+        {:ok, value}
+
+      :miss ->
+        fetch_on_miss(cache_name, key, layers, adapter_opts)
+    end
+  end
+
+  @impl Cache.Strategy
+  def put(cache_name, key, ttl, value, layers, adapter_opts) do
+    reversed = Enum.reverse(layers)
+    put_to_layers(cache_name, key, ttl, value, reversed, adapter_opts)
+  end
+
+  @impl Cache.Strategy
+  def delete(cache_name, key, layers, _adapter_opts) do
+    Enum.reduce_while(layers, :ok, fn layer, _acc ->
+      case layer_delete(cache_name, key, layer) do
+        :ok -> {:cont, :ok}
+        {:error, _} = error -> {:halt, error}
+      end
+    end)
+  end
+
+  defp get_from_layers(_cache_name, _key, [], _adapter_opts, _visited), do: :miss
+
+  defp get_from_layers(cache_name, key, [layer | rest], adapter_opts, visited) do
+    case layer_get(cache_name, key, layer) do
+      {:ok, nil} ->
+        get_from_layers(cache_name, key, rest, adapter_opts, [layer | visited])
+
+      {:ok, value} ->
+        {:hit, value, visited}
+
+      {:error, _} ->
+        get_from_layers(cache_name, key, rest, adapter_opts, [layer | visited])
+    end
+  end
+
+  defp fetch_on_miss(cache_name, key, layers, adapter_opts) do
+    on_fetch = adapter_opts[:on_fetch]
+
+    if is_nil(on_fetch) do
+      {:ok, nil}
+    else
+      case invoke_callback(on_fetch, [key]) do
+        {:ok, value} ->
+          backfill_ttl = adapter_opts[:backfill_ttl]
+          backfill_layers(cache_name, key, layers, value, backfill_ttl)
+          {:ok, value}
+
+        {:error, _} = error ->
+          error
+      end
+    end
+  end
+
+  defp put_to_layers(_cache_name, _key, _ttl, _value, [], _adapter_opts), do: :ok
+
+  defp put_to_layers(cache_name, key, ttl, value, [layer | rest], adapter_opts) do
+    case layer_put(cache_name, key, ttl, value, layer) do
+      :ok -> put_to_layers(cache_name, key, ttl, value, rest, adapter_opts)
+      {:error, _} = error -> error
+    end
+  end
+
+  defp backfill_layers(_cache_name, _key, [], _value, _ttl), do: :ok
+
+  defp backfill_layers(cache_name, key, [layer | rest], value, ttl) do
+    layer_put(cache_name, key, ttl, value, layer)
+    backfill_layers(cache_name, key, rest, value, ttl)
+  end
+
+  defp layer_get(_cache_name, key, layer) when is_atom(layer) do
+    if cache_module?(layer) do
+      layer.get(key)
+    else
+      {:ok, nil}
+    end
+  end
+
+  defp layer_put(_cache_name, key, ttl, value, layer) when is_atom(layer) do
+    if cache_module?(layer) do
+      layer.put(key, ttl, value)
+    else
+      :ok
+    end
+  end
+
+  defp layer_delete(_cache_name, key, layer) when is_atom(layer) do
+    if cache_module?(layer) do
+      layer.delete(key)
+    else
+      :ok
+    end
+  end
+
+  defp cache_module?(module) do
+    function_exported?(module, :get, 1) and function_exported?(module, :put, 2)
+  end
+
+  defp invoke_callback({module, function, args}, extra_args) do
+    apply(module, function, args ++ extra_args)
+  end
+
+  defp invoke_callback(fun, args) when is_function(fun) do
+    apply(fun, args)
+  end
+end

lib/cache/multi_layer.ex

@@ -99,6 +99,11 @@ defmodule Cache.Redis do
       end
 
       def hash_set_many(keys_fields_values, ttl \\ nil) do
+        keys_fields_values =
+          Enum.map(keys_fields_values, fn {key, fields_values} ->
+            {maybe_sandbox_key(key), fields_values}
+          end)
+
         @cache_adapter.hash_set_many(@cache_name, keys_fields_values, ttl, adapter_options())
       end
 

lib/cache/redis.ex

@@ -0,0 +1,97 @@
+defmodule Cache.Strategy do
+  @moduledoc """
+  Behaviour for strategy-based cache adapters.
+
+  Strategy adapters compose over existing cache adapters to provide higher-level
+  caching patterns such as consistent hashing, multi-layer cascading, and
+  refresh-ahead semantics.
+
+  Unlike regular adapters which implement `Cache` directly, strategy adapters
+  receive the underlying adapter module and its resolved options so they can
+  delegate operations appropriately.
+
+  ## Usage
+
+  Strategies are specified using the tuple format in `use Cache`:
+
+  ```elixir
+  use Cache,
+    adapter: {Cache.HashRing, Cache.ETS},
+    name: :my_cache,
+    opts: [read_concurrency: true]
+  ```
+
+  The first element is the strategy module, the second is the underlying adapter
+  (or strategy-specific configuration).
+  """
+
+  @doc """
+  Returns the NimbleOptions schema for validating strategy-level opts.
+  """
+  @callback opts_definition() :: Keyword.t()
+
+  @doc """
+  Returns a supervisor child spec for the strategy.
+
+  Receives the cache name, strategy config (the second element of the adapter
+  tuple), and the resolved underlying adapter opts.
+  """
+  @callback child_spec({
+              cache_name :: atom,
+              strategy_config :: term,
+              adapter_opts :: Keyword.t()
+            }) :: Supervisor.child_spec() | :supervisor.child_spec()
+
+  @doc """
+  Fetches a value from the cache using the strategy's routing/layering logic.
+  """
+  @callback get(
+              cache_name :: atom,
+              key :: atom | String.t(),
+              strategy_config :: term,
+              adapter_opts :: Keyword.t()
+            ) :: ErrorMessage.t_res(any)
+
+  @doc """
+  Stores a value in the cache using the strategy's routing/layering logic.
+  """
+  @callback put(
+              cache_name :: atom,
+              key :: atom | String.t(),
+              ttl :: pos_integer | nil,
+              value :: any,
+              strategy_config :: term,
+              adapter_opts :: Keyword.t()
+            ) :: :ok | ErrorMessage.t()
+
+  @doc """
+  Removes a value from the cache using the strategy's routing/layering logic.
+  """
+  @callback delete(
+              cache_name :: atom,
+              key :: atom | String.t(),
+              strategy_config :: term,
+              adapter_opts :: Keyword.t()
+            ) :: :ok | ErrorMessage.t()
+
+  @doc """
+  Returns true if the given module implements the `Cache.Strategy` behaviour.
+  """
+  @spec strategy?(module()) :: boolean()
+  def strategy?(module) do
+    module
+    |> module_behaviours()
+    |> Enum.member?(Cache.Strategy)
+  rescue
+    _ -> false
+  end
+
+  defp module_behaviours(module) do
+    module
+    |> :erlang.apply(:module_info, [:attributes])
+    |> Keyword.get_values(:behaviour)
+    |> List.flatten()
+  rescue
+    _ -> []
+  end
+end

lib/cache/strategy.ex

@@ -18,6 +18,7 @@
   "hackney": {:hex, :hackney, "1.18.1", "f48bf88f521f2a229fc7bae88cf4f85adc9cd9bcf23b5dc8eb6a1788c662c4f6", [:rebar3], [{:certifi, "~> 2.9.0", [hex: :certifi, repo: "hexpm", optional: false]}, {:idna, "~> 6.1.0", [hex: :idna, repo: "hexpm", optional: false]}, {:metrics, "~> 1.0.0", [hex: :metrics, repo: "hexpm", optional: false]}, {:mimerl, "~> 1.1", [hex: :mimerl, repo: "hexpm", optional: false]}, {:parse_trans, "3.3.1", [hex: :parse_trans, repo: "hexpm", optional: false]}, {:ssl_verify_fun, "~> 1.1.0", [hex: :ssl_verify_fun, repo: "hexpm", optional: false]}, {:unicode_util_compat, "~> 0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "a4ecdaff44297e9b5894ae499e9a070ea1888c84afdd1fd9b7b2bc384950128e"},
   "idna": {:hex, :idna, "6.1.1", "8a63070e9f7d0c62eb9d9fcb360a7de382448200fbbd1b106cc96d3d8099df8d", [:rebar3], [{:unicode_util_compat, "~> 0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "92376eb7894412ed19ac475e4a86f7b413c1b9fbb5bd16dccd57934157944cea"},
   "jason": {:hex, :jason, "1.4.4", "b9226785a9aa77b6857ca22832cffa5d5011a667207eb2a0ad56adb5db443b8a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "c5eb0cab91f094599f94d55bc63409236a8ec69a21a67814529e8d5f6cc90b3b"},
+  "libring": {:hex, :libring, "1.7.0", "4f245d2f1476cd7ed8f03740f6431acba815401e40299208c7f5c640e1883bda", [:mix], [], "hexpm", "070e3593cb572e04f2c8470dd0c119bc1817a7a0a7f88229f43cf0345268ec42"},
   "makeup": {:hex, :makeup, "1.2.1", "e90ac1c65589ef354378def3ba19d401e739ee7ee06fb47f94c687016e3713d1", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "d36484867b0bae0fea568d10131197a4c2e47056a6fbe84922bf6ba71c8d17ce"},
   "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"},
   "makeup_erlang": {:hex, :makeup_erlang, "1.0.2", "03e1804074b3aa64d5fad7aa64601ed0fb395337b982d9bcf04029d68d51b6a7", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "af33ff7ef368d5893e4a267933e7744e46ce3cf1f61e2dccf53a111ed3aa3727"},