Orkestra.CommandEnvelope (orkestra v0.2.0)

Wraps a command with dispatch context: routing, retries, and lifecycle tracking.

The envelope is what the dispatcher and middleware operate on. The command itself is immutable once created; the envelope accumulates context as it flows through the pipeline.

Structure

%CommandEnvelope{
  command: %StartAssessment{...},
  status: :pending,
  dispatched_at: nil,
  completed_at: nil,
  result: nil,
  error: nil,
  attempts: 0,
  max_retries: 0,
  middleware_context: %{}
}

Summary

Types

status()

t()

Functions

command_id(command_envelope)

Returns the command id.

command_type(command_envelope)

Returns the command type.

get_context(env, key, default \\ nil)

Gets a value from the middleware context.

mark_dispatched(env)

Marks the envelope as dispatched.

mark_failed(env, error)

Marks the envelope as failed with an error.

mark_rejected(env, reason)

Marks the envelope as rejected (e.g. validation or authorization failure).

mark_succeeded(env, result)

Marks the envelope as succeeded with a result.

metadata(command_envelope)

Returns the command metadata.

put_context(env, key, value)

Stores a value in the middleware context.

retryable?(arg1)

Whether the envelope can be retried.

wrap(command, opts \\ [])

Wraps a command in an envelope.

Types

status()

@type status() :: :pending | :dispatched | :succeeded | :failed | :rejected

t()

@type t() :: %Orkestra.CommandEnvelope{
  attempts: non_neg_integer(),
  command: Orkestra.Command.t(),
  completed_at: DateTime.t() | nil,
  dispatched_at: DateTime.t() | nil,
  error: term(),
  max_retries: non_neg_integer(),
  middleware_context: map(),
  result: term(),
  status: status()
}

Functions

command_id(command_envelope)

@spec command_id(t()) :: String.t()

Returns the command id.

command_type(command_envelope)

@spec command_type(t()) :: String.t()

Returns the command type.

get_context(env, key, default \\ nil)

@spec get_context(t(), atom(), term()) :: term()

Gets a value from the middleware context.

mark_dispatched(env)

@spec mark_dispatched(t()) :: t()

Marks the envelope as dispatched.

mark_failed(env, error)

@spec mark_failed(t(), term()) :: t()

Marks the envelope as failed with an error.

mark_rejected(env, reason)

@spec mark_rejected(t(), term()) :: t()

Marks the envelope as rejected (e.g. validation or authorization failure).

mark_succeeded(env, result)

@spec mark_succeeded(t(), term()) :: t()

Marks the envelope as succeeded with a result.

metadata(command_envelope)

@spec metadata(t()) :: Orkestra.Metadata.t() | nil

Returns the command metadata.

put_context(env, key, value)

@spec put_context(t(), atom(), term()) :: t()

Stores a value in the middleware context.

retryable?(arg1)

@spec retryable?(t()) :: boolean()

Whether the envelope can be retried.

wrap(command, opts \\ [])

@spec wrap(
  Orkestra.Command.t(),
  keyword()
) :: t()

Wraps a command in an envelope.

Options

:max_retries — number of retry attempts on failure (default: 0)