Hephaestus.Core.Instance (hephaestus v0.2.0)

Copy Markdown View Source

A runtime instance of a workflow execution.

Tracks the current state of a workflow as it progresses through steps, including which steps are active (being executed), completed, and the accumulated context.

Fields

  • id - unique identifier (UUID v4)
  • workflow - the workflow module being executed
  • workflow_version - the version of the workflow definition (positive integer, default 1)
  • current_step - the step module currently being processed (or nil)
  • status - one of :pending, :running, :waiting, :completed, :failed
  • context - Hephaestus.Core.Context with initial data and step results
  • step_configs - per-step config overrides keyed by step module
  • active_steps - MapSet of step modules currently being executed
  • completed_steps - MapSet of step modules that have finished
  • runtime_metadata - dynamic metadata accumulated from step executions
  • telemetry_metadata - caller metadata merged into emitted telemetry events
  • telemetry_start_time - monotonic start time used to compute telemetry durations
  • execution_history - list of Hephaestus.Core.ExecutionEntry records

Summary

Types

status()

The lifecycle status of a workflow instance.

t()

A workflow instance struct tracking execution state, active/completed steps, and context.

Functions

new(workflow)

Creates a new workflow instance for the given workflow module.

new(workflow, context)
new(workflow, version, context)

Types

status()

@type status() :: :pending | :running | :waiting | :completed | :failed

The lifecycle status of a workflow instance.

t()

@type t() :: %Hephaestus.Core.Instance{
  active_steps: MapSet.t(module()),
  completed_steps: MapSet.t(module()),
  context: Hephaestus.Core.Context.t(),
  current_step: module() | nil,
  execution_history: list(),
  id: String.t(),
  runtime_metadata: map(),
  status: status(),
  step_configs: %{optional(module()) => map()},
  telemetry_metadata: map(),
  telemetry_start_time: integer() | nil,
  workflow: module(),
  workflow_version: pos_integer()
}

A workflow instance struct tracking execution state, active/completed steps, and context.

Functions

new(workflow)

@spec new(module()) :: t()

Creates a new workflow instance for the given workflow module.

Generates a UUID v4 identifier and initializes the instance with a :pending status and the provided initial context.

Constructor overloads:

  • new/1 — defaults version to 1 and context to %{}
  • new/2 — accepts either (workflow, context) or (workflow, version)
  • new/3 — accepts (workflow, version, context)

Parameters

  • workflow - the workflow module to execute
  • version - the workflow version (positive integer)
  • context - a map of initial data passed to the workflow (default: %{})

Examples

iex> instance = Instance.new(MyApp.Workflows.OrderFlow, 1, %{order_id: 123})
iex> instance.status
:pending
iex> instance.context.initial
%{order_id: 123}
iex> instance.workflow_version
1

With default empty context:

iex> instance = Instance.new(MyApp.Workflows.OrderFlow, 1)
iex> instance.context.initial
%{}

new(workflow, context)

@spec new(module(), map()) :: t()
@spec new(module(), pos_integer()) :: t()

new(workflow, version, context)

@spec new(module(), pos_integer(), map()) :: t()