Defines the behaviour for session processes in Phoenix.SessionProcess.

Session processes are GenServer processes that manage isolated state for each user session. They integrate with the Redux Store infrastructure for state management.

Required Callbacks

• init_state/1 - Initialize the session's application state (required)

Optional Callbacks

• combined_reducers/0 - Define reducer modules for state slicing (optional)
• GenServer callbacks (handle_call/3, handle_cast/2, etc.) - Handle custom messages (optional)

Usage

To create a session process, use the :process macro:

defmodule MyApp.SessionProcess do
  use Phoenix.SessionProcess, :process

  @impl true
  def init_state(_arg) do
    %{user_id: nil, cart: [], preferences: %{}}
  end

  # Optional: Define reducers for state slicing
  @impl true
  def combined_reducers do
    [
      MyApp.CounterReducer,
      MyApp.UserReducer
    ]
  end

  # Optional: Add custom GenServer handlers
  @impl true
  def handle_call(:custom_action, _from, state) do
    {:reply, :ok, state}
  end

  @impl true
  def handle_cast({:custom_event, data}, state) do
    # Custom logic
    {:noreply, state}
  end
end

Redux Integration

Session processes automatically include Redux Store infrastructure:

• State Management: All state updates go through dispatch/4
• Reducers: Use combined_reducers/0 to define reducer modules
• Subscriptions: Automatic subscription management with selectors
• History: Optional action history tracking
• Async Actions: Built-in support for async operations

State Structure

The session process maintains state with two layers:

1. Application State (state.app_state):

   • Your custom state from init_state/1
   • Reducer slices from combined_reducers/0

2. Redux Infrastructure (internal, prefixed with _redux_):

   • _redux_reducers - Registered reducer modules
   • _redux_subscriptions - Active subscriptions
   • _redux_history - Action history
   • _redux_throttle_state - Throttle/debounce state
   • Other internal state

Example with Reducers

defmodule MyApp.SessionProcess do
  use Phoenix.SessionProcess, :process

  @impl true
  def init_state(_arg) do
    # Initial state before reducer slices are added
    %{session_created_at: DateTime.utc_now()}
  end

  @impl true
  def combined_reducers do
    [
      MyApp.CounterReducer,    # Adds state.counter slice
      MyApp.UserReducer        # Adds state.user slice
    ]
  end
end

# After initialization, state looks like:
# %{
#   session_created_at: ~U[2024-01-01 00:00:00Z],
#   counter: %{count: 0},           # From CounterReducer.init_state/0
#   user: %{current_user: nil}      # From UserReducer.init_state/0
# }

Reducer Formats

The combined_reducers/0 callback can return three formats:

1. Module atom - Uses the reducer's @name and @action_prefix:

   [MyApp.UserReducer]

2. {name, Module} tuple - Custom name, action_prefix defaults to stringified name:

   [{:cart, MyApp.CartReducer}]

3. {name, Module, action_prefix} tuple - Explicit name and action_prefix:

   [{:shipping, MyApp.ShippingReducer, "ship"}]

GenServer Integration

Since :process uses use GenServer, you can implement any GenServer callback:

• handle_call/3 - Synchronous requests
• handle_cast/2 - Asynchronous messages
• handle_info/2 - Process messages
• terminate/2 - Cleanup on shutdown
• code_change/3 - Hot code reloading

Accessing Session ID

Within the session process, use get_session_id/0 to retrieve the current session ID:

def handle_call(:get_id, _from, state) do
  session_id = get_session_id()
  {:reply, session_id, state}
end

Communication

Use the Phoenix.SessionProcess API to communicate with session processes:

# Start session
{:ok, _pid} = Phoenix.SessionProcess.start_session(session_id)

# Dispatch actions
:ok = Phoenix.SessionProcess.dispatch(session_id, "counter.increment")
:ok = Phoenix.SessionProcess.dispatch(session_id, "user.set", %{id: 123})

# Get state
state = Phoenix.SessionProcess.get_state(session_id)

# Custom calls/casts
{:ok, result} = Phoenix.SessionProcess.call(session_id, :custom_action)
:ok = Phoenix.SessionProcess.cast(session_id, {:custom_event, data})