Add Nebulex.Adapter.CompositeKV behaviour for composite KV operations

[cabol]

Problem

The composite KV operations get_and_update/3, update/4, fetch_or_store/3, and get_or_store/3 were not adapter callbacks. They lived only in Nebulex.Cache.KV, composed on top of the primitive fetch, put, and delete commands, with the given function always evaluated in the calling process.

Adapters had no way to change that. The Nebulex.Adapters.Partitioned docs claimed the supplied function ran on the node owning the key, but only the primitive commands were routed there; the function itself always ran locally, as elixir-nebulex/nebulex_distributed#19 reports. For the workload in that issue, where computing each value requires a large amount of memory in a lower-level cache, every node must hold enough memory for the whole key space instead of its own partition, so the cache cannot scale that workload by adding nodes.

Change

Add Nebulex.Adapter.CompositeKV, which specifies the four operations as adapter callbacks. use Nebulex.Adapter.CompositeKV provides the default implementation, moved out of Nebulex.Cache.KV, with every callback overridable.

The behaviour is required. use Nebulex.Cache validates at compile time that the adapter implements Nebulex.Adapter, Nebulex.Adapter.KV, and Nebulex.Adapter.CompositeKV, naming the missing one otherwise, and Nebulex.Cache.CompositeKV dispatches each command to the adapter callback like every other cache command. Adapters implement the callbacks to change where the function runs or to provide different atomicity guarantees; use Nebulex.Adapter.CompositeKV gives them the default.

Nebulex.Cache gains the public types get_and_update_fun/0 and update_fun/0 for the callback signatures, and ttl/0 and keep_ttl/0, which Nebulex.Adapter.KV and the expire callbacks now reuse instead of defining their own.

Three shared suites cover the operations. Nebulex.Cache.CompositeKVTest and Nebulex.Cache.CompositeKVTelemetryTest are registered in Nebulex.CacheTestCase; Nebulex.Cache.CompositeKVErrorTest is used by Nebulex.CacheErrorTest alongside the other error suites.

The adapter-authoring guide, the getting-started guide, and usage-rules/nebulex.md are updated for the behaviour.

Closes #254.

Release notes

New

• Nebulex.Adapter.CompositeKV, an adapter behaviour for the composite KV operations get_and_update, update, fetch_or_store, and get_or_store. Adapters can implement the callbacks to change where the given function runs or to provide different atomicity guarantees; use Nebulex.Adapter.CompositeKV provides the default, non-atomic implementation with all callbacks overridable.
• Composite operations are now adapter commands and emit their own Telemetry command span in addition to the primitive spans. Handlers see four new :command values: :get_and_update, :update, :fetch_or_store, and :get_or_store. A handler that matches command exhaustively without a fallback clause will raise and be detached on the first composite call.
• New public types Nebulex.Cache.get_and_update_fun/0, Nebulex.Cache.update_fun/0, Nebulex.Cache.ttl/0, and Nebulex.Cache.keep_ttl/0.

Fixed

• Nebulex.Adapter.run_command/4 no longer strips the shared :telemetry, :telemetry_event, and :telemetry_metadata options before invoking the adapter, reversing the v3.0.0 behavior of extracting them to keep adapter arguments clean. Nested commands, such as the primitive commands run by a composite operation, now receive them: telemetry: false disables the nested spans and the cache entry events and stats derived from them, :telemetry_metadata reaches the nested spans, and a custom :telemetry_event applies to them. Adapters that forward :telemetry_metadata to their backend, such as the Redis adapter, now receive it. The options appear in the :args Telemetry metadata as the adapter receives them.

Behavior changes

• get_and_update/3 no longer treats a nil new value as "do not write". A function returning {current, nil} stores nil under the key and returns {current, nil}, instead of skipping the write and returning {current, current}. That short-circuit came from v2, where nil was the cache-miss sentinel; v3 treats nil as a valid cache value, and update/4 already stored it.
• get_and_update/3 with :pop now removes an entry holding nil. The default implementation mapped a missing key to nil before handing it to the function, which also made a cached nil look like a miss, so :pop skipped the delete. A missing key still issues no delete command.

For adapter developers

