feat: add configurable unmatched action handling for reducers

Add handle_unmatched_action/2 and handle_unmatched_async/3 callbacks to allow
customization of behavior when actions don't match any pattern in reducers.

Changes:
- Add unmatched_action_handler config option (:log, :warn, :silent, or custom function/3)
- Update :reducer macro to provide default implementations that respect global config
- Add handle_unmatched_action/2 callback for sync actions (overridable per-reducer)
- Add handle_unmatched_async/3 callback for async actions (overridable per-reducer)
- Default behavior logs debug message suggesting use of @action_prefix
- Add comprehensive test suite (6 new tests)
- Update CLAUDE.md documentation with usage examples and configuration

This helps developers debug action routing issues and optimize reducer performance
by identifying when too many unmatched actions are being processed.

Author: GSMLG-BOT

CLAUDE.md

@@ -269,6 +269,13 @@ The library is organized into several logical groups:
   - `dispatch_async/4` is an alias for `dispatch(id, type, payload, [meta | async: true])`
   - `handle_async/3` MUST return cancellation callback `(() -> any())` for internal use
 
+- **Unmatched Action Handling**:
+  - Reducers can override `handle_unmatched_action/2` to customize behavior for unmatched actions
+  - Reducers can override `handle_unmatched_async/3` to customize behavior for unmatched async actions
+  - Global handler configured via `unmatched_action_handler` config option (:log, :warn, :silent, or custom function)
+  - Default behavior logs debug message suggesting use of `@action_prefix` to limit action routing
+  - Useful for debugging action routing issues in complex applications
+
 - **LiveView Integration**:
   - Use `Phoenix.SessionProcess.LiveView.mount_store/4` for direct subscriptions
   - Selector-based updates for efficiency
@@ -286,14 +293,20 @@ config :phoenix_session_process,
   session_process: MySessionProcess,  # Default session module
   max_sessions: 10_000,               # Maximum concurrent sessions
   session_ttl: 3_600_000,            # Session TTL in milliseconds (1 hour)
-  rate_limit: 100                    # Sessions per minute limit
+  rate_limit: 100,                   # Sessions per minute limit
+  unmatched_action_handler: :log     # How to handle unmatched actions (:log, :warn, :silent, or function)
 ```
 
 Configuration options:
 - `session_process`: Default module for session processes (defaults to `Phoenix.SessionProcess.DefaultSessionProcess`)
 - `max_sessions`: Maximum concurrent sessions (defaults to 10,000)
 - `session_ttl`: Session TTL in milliseconds (defaults to 1 hour)
 - `rate_limit`: Sessions per minute limit (defaults to 100)
+- `unmatched_action_handler`: How to handle actions that don't match any pattern in reducers (defaults to `:log`)
+  - `:log` - Log debug messages for unmatched actions
+  - `:warn` - Log warning messages for unmatched actions
+  - `:silent` - No logging
+  - Custom function with arity 3: `fn action, reducer_module, reducer_name -> ... end`
 
 ## Usage in Phoenix Applications
 
@@ -406,7 +419,8 @@ end
 config :phoenix_session_process,
   session_process: MyApp.SessionProcess,
   max_sessions: 10_000,
-  session_ttl: 3_600_000
+  session_ttl: 3_600_000,
+  unmatched_action_handler: :log  # Optional: :log | :warn | :silent | custom function
 
 # lib/my_app/application.ex
 def start(_type, _args) do
@@ -647,3 +661,25 @@ Use `Phoenix.SessionProcess.Error.message/1` for human-readable error messages.
    # Client-side selection - transfers full state
    count = SessionProcess.get_state(session_id, fn s -> s.counter.count end)
    ```
+
+7. **Unmatched Action Handling**:
+   ```elixir
+   # Default behavior: logs debug message for unmatched actions
+   def handle_action(action, state) do
+     case action do
+       %Action{type: "known"} -> # handle action
+       _ -> handle_unmatched_action(action, state)  # Logs debug message
+     end
+   end
+
+   # Override to customize behavior
+   def handle_unmatched_action(action, state) do
+     # Custom logic, e.g., track unmatched actions
+     MyApp.Metrics.track_unmatched(action)
+     state
+   end
+
+   # Or configure globally
+   config :phoenix_session_process,
+     unmatched_action_handler: :warn  # :log | :warn | :silent | custom function
+   ```

lib/phoenix/session_process.ex

