Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 70 additions & 39 deletions lib/cache/multi_layer.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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)
Expand Down
123 changes: 123 additions & 0 deletions test/cache/multi_layer_layer_validation_test.exs
Original file line number Diff line number Diff line change
@@ -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
13 changes: 11 additions & 2 deletions test/cache_strategy_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand Down Expand Up @@ -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)
Expand Down
Loading