refactor: simplify start_session API to 2 arities with keyword options

Simplified start_session from 3 arities to 2 arities using keyword options
for a cleaner, more flexible API.

Changes:
- start_session/2 now accepts keyword options: module:, args:
- Removed start_session/3
- Updated deprecation functions to use new options format
- Updated all test files to use new API
- Updated helpers to build keyword options dynamically

Examples:
  start_session(id, module: Mod, args: args)
  start_session(id, args: %{user_id: 123})

Breaking: start_session/3 removed (use start_session/2 with options)
All 148 tests pass.

Author: GSMLG-BOT

README.md

@@ -595,10 +595,6 @@ mix run bench/session_benchmark.exs
 
 See `bench/README.md` for detailed benchmarking guide and customization options.
 
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
 ### Development Setup
 
 1. Fork the repository

lib/phoenix/session_process.ex

@@ -231,23 +231,15 @@ defmodule Phoenix.SessionProcess do
   defdelegate start_session(session_id), to: Phoenix.SessionProcess.ProcessSupervisor
 
   @doc """
-  Deprecated: Use `start_session/1` instead.
+  Starts a session process with options.
 
-  This function is kept for backward compatibility but will be removed in a future version.
-  """
-  @deprecated "Use start_session/1 instead"
-  @spec start(binary()) :: {:ok, pid()} | {:error, term()}
-  def start(session_id), do: start_session(session_id)
-
-  @doc """
-  Starts a session process using a custom module.
-
-  This allows you to use a specific session process implementation instead of
-  the default configured module.
+  This allows you to customize the module and initialization arguments.
 
   ## Parameters
   - `session_id` - Unique binary identifier for the session
-  - `module` - Module implementing the session process behavior
+  - `opts` - Keyword list of options:
+    - `:module` - Module implementing the session process behavior (defaults to configured module)
+    - `:args` - Initialization arguments passed to `init/1` (defaults to nil)
 
   ## Returns
   - `{:ok, pid}` - Session process started successfully
@@ -257,71 +249,69 @@ defmodule Phoenix.SessionProcess do
 
   ## Examples
 
-      {:ok, pid} = Phoenix.SessionProcess.start_session("user_123", MyApp.CustomSessionProcess)
+      # Use default module
+      {:ok, pid} = Phoenix.SessionProcess.start_session("user_123")
+
+      # Use custom module
+      {:ok, pid} = Phoenix.SessionProcess.start_session("user_123", module: MyApp.CustomSessionProcess)
 
-      iex> result = Phoenix.SessionProcess.start_session("valid_session", Phoenix.SessionProcess.DefaultSessionProcess)
+      # Use custom module with initialization arguments
+      {:ok, pid} = Phoenix.SessionProcess.start_session("user_123",
+        module: MyApp.SessionProcess,
+        args: %{user_id: 123})
+
+      # Use default module with initialization arguments
+      {:ok, pid} = Phoenix.SessionProcess.start_session("user_456", args: [debug: true])
+
+      iex> result = Phoenix.SessionProcess.start_session("valid_session", module: Phoenix.SessionProcess.DefaultSessionProcess)
       iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
       true
 
-      iex> Phoenix.SessionProcess.start_session("invalid@session", Phoenix.SessionProcess.DefaultSessionProcess)
-      {:error, {:invalid_session_id, "invalid@session"}}
+      iex> result = Phoenix.SessionProcess.start_session("valid_with_args", module: Phoenix.SessionProcess.DefaultSessionProcess, args: %{user_id: 123})
+      iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
+      true
   """
-  @spec start_session(binary(), atom()) :: {:ok, pid()} | {:error, term()}
-  defdelegate start_session(session_id, module), to: Phoenix.SessionProcess.ProcessSupervisor
+  @spec start_session(binary(), keyword()) :: {:ok, pid()} | {:error, term()}
+  defdelegate start_session(session_id, opts), to: Phoenix.SessionProcess.ProcessSupervisor
 
   @doc """
-  Deprecated: Use `start_session/2` instead.
+  Deprecated: Use `start_session/1` instead.
 
   This function is kept for backward compatibility but will be removed in a future version.
   """