@@ -1034,14 +1034,96 @@ defmodule Phoenix.SessionProcess do
             %{state | data: data, priority: priority}
           end
       """
-      def handle_action(_action, state), do: state
+      def handle_action(action, state) do
+        handle_unmatched_action(action, state)
+      end
+
+      @doc """
+      Handle unmatched actions.
+
+      This callback is called when an action doesn't match any pattern in `handle_action/2`.
+      Override this to customize behavior for unmatched actions.
+
+      ## Parameters
+
+      - `action` - The unmatched action (Action struct)
+      - `state` - The current state slice for this reducer
+
+      ## Returns
+
+      - `state` - The state (unchanged by default)
+
+      ## Default Behavior
+
+      The default implementation logs a debug message based on the global
+      `unmatched_action_handler` configuration and returns the state unchanged.
+
+      ## Examples
+
+          # Custom handler that logs at info level
+          def handle_unmatched_action(action, state) do
+            require Logger
+            Logger.info("MyReducer ignored action: \#{action.type}")
+            state
+          end
+
+          # Custom handler that tracks metrics
+          def handle_unmatched_action(action, state) do
+            MyApp.Metrics.increment("reducer.unmatched_actions", tags: [reducer: :my_reducer])
+            state
+          end
+
+          # Silent handler
+          def handle_unmatched_action(_action, state), do: state
+      """
+      def handle_unmatched_action(action, state) do
+        require Logger
+        reducer_module = __MODULE__
+        reducer_name = __MODULE__.__reducer_name__()
+        handler = Phoenix.SessionProcess.Config.unmatched_action_handler()
+
+        case handler do
+          :log ->
+            Logger.debug("""
+            Reducer #{inspect(reducer_name)} (#{inspect(reducer_module)}) received unmatched action: #{inspect(action.type)}.
+            Consider using @action_prefix to limit which actions are routed to this reducer.
+            """)
+
+          :warn ->
+            Logger.warning("""
+            Reducer #{inspect(reducer_name)} (#{inspect(reducer_module)}) received unmatched action: #{inspect(action.type)}.
+            Consider using @action_prefix to limit which actions are routed to this reducer.
+            """)
+
+          :silent ->
+            :ok
+
+          handler when is_function(handler, 3) ->
+            handler.(action, reducer_module, reducer_name)
+
+          _ ->
+            Logger.warning(
+              "Invalid unmatched_action_handler configuration: #{inspect(handler)}. " <>
+                "Expected :log, :warn, :silent, or function/3"
+            )
+        end
+
+        state
+      end
 
       @doc """
       Handle asynchronous actions with dispatch callback.
 
       Override this function for actions that require async operations.
       The dispatch callback allows you to dispatch new actions from async context.
 
+      **Note**: If you define `handle_async/3`, you should include a catch-all clause
+      that delegates to `handle_unmatched_async/3` for actions you don't handle:
+
+          def handle_async(action, dispatch, state) do
+            handle_unmatched_async(action, dispatch, state)
+          end
+
       ## Parameters
 
       - `action` - The action to process (Action struct)
@@ -1054,7 +1136,6 @@ defmodule Phoenix.SessionProcess do
       ## Returns
 
       - `cancel_fn` - A cancellation function `(() -> any())` that will be called if the action needs to be cancelled
-      - Default implementation returns `fn -> nil end` (no-op cancellation)
 
       ## Examples
 
@@ -1071,7 +1152,7 @@ defmodule Phoenix.SessionProcess do
             fn -> Task.shutdown(task, :brutal_kill) end
           end
 
