defmodule OnePiece.Commanded.Helpers do
@moduledoc """
A Swiss Army Knife Helper Module.
"""
alias Commanded.Event.FailureContext
@type error_context :: FailureContext.t() | map()
@type commanded_dispatch_response ::
:ok
| {:ok, aggregate_state :: struct()}
| {:ok, aggregate_version :: non_neg_integer()}
| {:ok, execution_result :: Commanded.Commands.ExecutionResult.t()}
| {:error, :unregistered_command}
| {:error, :consistency_timeout}
| {:error, reason :: term()}
@doc """
Deprecated, it has the same behavior as `OnePiece.Commanded.Id.new/0`.
"""
@spec generate_uuid :: String.t()
@deprecated "Use `OnePiece.Commanded.Id.new/0` instead."
defdelegate generate_uuid, to: OnePiece.Commanded.Id, as: :new
@doc """
Transforms the given `source` map or struct into the `target` struct.
"""
@spec struct_from(source :: struct(), target :: struct()) :: struct()
def struct_from(%_{} = source, target) do
struct(target, Map.from_struct(source))
end
@spec struct_from(attrs :: map(), target :: module()) :: struct()
def struct_from(attrs, target) do
struct(target, attrs)
end
@doc false
@spec defines_struct?(mod :: module()) :: boolean()
def defines_struct?(mod) do
:functions
|> mod.__info__()
|> Keyword.get(:__struct__)
|> Kernel.!=(nil)
end
@doc """
Copy the information from the `source` map into the given `target` map.
iex> OnePiece.Commanded.Helpers.cast_to(%{}, %{name: "ubi-wan", last_name: "kenobi"}, [:last_name])
%{last_name: "kenobi"}
"""
@spec cast_to(target :: map, source :: map, keys :: [Map.key()]) :: map
def cast_to(target, source, keys) do
Map.merge(target, Map.take(source, keys))
end
@doc """
Returns a keyword list containing the "correlation id" and "causation id" tracing.
iex> OnePiece.Commanded.Helpers.tracing_from_metadata(%{
...> event_id: "26eb06fe-9ba6-4f58-a2dd-2bdba73de4f2",
...> correlation_id: "f634ba94-145c-4fa7-bf7f-0d73dd83b446"
...> })
...>
[causation_id: "26eb06fe-9ba6-4f58-a2dd-2bdba73de4f2", correlation_id: "f634ba94-145c-4fa7-bf7f-0d73dd83b446"]
Useful when dispatching commands to copy-forward `t:Commanded.Event.Handler.metadata/0` tracing information.
defmodule MyProcessor do
application: MyApp,
use Commanded.Event.Handler,
name: "my_processor"
alias OnePiece.Commanded.Helpers
def handle(%MyEvent{} = event, metadata) do
MyApp.dispatch(
%MyCommand{},
# copy-forward the information
Helpers.tracing_from_metadata(metadata)
)
end
end
"""
@spec tracing_from_metadata(metadata :: Commanded.Event.Handler.metadata()) :: [
causation_id: String.t(),
correlation_id: String.t()
]
def tracing_from_metadata(metadata) do
[causation_id: metadata.event_id, correlation_id: metadata.correlation_id]
end
@doc """
Adds the "correlation id" and "causation id" tracing to an existing keyword list configuration option.
iex> OnePiece.Commanded.Helpers.tracing_from_metadata([timeout: 30_000], %{
...> event_id: "26eb06fe-9ba6-4f58-a2dd-2bdba73de4f2",
...> correlation_id: "f634ba94-145c-4fa7-bf7f-0d73dd83b446"
...> })
...>
[timeout: 30_000, causation_id: "26eb06fe-9ba6-4f58-a2dd-2bdba73de4f2", correlation_id: "f634ba94-145c-4fa7-bf7f-0d73dd83b446"]
Useful when dispatching commands to copy-forward the `t:Commanded.Event.Handler.metadata/0` tracing information and
wants to also add other keyword list options.
defmodule MyProcessor do
use Commanded.Event.Handler,
application: MyApp,
name: "my_processor"
alias OnePiece.Commanded.Helpers
def handle(%MyEvent{} = event, metadata) do
MyApp.dispatch(
%MyCommand{},
# copy-forward the information
Helpers.tracing_from_metadata([timeout: 30_000], metadata)
)
end
end
"""
@spec tracing_from_metadata(opts :: keyword, metadata :: Commanded.Event.Handler.metadata()) :: [
causation_id: String.t(),
correlation_id: String.t()
]
def tracing_from_metadata(opts, metadata) do
Keyword.merge(opts, tracing_from_metadata(metadata))
end
@doc """
Returns `skip` or a `retry` response.
When the `c:Commanded.Application.dispatch/1` or `c:Commanded.Application.dispatch/2` returns an `:skip` otherwise,
returns a `:retry` response. Useful when you are doing error handling in your `c:Commanded.Event.Handler.error/3`.
iex> success_dispatch = fn _ -> :ok end
...> OnePiece.Commanded.Helpers.skip_or_retry(success_dispatch.(%{}), %{})
:skip
iex> success_dispatch = fn _ -> {:ok, %{}} end
...> OnePiece.Commanded.Helpers.skip_or_retry(success_dispatch.(%{}), %{})
:skip
iex> failure_dispatch = fn _ -> {:error, :ooops} end
...> OnePiece.Commanded.Helpers.skip_or_retry(failure_dispatch.(%{}), %{failures: 1})
{:retry, %{failures: 1}}
"""
@spec skip_or_retry(tuple_response :: commanded_dispatch_response, context :: error_context) ::
:skip | {:retry, error_context}
def skip_or_retry(:ok, _context), do: :skip
def skip_or_retry({:ok, _}, _context), do: :skip
def skip_or_retry(_, context), do: {:retry, context}
@doc """
Returns `skip` or a `retry` response with a given delay.
When the `c:Commanded.Application.dispatch/1` or `c:Commanded.Application.dispatch/2` returns an `:skip` otherwise,
returns a `:retry` response. Useful when you are doing error handling in your `c:Commanded.Event.Handler.error/3`.
iex> success_dispatch = fn _ -> :ok end
...> OnePiece.Commanded.Helpers.skip_or_retry(success_dispatch.(%{}), 5_000, %{})
:skip
iex> success_dispatch = fn _ -> {:ok, %{}} end
...> OnePiece.Commanded.Helpers.skip_or_retry(success_dispatch.(%{}), 5_000, %{})
:skip
iex> failure_dispatch = fn _ -> {:error, :ooops} end
...> OnePiece.Commanded.Helpers.skip_or_retry(failure_dispatch.(%{}), 5_000, %{failures: 1})
{:retry, 5_000, %{failures: 1}}
"""
@spec skip_or_retry(
tuple_response :: commanded_dispatch_response,
delay :: non_neg_integer(),
context :: error_context
) ::
:skip | {:retry, non_neg_integer(), error_context}
def skip_or_retry(:ok, _delay, _context), do: :skip
def skip_or_retry({:ok, _}, _delay, _context), do: :skip
def skip_or_retry(_, delay, context), do: {:retry, delay, context}
@doc """
Increase the failure counter from `t:Commanded.Event.FailureContext.t/0` context by one.
iex> OnePiece.Commanded.Helpers.increase_failure_counter(%Commanded.Event.FailureContext{context: %{failures_count: 1}})
%{failures_count: 2}
"""
@spec increase_failure_counter(failure_context :: FailureContext.t()) :: map()
def increase_failure_counter(%FailureContext{} = failure_context) do
Map.update(failure_context.context, :failures_count, 1, &(&1 + 1))
end
@doc """
Ignores a specific error from a command dispatch result.
This function takes a dispatch result and an error term. If the result represents an error that matches the provided
error term, the function returns `:ok`. Otherwise, it returns the original result.
This is useful when an error condition should be treated as a successful operation under specific circumstances.
## Examples
iex> OnePiece.Commanded.Helpers.ignore_error({:error, :idempotency_failure}, :idempotency_failure)
:ok
iex> OnePiece.Commanded.Helpers.ignore_error({:error, :something_went_wrong}, :idempotency_failure)
{:error, :something_went_wrong}
iex> OnePiece.Commanded.Helpers.ignore_error(:ok, :idempotency_failure)
:ok
iex> OnePiece.Commanded.Helpers.ignore_error({:ok, %{name: "Billy"}}, :idempotency_failure)
{:ok, %{name: "Billy"}}
"""
@spec ignore_error(result :: commanded_dispatch_response, error: any) :: commanded_dispatch_response
def ignore_error({:error, expected_error}, expected_error), do: :ok
def ignore_error(result, _expected_error), do: result
@doc false
def get_primary_key({identifier, identifier_type}) do
{identifier, identifier_type}
end
def get_primary_key(identifier) when is_atom(identifier) do
{identifier, :string}
end
end
