Lotus.Cache (Lotus v1.2.0)

Lotus cache facade. If no adapter configured, acts as a no-op pass-through.

Summary

Functions

build_options(cache_opts, tags)

Builds the per-entry options for a cache write.

delete(key)

Removes one entry.

enabled?()

get(key)

get_or_store(key, ttl_ms, fun, opts \\ [])

invalidate_scope(scope)

Invalidates all cache entries associated with the given scope.

invalidate_tags(tags)

Invalidates every entry that carries one of tags.

put(key, value, ttl_ms, opts \\ [])

scope(operation)

How far one delete/1 or invalidate_tags/1 on the configured adapter reaches.

Types

key()

@type key() :: binary()

opts()

@type opts() :: Keyword.t()

ttl_ms()

@type ttl_ms() :: non_neg_integer()

value()

@type value() :: any()

Functions

build_options(cache_opts, tags)

@spec build_options(term(), [String.t()]) :: opts()

Builds the per-entry options for a cache write.

Layers the caller's :cache option over the entry options set in application config, then adds the invalidation tags. A caller that passes no :cache option, or an atom such as :bypass, still gets the configured defaults.

delete(key)

@spec delete(key()) :: :ok | {:error, term()}

Removes one entry.

When the adapter's delete is node-local the call is relayed to the other nodes of the cluster. See scope/1.

enabled?()

@spec enabled?() :: boolean()

get(key)

@spec get(key()) :: {:ok, value()} | :miss

get_or_store(key, ttl_ms, fun, opts \\ [])

@spec get_or_store(key(), ttl_ms(), (-> value()), opts()) ::
  {:ok, value(), :hit | :miss | atom()} | {:error, term()}

invalidate_scope(scope)

@spec invalidate_scope(term()) :: :ok | {:error, term()}

Invalidates all cache entries associated with the given scope.

Uses tag-based invalidation — each scoped cache entry is tagged with "scope:<digest>", so this clears only entries for the specified scope without flushing the entire source cache.

Examples

Lotus.Cache.invalidate_scope(%{tenant_id: 42})
Lotus.Cache.invalidate_scope(%{role: :admin})

invalidate_tags(tags)

@spec invalidate_tags([binary()]) :: :ok | {:error, term()}

Invalidates every entry that carries one of tags.

When the adapter's tag bookkeeping is node-local the call is relayed to the other nodes of the cluster. See scope/1.

put(key, value, ttl_ms, opts \\ [])

@spec put(key(), value(), ttl_ms(), opts()) :: :ok | {:error, term()}

scope(operation)

@spec scope(Lotus.Cache.Adapter.relayed_operation()) :: :node | :cluster

How far one delete/1 or invalidate_tags/1 on the configured adapter reaches.

:node means the call only touches the calling node, so it is relayed to the other nodes over Lotus.Notifier and applied there by Lotus.Cache.Relay. :cluster means one call already reaches every node and nothing is relayed. An adapter that does not implement Lotus.Cache.Adapter.scope/1 counts as :node for both. Without a configured adapter the answer is :cluster, because there is nothing to relay.