-  @deprecated "Use start_session/2 instead"
-  @spec start(binary(), atom()) :: {:ok, pid()} | {:error, term()}
-  def start(session_id, module), do: start_session(session_id, module)
+  @deprecated "Use start_session/1 instead"
+  @spec start(binary()) :: {:ok, pid()} | {:error, term()}
+  def start(session_id), do: start_session(session_id)
 
   @doc """
-  Starts a session process with a custom module and initialization arguments.
+  Deprecated: Use `start_session/2` with options instead.
 
-  The initialization arguments are passed to the module's `init/1` callback,
-  allowing you to set up initial state or configuration.
+  ## Migration
 
-  ## Parameters
-  - `session_id` - Unique binary identifier for the session
-  - `module` - Module implementing the session process behavior
-  - `arg` - Initialization argument(s) passed to `init/1`
-
-  ## Returns
-  - `{:ok, pid}` - Session process started successfully
-  - `{:error, {:already_started, pid}}` - Session already exists
-  - `{:error, {:invalid_session_id, id}}` - Invalid session ID format
-  - `{:error, {:session_limit_reached, max}}` - Maximum sessions exceeded
-
-  ## Examples
-
-      # With map argument
-      {:ok, pid} = Phoenix.SessionProcess.start_session("user_123", MyApp.SessionProcess, %{user_id: 123})
+      # Old
+      start(session_id, MyModule)
 
-      # With keyword list
-      {:ok, pid} = Phoenix.SessionProcess.start_session("user_456", MyApp.SessionProcess, [debug: true])
-
-      iex> result = Phoenix.SessionProcess.start_session("valid_session_with_args", Phoenix.SessionProcess.DefaultSessionProcess, %{user_id: 123})
-      iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
-      true
-
-      iex> result = Phoenix.SessionProcess.start_session("valid_session_with_list", Phoenix.SessionProcess.DefaultSessionProcess, [debug: true])
-      iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
-      true
+      # New
+      start_session(session_id, module: MyModule)
   """
-  @spec start_session(binary(), atom(), any()) :: {:ok, pid()} | {:error, term()}
-  defdelegate start_session(session_id, module, arg), to: Phoenix.SessionProcess.ProcessSupervisor
+  @deprecated "Use start_session/2 with module: option instead"
+  @spec start(binary(), atom()) :: {:ok, pid()} | {:error, term()}
+  def start(session_id, module), do: start_session(session_id, module: module)
 
   @doc """
-  Deprecated: Use `start_session/3` instead.
+  Deprecated: Use `start_session/2` with options instead.
 
-  This function is kept for backward compatibility but will be removed in a future version.
+  ## Migration
+
+      # Old
+      start(session_id, MyModule, args)
+
+      # New
+      start_session(session_id, module: MyModule, args: args)
   """
-  @deprecated "Use start_session/3 instead"
+  @deprecated "Use start_session/2 with module: and args: options instead"
   @spec start(binary(), atom(), any()) :: {:ok, pid()} | {:error, term()}