-          # With meta
+          # With catch-all for unmatched actions
           def handle_async(%Action{type: "load_data"}, dispatch, state) do
             task = Task.async(fn ->
               data = API.load_data()
@@ -1081,18 +1162,84 @@ defmodule Phoenix.SessionProcess do
             fn -> Task.shutdown(task, :brutal_kill) end
           end
 
-          # Simple case: no cancellation needed
-          def handle_async(%Action{type: "log", payload: msg}, _dispatch, _state) do
-            Logger.info(msg)
+          def handle_async(action, dispatch, state) do
+            # Delegate unmatched async actions to default handler
+            handle_unmatched_async(action, dispatch, state)
+          end
+      """
+
+      @doc """
+      Handle unmatched asynchronous actions.
+
+      This callback is called when an async action doesn't match any pattern in `handle_async/3`.
+      Override this to customize behavior for unmatched async actions.
+
+      ## Parameters
+
+      - `action` - The unmatched action (Action struct)
+      - `dispatch` - Callback function to dispatch new actions
+      - `state` - The current state slice for this reducer
+
+      ## Returns
+
+      - `cancel_fn` - A no-op cancellation function `(() -> nil)` (default)
+
+      ## Default Behavior
+
+      The default implementation logs a debug message and returns a no-op cancel function.
+
+      ## Examples
+
+          # Custom handler that logs
+          def handle_unmatched_async(action, _dispatch, _state) do
+            require Logger
+            Logger.info("MyReducer ignored async action: \#{action.type}")
+            fn -> nil end
+          end
+
+          # Silent handler
+          def handle_unmatched_async(_action, _dispatch, _state) do
             fn -> nil end
           end
       """
+      def handle_unmatched_async(action, _dispatch, state) do
+        require Logger
+        reducer_module = __MODULE__
+        reducer_name = __MODULE__.__reducer_name__()
+        handler = Phoenix.SessionProcess.Config.unmatched_action_handler()
+
+        case handler do
+          :log ->
+            Logger.debug("""
+            Reducer #{inspect(reducer_name)} (#{inspect(reducer_module)}) received unmatched async action: #{inspect(action.type)}.
+            Consider using @action_prefix to limit which actions are routed to this reducer.
+            """)
+
+          :warn ->
+            Logger.warning("""
+            Reducer #{inspect(reducer_name)} (#{inspect(reducer_module)}) received unmatched async action: #{inspect(action.type)}.
+            Consider using @action_prefix to limit which actions are routed to this reducer.
+            """)
+
+          :silent ->
+            :ok
+
+          handler when is_function(handler, 3) ->
+            handler.(action, reducer_module, reducer_name)
+
+          _ ->
+            :ok
+        end
+
+        fn -> nil end
+      end
 
       # NOTE: No default implementation for handle_async/3
       # Only export handle_async/3 if explicitly defined by the reducer
       # This ensures function_exported?(module, :handle_async, 3) accurately reflects intent
 
-      defoverridable init_state: 0, handle_action: 2
+      defoverridable init_state: 0, handle_action: 2, handle_unmatched_action: 2,
+                     handle_unmatched_async: 3
     end
   end
 

lib/phoenix/session_process/config.ex

@@ -15,7 +15,8 @@ defmodule Phoenix.SessionProcess.Config do
     session_process: MyApp.SessionProcess,  # Default session module
     max_sessions: 10_000,                   # Maximum concurrent sessions
     session_ttl: 3_600_000,                # Session TTL in milliseconds (1 hour)
-    rate_limit: 100                        # Sessions per minute limit
+    rate_limit: 100,                       # Sessions per minute limit
+    unmatched_action_handler: :log         # How to handle unmatched actions (:log, :warn, :silent, or custom function)
   ```
 
   ## Options
@@ -40,6 +41,15 @@ defmodule Phoenix.SessionProcess.Config do
   - **Default**: `100`
   - **Description**: Maximum number of new sessions that can be created per minute. Prevents abuse.
 
+  ### `:unmatched_action_handler`
+  - **Type**: `:log | :warn | :silent | (action, reducer_module, reducer_name -> any())`
+  - **Default**: `:log`
+  - **Description**: How to handle actions that don't match any pattern in a reducer's `handle_action/2`:
+    - `:log` - Log debug message suggesting use of action prefix
+    - `:warn` - Log warning message (useful for debugging)
+    - `:silent` - No logging
+    - Custom function with arity 3: `fun(action, reducer_module, reducer_name)`
+
   ## Runtime Configuration
 
   Configuration can be provided in two ways:
@@ -89,6 +99,7 @@ defmodule Phoenix.SessionProcess.Config do
   @default_session_ttl 3_600_000
   # sessions per minute
   @default_rate_limit 100
+  @default_unmatched_action_handler :log
 
   @doc """
   Returns the configured default session process module.
@@ -204,6 +215,44 @@ defmodule Phoenix.SessionProcess.Config do
     get_config(:rate_limit, @default_rate_limit)
   end
 
+  @doc """
+  Returns the handler for unmatched actions in reducers.
+
+  ## Examples
+
+      iex> Phoenix.SessionProcess.Config.unmatched_action_handler()
+      :log
+
+  ## Returns
+
+  - `:log` - Log debug messages for unmatched actions (default)
+  - `:warn` - Log warning messages for unmatched actions
+  - `:silent` - No logging
+  - `function/3` - Custom handler function with signature: `fun(action, reducer_module, reducer_name)`
+
+  ## Configuration
+
+  Set in your config file:
+
+      config :phoenix_session_process,
+        unmatched_action_handler: :warn
+
+      # Or with custom function:
+      config :phoenix_session_process,
+        unmatched_action_handler: fn action, module, name ->
+          MyApp.Metrics.track_unmatched_action(action, module, name)
+        end
+
+  ## Note
+
+  This helps debug action routing issues. If you see many unmatched actions,
+  consider using `@action_prefix` to limit which actions are routed to each reducer.
+  """
+  @spec unmatched_action_handler :: :log | :warn | :silent | function()
+  def unmatched_action_handler do
+    get_config(:unmatched_action_handler, @default_unmatched_action_handler)
+  end
+
   @doc """
   Validates whether a session ID has the correct format.