From 352f11e14cbaaaa83610140131b0328863f62910 Mon Sep 17 00:00:00 2001 From: MikaAK Date: Wed, 2 Sep 2026 17:56:00 -0700 Subject: [PATCH 1/2] fix(multi_layer): reject non-module layers instead of silently no-opping MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cache.MultiLayer documented four layer forms and one worked. A bare adapter (Cache.ETS), a {Adapter, opts} tuple, and __MODULE__ were all documented; the first two dispatched through cache_module?(m) = function_exported?(m, :get, 1) and function_exported?(m, :put, 2) which an adapter cannot satisfy — an adapter exports get/3 and put/5 — and the else branches returned {:ok, nil} and :ok. Those are success shapes, and that is what made this survive: a layer that always misses is indistinguishable from a cold cache, and a write that no-ops is indistinguishable from one that worked. A cascade with an inert layer behaves exactly like a working one, so any test asserting only "the cascade returns the right value" passes either way. Layers are cache modules. validate_layers!/2 rejects anything else at startup, naming the offending element and how to wrap it. The no-match dispatch branches are gone — there is no longer any way for a layer to fail quietly, because the only fallback available to them was a success shape. Also fixes a test that was passing for the wrong reason: MultiLayerFetch listed [Cache.ETS] as its only layer, so on_fetch fired against a cascade of zero working layers — a total miss that was guaranteed rather than observed. The moduledoc now documents only the form that works, plus the constraint that a cache cannot be its own layer (its get/1 is this strategy's get/4, so the cascade would recurse). Tests: 9 new (5 rejection incl. a positive control, 4 proving a validated cascade is really two layers — written as slow-layer-only writes that are then removed, since that is the one assertion an inert fast layer cannot fake). Suite 330/343; the 13 failures are RedisJSONTest against a local Redis with no RedisJSON module, and are identical on an unmodified tree. --- lib/cache/multi_layer.ex | 109 ++++++++++------ .../multi_layer_layer_validation_test.exs | 123 ++++++++++++++++++ test/cache_strategy_test.exs | 13 +- 3 files changed, 204 insertions(+), 41 deletions(-) create mode 100644 test/cache/multi_layer_layer_validation_test.exs 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..c5097e6 --- /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) From 7d273628fec6ed6d8bc598367cc9b7d72b60d07d Mon Sep 17 00:00:00 2001 From: MikaAK Date: Wed, 2 Sep 2026 22:10:36 -0700 Subject: [PATCH 2/2] test(multi_layer): lowercase positive-control test name for credo Claude-Session: https://claude.ai/code/session_014FgvF2AKpSdWdLEEQQjhjZ --- test/cache/multi_layer_layer_validation_test.exs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/cache/multi_layer_layer_validation_test.exs b/test/cache/multi_layer_layer_validation_test.exs index c5097e6..e7b6599 100644 --- a/test/cache/multi_layer_layer_validation_test.exs +++ b/test/cache/multi_layer_layer_validation_test.exs @@ -70,7 +70,7 @@ defmodule Cache.MultiLayerLayerValidationTest do end end - test "POSITIVE CONTROL: a list of real cache modules is accepted" do + 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