Adapters must implement Nebulex.Adapter.CompositeKV; a cache using an adapter that does not fails to compile with a message naming the behaviour. Add use Nebulex.Adapter.CompositeKV for the default implementation, or implement the callbacks. Two more things may require changes. Adapter callbacks now receive the shared :telemetry, :telemetry_event, and :telemetry_metadata options in opts, so a callback that validates its options strictly must drop them first with Keyword.drop(opts, Nebulex.Cache.Options.__runtime_shared_opts__()). Adapter repositories running the shared test suite need the composite helpers in their test cache module: fetch_or_store_fun/0, fetch_or_store_error_fun/0, and get_or_store_fun/0.

The built-in cache entry and stats handlers are driven by the primitive command events. If an override bypasses those commands, or runs them under another cache's metadata, those handlers will not account for the operation on the original cache. Core cannot derive the events from the composite command: adding handler clauses for it would double-count on the default path, which already emits the primitive events, and fetch_or_store/get_or_store return {:ok, value} on both a hit and a miss, so the composite event does not say whether anything was written. Overrides should preserve equivalent events for the affected cache.

Validation

mix precommit passes: 435 tests, 100% coverage, Dialyzer 0 errors, Credo strict, format, Sobelow, deps.audit, doctor, and mix docs with no warnings.

Next

Nebulex.Adapters.Partitioned in nebulex_distributed can implement the callbacks to run the given function on the node owning the key, resolving nebulex_distributed#19. The other adapters in that repository need only use Nebulex.Adapter.CompositeKV.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unittests-elixir-1.20.x-otp-29.x	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
lib/nebulex/adapter.ex	100.00% <100.00%> (ø)
lib/nebulex/adapter/composite_kv.ex	100.00% <100.00%> (ø)
lib/nebulex/adapters/nil.ex	100.00% <ø> (ø)
lib/nebulex/cache.ex	100.00% <100.00%> (ø)
lib/nebulex/cache/composite_kv.ex	100.00% <100.00%> (ø)
lib/nebulex/cache/kv.ex	100.00% <ø> (ø)
lib/nebulex/cache/options.ex	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Copilot review overview

🟡 Changes recommended

A moderate compatibility issue remains in fetch_or_store/6 and get_or_store/6 when adapters return {:ok, false} from put.

Review effort: Lite
Findings: 2

Open (2)

• Test adapter CompositeKV callback dispatch · New
• Clarify CompositeKV dispatcher behavior documentation · New

What changed in this PR

Adds adapter-level CompositeKV callbacks with default implementations, telemetry support, updated public types, tests, and documentation.

Changes:

• Introduces Nebulex.Adapter.CompositeKV and cache-layer dispatch.
• Updates telemetry forwarding and composite operation semantics.
• Adds shared coverage, guides, architecture rules, and release notes.

File	Description
usage-rules/​nebulex.md	Documents CompositeKV behavior.
usage-rules/​architecture.md	Updates architecture guidance.
test/​support/​test_cache.exs	Adds composite test helpers.
test/​support/​test_adapter.exs	Handles shared runtime options.
test/​support/​fake_adapter.exs	Uses default CompositeKV behavior.
test/​shared/​cache/​kv_test.exs	Updates KV test coverage.
test/​shared/​cache/​composite_kv_test.exs	Tests composite operations.
test/​shared/​cache/​composite_kv_telemetry_test.exs	Tests composite telemetry.
test/​shared/​cache/​composite_kv_error_test.exs	Tests composite errors.
test/​shared/​cache_test_case.exs	Registers shared suites.
test/​nebulex/​telemetry_test.exs	Tests telemetry option forwarding.
test/​nebulex/​cache_test.exs	Updates cache behavior tests.
test/​nebulex/​cache_error_test.exs	Registers composite error tests.
mix.exs	Updates documentation configuration.
lib/​nebulex/​cache/​kv.ex	Removes relocated implementations.
lib/​nebulex/​cache/​composite_kv.ex	Dispatches composite operations.
lib/​nebulex/​cache.ex	Adds APIs, types, and documentation.
lib/​nebulex/​adapter/​kv.ex	Reuses shared cache types.
lib/​nebulex/​adapter/​composite_kv.ex	Defines callbacks and defaults.
lib/​nebulex/​adapter.ex	Adds telemetry-aware command execution.
guides/​learning/​creating-new-adapter.md	Documents adapter behavior.
guides/​introduction/​getting-started.md	Updates usage guidance.
CHANGELOG.md	Records release changes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.