-  def start(session_id, module, arg), do: start_session(session_id, module, arg)
+  def start(session_id, module, arg), do: start_session(session_id, module: module, args: arg)
 
   @doc """
   Checks if a session process is currently running.

lib/phoenix/session_process/helpers.ex

@@ -156,15 +156,18 @@ defmodule Phoenix.SessionProcess.Helpers do
   end
 
   defp do_create_session_with_retry(session_id, module, arg, retries) do
+    # Build options for start_session/2
+    opts =
+      []
+      |> Keyword.put_new_lazy(:module, fn -> module end)
+      |> Keyword.put_new_lazy(:args, fn -> arg end)
+      |> Enum.reject(fn {_k, v} -> is_nil(v) end)
+
     result =
-      if module do
-        if arg do
-          SessionProcess.start_session(session_id, module, arg)
-        else
-          SessionProcess.start_session(session_id, module)
-        end
-      else
+      if opts == [] do
         SessionProcess.start_session(session_id)
+      else
+        SessionProcess.start_session(session_id, opts)
       end
 
     case result do

lib/phoenix/session_process/process_superviser.ex

@@ -181,38 +181,43 @@ defmodule Phoenix.SessionProcess.ProcessSupervisor do
   end
 
   @doc """
-  Starts a session process using a specific module.
+  Starts a session process with options.
 
   ## Parameters
 
   - `session_id` - Unique identifier for the session
-  - `module` - Session process module to use
+  - `opts` - Keyword list of options:
+    - `:module` - Session process module to use (defaults to configured module)
+    - `:args` - Initialization arguments passed to `init/1` (defaults to nil)
 
   ## Returns
 
   - `{:ok, pid()}` - Session process started successfully
   - `{:error, reason}` - Failed to start session process
-  """
-  def start_session(session_id, module) do
-    start_session_with_module(session_id, module)
-  end
 
-  @doc """
-  Starts a session process using a specific module with initialization arguments.
+  ## Examples
 
-  ## Parameters
+      # Use default module with no args
+      start_session("session_123")
 
-  - `session_id` - Unique identifier for the session
-  - `module` - Session process module to use
-  - `arg` - Initialization arguments for the session process
+      # Use custom module with default args
+      start_session("session_123", module: MyApp.SessionProcess)
 
-  ## Returns
+      # Use custom module with custom args
+      start_session("session_123", module: MyApp.SessionProcess, args: %{user_id: 123})
 
-  - `{:ok, pid()}` - Session process started successfully
-  - `{:error, reason}` - Failed to start session process
+      # Use default module with custom args
+      start_session("session_123", args: %{user_id: 123})
   """
-  def start_session(session_id, module, arg) do
-    start_session_with_module(session_id, module, arg)
+  def start_session(session_id, opts) when is_list(opts) do
+    module = Keyword.get(opts, :module, Config.session_process())
+    args = Keyword.get(opts, :args)
+    start_session_with_module(session_id, module, args)
+  end
+
+  # Backward compatibility for old 2-arity call with module atom
+  def start_session(session_id, module) when is_atom(module) do
+    start_session_with_module(session_id, module)
   end
 
   @doc """

test/phoenix/session_process/integration_test.exs

@@ -46,7 +46,7 @@ defmodule Phoenix.SessionProcess.IntegrationTest do
 
     # Start with custom module
     assert {:ok, _pid} =
-             SessionProcess.start_session(session_id, TestCustomSession, %{test: "data"})
+             SessionProcess.start_session(session_id, module: TestCustomSession, args: %{test: "data"})
 
     # Verify custom initialization worked
     assert %{custom: true} = SessionProcess.call(session_id, :get_state)

test/phoenix/session_process/macro_consistency_test.exs

@@ -32,7 +32,7 @@ defmodule Phoenix.SessionProcess.MacroConsistencyTest do
       session_id = "test_process_with_arg_#{:rand.uniform(10000)}"
       init_arg = %{user_id: 123, data: "test"}
 
-      {:ok, _pid} = SessionProcess.start_session(session_id, TestProcessWithArg, init_arg)
+      {:ok, _pid} = SessionProcess.start_session(session_id, module: TestProcessWithArg, args: init_arg)
 
       state = SessionProcess.call(session_id, :get_state)
       assert state.initialized_with == init_arg
@@ -44,7 +44,7 @@ defmodule Phoenix.SessionProcess.MacroConsistencyTest do
       session_id = "test_process_with_arg_#{:rand.uniform(10000)}"
       init_arg = %{user_id: 456, data: "test"}
 
