diff --git a/lib/cache/multi_layer.ex b/lib/cache/multi_layer.ex index b15b184..9e1df26 100644 --- a/lib/cache/multi_layer.ex +++ b/lib/cache/multi_layer.ex @@ -8,36 +8,45 @@ defmodule Cache.MultiLayer do ## 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 + Every layer is a `use Cache` MODULE — one that is already defined and + supervised in its own right. Adapters (`Cache.ETS`, `Cache.Redis`) are not + layers: an adapter is stateless and exports `get/3`/`put/5`, so it has no + instance to address, while a cache module exports `get/1`/`put/3` and + carries its own name. Wrap the adapter in a module and list that. ```elixir + defmodule MyApp.Local do + use Cache, adapter: Cache.ETS, name: :my_app_local, opts: [] + end + + defmodule MyApp.Shared do + use Cache, adapter: Cache.Redis, name: :my_app_shared, opts: [uri: "redis://localhost"] + end + defmodule MyApp.LayeredCache do use Cache, - adapter: {Cache.MultiLayer, [Cache.ETS, MyApp.RedisCache]}, + adapter: {Cache.MultiLayer, [MyApp.Local, MyApp.Shared]}, 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. + Start every layer alongside the cascade, layers first: ```elixir - defmodule MyApp.LayeredCache do - use Cache, - adapter: {Cache.MultiLayer, [Cache.ETS, __MODULE__, MyApp.RedisCache]}, - name: :layered_cache, - opts: [uri: "redis://localhost"] - end + {Cache, [MyApp.Local, MyApp.Shared, MyApp.LayeredCache]} ``` + A layer that is not a cache module raises at startup with the offending + module named — see `child_spec/1`. Passing an adapter used to be documented + and silently did nothing, which is the failure this validation exists to + make impossible. + + ## A cache cannot be its own layer + + Do not list the defining module in its own layer list. Its `get/1` is this + strategy's `get/4`, so the cascade would call back into itself. + ## Read Behaviour Layers are iterated fastest → slowest (list order). On a hit from layer N, @@ -145,10 +154,46 @@ defmodule Cache.MultiLayer do def opts_definition, do: @opts_definition @impl Cache.Strategy - def child_spec({cache_name, _layers, _adapter_opts}) do + def child_spec({cache_name, layers, _adapter_opts}) do + validate_layers!(cache_name, layers) + Cache.MultiLayer.Coordinator.child_spec(cache_name) end + # Layers are `use Cache` MODULES. Anything else — an adapter, a tuple, a + # typo — is rejected here, at startup, with the offending element named. + # + # This is not defensive tidiness: the dispatch below is duck-typed on + # `get/1`/`put/3`, and its previous no-match branches returned `{:ok, nil}` + # and `:ok`. Those are SUCCESS shapes. A layer that fails the check would + # read as a permanent miss and discard every write, and neither is + # distinguishable from a cold cache and a successful write — so a + # misconfigured cascade behaved exactly like a working one, forever. + # Startup is the last place this can still be loud. + defp validate_layers!(cache_name, layers) do + Enum.each(layers, fn layer -> + unless is_atom(layer) and cache_module?(layer) do + raise ArgumentError, """ + #{inspect(cache_name)}: every Cache.MultiLayer layer must be a `use Cache` module, got: + + #{inspect(layer)} + + An adapter (Cache.ETS, Cache.Redis) is not a layer — it is stateless and + exports get/3, while a layer must export get/1. Wrap it in a module: + + defmodule MyApp.Local do + use Cache, adapter: Cache.ETS, name: :my_app_local, opts: [] + end + + then list `MyApp.Local`, and start it alongside the cascade. + + If the module IS a `use Cache` module, it is not compiled or loaded yet — + check for a typo or a missing dependency. + """ + end + end) + end + @impl Cache.Strategy def get(cache_name, key, layers, adapter_opts) do backfill_ttl = adapter_opts[:backfill_ttl] @@ -278,29 +323,15 @@ defmodule Cache.MultiLayer do 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 + # `validate_layers!/2` has already rejected anything that is not a cache + # module, so these dispatch directly. No fallback branch: a fallback here + # could only return a success shape, which is the defect that made a broken + # layer indistinguishable from a working one. + defp layer_get(_cache_name, key, layer), do: layer.get(key) - 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_put(_cache_name, key, ttl, value, layer), do: layer.put(key, ttl, value) - 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 layer_delete(_cache_name, key, layer), do: layer.delete(key) defp cache_module?(module) do function_exported?(module, :get, 1) and function_exported?(module, :put, 2) diff --git a/test/cache/multi_layer_layer_validation_test.exs b/test/cache/multi_layer_layer_validation_test.exs new file mode 100644 index 0000000..e7b6599 --- /dev/null +++ b/test/cache/multi_layer_layer_validation_test.exs @@ -0,0 +1,123 @@ +defmodule Cache.MultiLayerLayerValidationTest do + @moduledoc """ + `Cache.MultiLayer` layers are `use Cache` MODULES. Anything else is rejected + at startup by `validate_layers!/2`. + + The moduledoc previously documented three other forms — a bare adapter, a + `{Adapter, opts}` tuple, and `__MODULE__` — and none of them worked. The + adapter forms were the dangerous ones: dispatch gated on + `function_exported?(module, :get, 1)`, which an adapter cannot satisfy + (adapters export `get/3`), and the else branches returned `{:ok, nil}` and + `:ok`. + + Those are SUCCESS shapes, which is what made the defect survive. A layer + that always misses is indistinguishable from a cold cache; a write that + no-ops is indistinguishable from one that worked. Every test asserting only + "the cascade returns the right value" passes with the fast layer entirely + inert — which is why the first suite written against this cascade passed + while one of its two layers did nothing at all. + + So there are two things to pin, and both are about failure being visible: + a bad layer is REJECTED LOUDLY at startup, and a good cascade is provably + two layers rather than one. + """ + use ExUnit.Case, async: true + + defmodule FastLayer do + @moduledoc false + use Cache, adapter: Cache.ETS, name: :multi_layer_validation_fast, opts: [] + end + + defmodule SlowLayer do + @moduledoc false + use Cache, adapter: Cache.ETS, name: :multi_layer_validation_slow, opts: [] + end + + defmodule LayeredCache do + @moduledoc false + use Cache, + adapter: {Cache.MultiLayer, [FastLayer, SlowLayer]}, + name: :multi_layer_validation_cascade, + opts: [backfill_ttl: :timer.seconds(60)] + end + + describe "layer validation rejects non-modules at startup" do + test "a bare adapter raises, naming the offending element" do + assert_raise ArgumentError, ~r/must be a `use Cache` module/, fn -> + Cache.MultiLayer.child_spec({:rejects_adapter, [Cache.ETS, SlowLayer], []}) + end + end + + test "the message names the adapter that was passed" do + error = + assert_raise ArgumentError, fn -> + Cache.MultiLayer.child_spec({:rejects_adapter_named, [Cache.ETS], []}) + end + + assert error.message =~ "Cache.ETS" + assert error.message =~ "Wrap it in a module" + end + + test "an {Adapter, opts} tuple raises rather than crashing on a missing clause" do + assert_raise ArgumentError, ~r/must be a `use Cache` module/, fn -> + Cache.MultiLayer.child_spec({:rejects_tuple, [{Cache.ETS, []}, SlowLayer], []}) + end + end + + test "an unloaded or misspelled module raises" do + assert_raise ArgumentError, ~r/must be a `use Cache` module/, fn -> + Cache.MultiLayer.child_spec({:rejects_typo, [NoSuchCacheModule], []}) + end + end + + test "positive control: a list of real cache modules is accepted" do + assert %{id: _id, start: _start} = + Cache.MultiLayer.child_spec({:accepts_modules, [FastLayer, SlowLayer], []}) + end + end + + describe "a validated cascade is actually two layers" do + setup do + start_supervised!({Cache, [FastLayer, SlowLayer, LayeredCache]}) + :ok + end + + # The only assertion a broken fast layer cannot fake: write to the SLOW + # layer only, then remove it. Nothing but a real backfill into a real fast + # layer can answer the second read. + test "a slow-layer hit backfills the fast layer, and survives the slow copy going away" do + :ok = SlowLayer.put("k", nil, "slow_only") + + assert {:ok, "slow_only"} = LayeredCache.get("k") + + :ok = SlowLayer.delete("k") + assert {:ok, nil} = SlowLayer.get("k") + + assert {:ok, "slow_only"} = LayeredCache.get("k") + end + + test "a write reaches the fast layer, not only the slow one" do + :ok = LayeredCache.put("w", nil, "written") + + :ok = SlowLayer.delete("w") + assert {:ok, nil} = SlowLayer.get("w") + + assert {:ok, "written"} = LayeredCache.get("w") + end + + test "a write reaches the slow layer, not only the fast one" do + :ok = LayeredCache.put("s", nil, "written") + + assert {:ok, "written"} = SlowLayer.get("s") + end + + test "delete clears both layers" do + :ok = LayeredCache.put("d", nil, "gone") + :ok = LayeredCache.delete("d") + + assert {:ok, nil} = FastLayer.get("d") + assert {:ok, nil} = SlowLayer.get("d") + assert {:ok, nil} = LayeredCache.get("d") + end + end +end diff --git a/test/cache_strategy_test.exs b/test/cache_strategy_test.exs index 23258ed..5d7e3ca 100644 --- a/test/cache_strategy_test.exs +++ b/test/cache_strategy_test.exs @@ -45,9 +45,18 @@ defmodule CacheStrategyTest do opts: [] end + defmodule TestCache.FetchLayer do + use Cache, adapter: Cache.ETS, name: :test_strategy_fetch_layer, opts: [] + end + + # Was `[Cache.ETS]` — an adapter, which `validate_layers!/2` now rejects. + # Worth recording why that mattered rather than just fixing it: an adapter + # layer silently no-opped, so this cascade had ZERO working layers and + # `on_fetch` fired on a miss that was guaranteed rather than observed. The + # test passed for the wrong reason, and could not have failed. defmodule TestCache.MultiLayerFetch do use Cache, - adapter: {Cache.MultiLayer, [Cache.ETS]}, + adapter: {Cache.MultiLayer, [TestCache.FetchLayer]}, name: :test_strategy_multi_layer_fetch, opts: [on_fetch: &__MODULE__.fetch/1] @@ -316,7 +325,7 @@ defmodule CacheStrategyTest do type: :supervisor, start: {Cache, :start_link, - [[TestCache.MultiLayerFetch], [name: :multi_layer_fetch_sup]]} + [[TestCache.FetchLayer, TestCache.MultiLayerFetch], [name: :multi_layer_fetch_sup]]} }) Process.sleep(50)