Persistence contract for Omni.Session.

Defines the adapter behaviour that storage backends implement, and the dispatch functions that Omni.Session (and applications) call.

A store is a %Store{} struct pairing the adapter module with its initialised config. Build one with init/1, which accepts several convenience forms:

# Tuple — the most common form in config files
{:ok, store} = Omni.Session.Store.init({Omni.Session.Stores.FileSystem, base_dir: "/data/sessions"})

# Bare module — equivalent to {mod, []}
{:ok, store} = Omni.Session.Store.init(Omni.Session.Stores.FileSystem)

# Already-initialised struct — pass-through
{:ok, ^store} = Omni.Session.Store.init(store)

Omni.Session.start_link/1 and Omni.Session.Manager.start_link/1 both accept any of these forms as the :store option and call init/1 internally, so callers rarely need to call it directly.

Configuring a store once in an application

The recommended path is to use Omni.Session.Manager with otp_app:, which reads the store from Application.get_env/3 for you:

defmodule MyApp.Sessions do
  use Omni.Session.Manager, otp_app: :my_app
end

# config/config.exs
config :my_app, MyApp.Sessions,
  store: {Omni.Session.Stores.FileSystem, base_dir: "/var/data/sessions"}

# everywhere a session is needed
MyApp.Sessions.create(agent: [...])
MyApp.Sessions.delete("abc-123")

When configuration varies per environment, override in config/test.exs (etc.) using the same key.

Direct (non-Manager) usage

When sessions are started outside a Manager, the application owns the store configuration. A module attribute is enough for static configuration:

defmodule MyApp.Storage do
  @store {Omni.Session.Stores.FileSystem, base_dir: "/var/data/sessions"}
  def store, do: @store
end

Omni.Session.start_link(store: MyApp.Storage.store(), new: id, agent: [...])

For environment-specific configuration without a Manager, read the tuple from Application.get_env/3 inside the wrapper.

State categories

Persisted state falls into two categories, owned by different write paths:

The two write paths operate on disjoint keys. Adapters that persist both in a single file or row (the FileSystem reference does) can safely read-modify-write each side — it is key-splatting, not a semantic merge.

Error model

Store callbacks return {:error, term()} on failure; Session never halts on store errors. POSIX atoms (e.g. :enoent, :eacces) bubble up unwrapped from filesystem backends. Error reasons are adapter-specific.

Implementing an adapter

Implement @behaviour Omni.Session.Store and the seven callbacks:

• init/1
• save_tree/4
• save_state/4
• load/3
• list/2
• delete/3
• exists?/2

init/1 receives the raw keyword config from the store tuple and returns {:ok, config_state} or {:error, reason}. The returned config_state is what all other callbacks receive as their first argument — it can be a keyword list, map, struct, or any term the adapter prefers.