-      {:ok, _pid} = SessionProcess.start_session(session_id, TestProcessLinkWithArg, init_arg)
+      {:ok, _pid} = SessionProcess.start_session(session_id, module: TestProcessLinkWithArg, args: init_arg)
 
       state = SessionProcess.call(session_id, :get_state)
       assert state.initialized_with == init_arg
@@ -61,8 +61,8 @@ defmodule Phoenix.SessionProcess.MacroConsistencyTest do
       init_arg = %{value: 42}
 
       # Both should accept the same argument format
-      {:ok, _} = SessionProcess.start_session(session_id_1, TestProcessWithArg, init_arg)
-      {:ok, _} = SessionProcess.start_session(session_id_2, TestProcessLinkWithArg, init_arg)
+      {:ok, _} = SessionProcess.start_session(session_id_1, module: TestProcessWithArg, args: init_arg)
+      {:ok, _} = SessionProcess.start_session(session_id_2, module: TestProcessLinkWithArg, args: init_arg)
 
       state1 = SessionProcess.call(session_id_1, :get_state)
       state2 = SessionProcess.call(session_id_2, :get_state)

test/phoenix/session_process_test.exs

@@ -28,28 +28,28 @@ defmodule Phoenix.SessionProcessTest do
   test "test start session process" do
     session_id = SessionId.generate_unique_session_id()
     assert SessionProcess.started?(session_id) == false
-    {:ok, pid} = SessionProcess.start_session(session_id, TestProcess, %{value: 0})
+    {:ok, pid} = SessionProcess.start_session(session_id, module: TestProcess, args: %{value: 0})
     assert is_pid(pid)
     assert SessionProcess.started?(session_id) == true
   end
 
   test "test terminate session process" do
     session_id = SessionId.generate_unique_session_id()
-    {:ok, _pid} = SessionProcess.start_session(session_id, TestProcess, %{value: 0})
+    {:ok, _pid} = SessionProcess.start_session(session_id, module: TestProcess, args: %{value: 0})
     assert SessionProcess.started?(session_id) == true
     SessionProcess.terminate(session_id)
     assert SessionProcess.started?(session_id) == false
   end
 
   test "test call on session process" do
     session_id = SessionId.generate_unique_session_id()
-    {:ok, _pid} = SessionProcess.start_session(session_id, TestProcess, %{value: 123})
+    {:ok, _pid} = SessionProcess.start_session(session_id, module: TestProcess, args: %{value: 123})
     assert SessionProcess.call(session_id, :get_value) == 123
   end
 
   test "test cast on session process" do
     session_id = SessionId.generate_unique_session_id()
-    {:ok, _pid} = SessionProcess.start_session(session_id, TestProcess, %{value: 0})
+    {:ok, _pid} = SessionProcess.start_session(session_id, module: TestProcess, args: %{value: 0})
     assert SessionProcess.call(session_id, :get_value) == 0
     SessionProcess.cast(session_id, :add_one)
     assert SessionProcess.call(session_id, :get_value) == 1
@@ -64,8 +64,8 @@ defmodule Phoenix.SessionProcessTest do
       session_id1 = SessionId.generate_unique_session_id()
       session_id2 = SessionId.generate_unique_session_id()
 
-      {:ok, pid1} = SessionProcess.start_session(session_id1, TestProcess, %{value: 1})
-      {:ok, pid2} = SessionProcess.start_session(session_id2, TestProcess, %{value: 2})
+      {:ok, pid1} = SessionProcess.start_session(session_id1, module: TestProcess, args: %{value: 1})
+      {:ok, pid2} = SessionProcess.start_session(session_id2, module: TestProcess, args: %{value: 2})
 
       sessions = SessionProcess.list_session()
       # Check that our created sessions are in the list
