TemporalEx.Error (temporal_ex v0.2.1)

Copy Markdown

Structured error types for Temporal RPC failures.

Parses gRPC error responses into specific error structs so callers can pattern-match on the failure type.

Classification strategy (in order):

  1. Typed error details — Temporal emits structured failure messages (e.g. WorkflowExecutionAlreadyStartedFailure, NamespaceNotFoundFailure) in the gRPC error's details list. When present, they give an unambiguous answer.

  2. Caller-supplied :context — each TemporalEx call site knows whether it just invoked a workflow or schedule RPC, so it passes context: :workflow or context: :schedule. This disambiguates status codes (ALREADY_EXISTS, NOT_FOUND) that aren't covered by a typed detail.

  3. Generic RPCError — when neither signal is available, the error is returned as a generic RPCError rather than guessing based on the free-form message text (which can embed user-controlled values).

Summary

Types

context()
t()

Functions

from_rpc_error(error, opts \\ [])

Converts a gRPC error into a typed TemporalEx.Error struct.

Types

context()

@type context() :: :workflow | :schedule | nil

t()

@type t() ::
  %TemporalEx.Error.WorkflowAlreadyStarted{
    message: term(),
    run_id: term(),
    workflow_id: term()
  }
  | %TemporalEx.Error.WorkflowNotFound{
      message: term(),
      run_id: term(),
      workflow_id: term()
    }
  | %TemporalEx.Error.ScheduleAlreadyExists{
      message: term(),
      schedule_id: term()
    }
  | %TemporalEx.Error.ScheduleNotFound{message: term(), schedule_id: term()}
  | %TemporalEx.Error.NamespaceNotFound{message: term(), namespace: term()}
  | %TemporalEx.Error.QueryFailed{message: term()}
  | %TemporalEx.Error.RPCError{code: term(), details: term(), message: term()}

Functions

from_rpc_error(error, opts \\ [])

@spec from_rpc_error(
  term(),
  keyword()
) :: t()

Converts a gRPC error into a typed TemporalEx.Error struct.

Accepts GRPC.RPCError structs or {:error, reason} tuples.

Options

  • :context — caller operation kind, one of :workflow, :schedule, or nil (default). Used to disambiguate ALREADY_EXISTS / NOT_FOUND status codes when the gRPC error carries no typed detail.