fix(dispatch): reject invalid command UUID overrides

lib/application.ex

@@ -310,6 +310,9 @@ defmodule Commanded.Application do
         - `causation_id` - an optional UUID used to identify the cause of the
           command being dispatched.
 
+        - `command_uuid` - an optional UUID used to identify the command being
+          dispatched. When omitted, one will be generated automatically.
+
         - `correlation_id` - an optional UUID used to correlate related
           commands/events together.
 

lib/commanded/commands/router.ex

@@ -445,7 +445,7 @@ defmodule Commanded.Commands.Router do
           command being dispatched.
 
         - `command_uuid` - an optional UUID used to identify the command being
-          dispatched.
+          dispatched. When omitted, one will be generated automatically.
 
         - `correlation_id` - an optional UUID used to correlate related
           commands/events together.
@@ -546,7 +546,7 @@ defmodule Commanded.Commands.Router do
 
           application = Keyword.fetch!(opts, :application)
           causation_id = Keyword.get(opts, :causation_id)
-          command_uuid = Keyword.get_lazy(opts, :command_uuid, &UUID.uuid7/0)
+          command_uuid = Router.fetch_command_uuid(opts)
           consistency = Keyword.fetch!(opts, :consistency)
           correlation_id = Keyword.get_lazy(opts, :correlation_id, &UUID.uuid7/0)
           metadata = Keyword.fetch!(opts, :metadata) |> validate_metadata()
@@ -648,6 +648,20 @@ defmodule Commanded.Commands.Router do
     end
   end
 
+  @doc false
+  def fetch_command_uuid(opts) do
+    case Keyword.fetch(opts, :command_uuid) do
+      {:ok, value} when is_binary(value) ->
+        value
+
+      :error ->
+        UUID.uuid7()
+
+      _ ->
+        raise ArgumentError, message: "command_uuid must be a binary"
+    end
+  end
+
   @doc false
   def get_opt(opts, name, default \\ nil) do
     Keyword.get(opts, name) || Application.get_env(:commanded, name) || default

test/commands/command_identity_test.exs

@@ -27,5 +27,21 @@ defmodule Commanded.Commands.CommandIdentityTest do
       :ok = BankApp.dispatch(command, command_uuid: command_uuid)
       assert [^command_uuid] = CommandAuditMiddleware.dispatched_commands(& &1.command_uuid)
     end
+
+    test "should reject nil command_uuid" do
+      command = %OpenAccount{account_number: "ACC123", initial_balance: 1_000}
+
+      assert_raise ArgumentError, "command_uuid must be a binary", fn ->
+        BankApp.dispatch(command, command_uuid: nil)
+      end
+    end
+
+    test "should reject non-binary command_uuid" do
+      command = %OpenAccount{account_number: "ACC123", initial_balance: 1_000}
+
+      assert_raise ArgumentError, "command_uuid must be a binary", fn ->
+        BankApp.dispatch(command, command_uuid: 123)
+      end
+    end
   end
 end