@@ -79,7 +79,7 @@ defmodule Phoenix.SessionProcessTest do
 
     test "removes session when terminated" do
       session_id = SessionId.generate_unique_session_id()
-      {:ok, pid} = SessionProcess.start_session(session_id, TestProcess, %{value: 0})
+      {:ok, pid} = SessionProcess.start_session(session_id, module: TestProcess, args: %{value: 0})
 
       # Check session exists in list
       sessions_before = SessionProcess.list_session()
@@ -101,8 +101,8 @@ defmodule Phoenix.SessionProcessTest do
       session_id1 = SessionId.generate_unique_session_id()
       session_id2 = SessionId.generate_unique_session_id()
 
-      {:ok, _pid1} = SessionProcess.start_session(session_id1, TestProcess, %{value: 1})
-      {:ok, _pid2} = SessionProcess.start_session(session_id2, TestProcess, %{value: 2})
+      {:ok, _pid1} = SessionProcess.start_session(session_id1, module: TestProcess, args: %{value: 1})
+      {:ok, _pid2} = SessionProcess.start_session(session_id2, module: TestProcess, args: %{value: 2})
 
       sessions = SessionProcess.list_sessions_by_module(TestProcess)
       # Check that our created sessions are in the list
@@ -118,10 +118,10 @@ defmodule Phoenix.SessionProcessTest do
       session_id1 = SessionId.generate_unique_session_id()
       session_id2 = SessionId.generate_unique_session_id()
 
-      {:ok, _pid1} = SessionProcess.start_session(session_id1, TestProcess, %{value: 1})
+      {:ok, _pid1} = SessionProcess.start_session(session_id1, module: TestProcess, args: %{value: 1})
 
       {:ok, _pid2} =
-        SessionProcess.start_session(session_id2, TestProcessLink, %{value: 2})
+        SessionProcess.start_session(session_id2, module: TestProcessLink, args: %{value: 2})
 
       test_sessions = SessionProcess.list_sessions_by_module(TestProcess)
       link_sessions = SessionProcess.list_sessions_by_module(TestProcessLink)
@@ -152,10 +152,10 @@ defmodule Phoenix.SessionProcessTest do
       session_id1 = SessionId.generate_unique_session_id()
       session_id2 = SessionId.generate_unique_session_id()
 
-      {:ok, _pid1} = SessionProcess.start_session(session_id1, TestProcess, %{value: 1})
+      {:ok, _pid1} = SessionProcess.start_session(session_id1, module: TestProcess, args: %{value: 1})
 
       {:ok, _pid2} =
-        SessionProcess.start_session(session_id2, TestProcessLink, %{value: 2})
+        SessionProcess.start_session(session_id2, module: TestProcessLink, args: %{value: 2})
 
       info = SessionProcess.session_info()
       # Check that both modules are in the list
@@ -173,7 +173,7 @@ defmodule Phoenix.SessionProcessTest do
   describe "get_session_id/0 in :process macro" do
     test "returns correct session_id from within session process" do
       session_id = SessionId.generate_unique_session_id()
-      {:ok, _pid} = SessionProcess.start_session(session_id, TestProcess, %{value: 0})
+      {:ok, _pid} = SessionProcess.start_session(session_id, module: TestProcess, args: %{value: 0})
 
       # Call a function that uses get_session_id internally
       result = SessionProcess.call(session_id, :get_my_session_id)
@@ -184,7 +184,7 @@ defmodule Phoenix.SessionProcessTest do
   describe "get_session_id/0 with LiveView monitoring" do
     test "returns correct session_id from within session process" do
       session_id = SessionId.generate_unique_session_id()
-      {:ok, _pid} = SessionProcess.start_session(session_id, TestProcessLink, %{value: 0})
+      {:ok, _pid} = SessionProcess.start_session(session_id, module: TestProcessLink, args: %{value: 0})
 
       result = SessionProcess.call(session_id, :get_my_session_id)
       assert result == session_id