Hourglass.WorkflowStatus (hourglass v0.1.0)

Copy Markdown View Source

Snapshot of a workflow execution's current state. Returned by Hourglass.status/2.

Fields:

  • state — high-level lifecycle state.
  • pending_activities — activities currently scheduled or executing, with attempt count + last failure (if any). Always populated; cheap (single DescribeWorkflowExecution call).
  • recent_failures — list of activity-failure events from the workflow's history, ordered most-recent first. Only populated when failures: :include is passed to status/2; walks history (more expensive). nil when not requested; [] when requested + empty.
  • start_time — when the workflow started.
  • close_time — when the workflow completed/failed/was terminated; nil while running.

Design

User direction: "if the human has to look at temporal, we've failed." This struct is the production-safe observability surface — tests, ops tooling, and GenServers monitoring long-running workflows pull from here without needing the Temporal Web UI.

Summary

Types

failure_event()
pending_activity()
state()
t()

Types

failure_event()

@type failure_event() :: %{
  activity_type: String.t(),
  attempt: non_neg_integer(),
  failure: Temporal.Api.Failure.V1.Failure.t(),
  event_time: DateTime.t()
}

pending_activity()

@type pending_activity() :: %{
  activity_type: String.t(),
  attempt: non_neg_integer(),
  last_failure: Temporal.Api.Failure.V1.Failure.t() | nil
}

state()

@type state() ::
  :running
  | :completed
  | :failed
  | :continued_as_new
  | :timed_out
  | :canceled
  | :terminated
  | :unknown

t()

@type t() :: %Hourglass.WorkflowStatus{
  close_time: DateTime.t() | nil,
  pending_activities: [pending_activity()],
  recent_failures: [failure_event()] | nil,
  start_time: DateTime.t() | nil,
  state: state()
}