engine

Documentation

Overview

Package engine provides the low-level API for executing workflow definitions.

Most applications should start with github.com/justinush/maestro/pkg/maestro:

maestro.Load -> Runtime.NewInstance -> RunUntilBlocked -> SubmitInput

Use pkg/engine when you need direct control over Options, action registries, or Snapshot restore without the maestro.Runtime facade.

Typical control flow: branch on RunResult.Status and SubmitInputResult.Status. Err is set only when status is RunFailed or SubmitFailed.

NewInstance
    -> RunUntilBlocked
    |-- RunCompleted -> done
    |-- RunFailed (inspect Err) -> done
    |-- RunBlocked
            -> SubmitInput
            |-- SubmitFailed (inspect Err) -> done
            |-- SubmitAdvanced or SubmitStayOnStep
                    -> RunUntilBlocked (repeat)

Index

• Variables
• type ActionContext
• type ActionRunner
  • func NewHTTPRunner(client *http.Client) ActionRunner
  • func NewStubRunner() ActionRunner
• type Event
• type EventType
• type InputValidationError
  • func AsInputValidationError(err error) (*InputValidationError, bool)
• type Instance
  • func NewInstance(def *definition.WorkflowDefinition, opts Options) (*Instance, error)
  • func NewInstanceFromSnapshot(def *definition.WorkflowDefinition, snap Snapshot, opts Options) (*Instance, error)
  • func (in *Instance) CurrentStepID() string
  • func (in *Instance) Definition() *definition.WorkflowDefinition
  • func (in *Instance) Events() []Event
  • func (in *Instance) IsTerminal() bool
  • func (in *Instance) RunID() string
  • func (in *Instance) RunUntilBlocked() RunResult
  • func (in *Instance) Snapshot() Snapshot
  • func (in *Instance) Step() (*definition.Step, error)
  • func (in *Instance) StepByID(id string) (*definition.Step, error)
  • func (in *Instance) SubmitInput(input map[string]any) SubmitInputResult
  • func (in *Instance) Variables() map[string]any
• type Options
• type Registry
  • func DefaultRegistry() *Registry
  • func NewRegistry() *Registry
  • func RegistryWithHTTP(client *http.Client) *Registry
  • func (r *Registry) Lookup(actionType string) (ActionRunner, bool)
  • func (r *Registry) MustRegister(actionType string, runner ActionRunner)
  • func (r *Registry) Register(actionType string, runner ActionRunner) error
• type RunResult
• type RunStatus
• type Snapshot
• type SubmitInputResult
• type SubmitInputStatus
• type UnknownStepError
  • func AsUnknownStepError(err error) (*UnknownStepError, bool)

Variables

var (
	// ErrNilDefinition is returned when a nil workflow definition is passed to constructors.
	ErrNilDefinition = iengine.ErrNilDefinition
	// ErrEmptyInitialStepID is returned when initialStepId is empty.
	ErrEmptyInitialStepID = iengine.ErrEmptyInitialStepID
	// ErrInitialStepUnknown is returned when initialStepId is not present in steps.
	ErrInitialStepUnknown = iengine.ErrInitialStepUnknown
	// ErrEmptyStepID is returned when a step id is empty.
	ErrEmptyStepID = iengine.ErrEmptyStepID
	// ErrEmptyStepKind is returned when a step kind is empty.
	ErrEmptyStepKind = iengine.ErrEmptyStepKind
	// ErrDuplicateStepID is returned when two steps share the same id.
	ErrDuplicateStepID = iengine.ErrDuplicateStepID
	// ErrNoMatchingTransition is returned when every outbound guard evaluated to false.
	ErrNoMatchingTransition = iengine.ErrNoMatchingTransition
	// ErrUnknownActionType is returned when an action type is not registered.
	ErrUnknownActionType = iengine.ErrUnknownActionType
	// ErrCELGuard is returned when a transition guard fails to evaluate.
	ErrCELGuard = iengine.ErrCELGuard
)

Errors returned while building or executing instances.

Types

type ActionContext

type ActionContext = iengine.ActionContext

ActionContext is the input to [ActionRunner.Run] for one action invocation.

type ActionRunner

type ActionRunner = iengine.ActionRunner

ActionRunner executes a single workflow action (stub, http, or custom types).

func NewHTTPRunner

func NewHTTPRunner(client *http.Client) ActionRunner

NewHTTPRunner returns an ActionRunner for "http" actions.

func NewStubRunner

func NewStubRunner() ActionRunner

NewStubRunner returns the built-in stub ActionRunner (usually accessed via DefaultRegistry).

type Event

type Event = iengine.Event

Event is one row in the execution trace (JSON-serializable).

type EventType

type EventType = iengine.EventType

EventType identifies the kind of trace Event.

const (
	// EventStepEntered is recorded when execution enters a step.
	EventStepEntered EventType = iengine.EventStepEntered
	// EventInputAccepted is recorded when [Instance.SubmitInput] accepts input on a human step.
	EventInputAccepted EventType = iengine.EventInputAccepted
	// EventActionRan is recorded after a successful onEnter/onExit action.
	EventActionRan EventType = iengine.EventActionRan
	// EventTransitionGuard is recorded when TraceGuards is enabled and a guard is evaluated.
	EventTransitionGuard EventType = iengine.EventTransitionGuard
	// EventTransitionTaken is recorded when an outbound transition fires.
	EventTransitionTaken EventType = iengine.EventTransitionTaken
	// EventBlocked is recorded when [RunUntilBlocked] stops on a human step.
	EventBlocked EventType = iengine.EventBlocked
	// EventCompleted is recorded when execution reaches a terminal end step.
	EventCompleted EventType = iengine.EventCompleted
)

EventType constants for Instance.Events and [RunResult.Events].

type InputValidationError

type InputValidationError = iengine.InputValidationError

InputValidationError means Instance.SubmitInput input failed JSON Schema validation for a human step.

func AsInputValidationError

func AsInputValidationError(err error) (*InputValidationError, bool)

AsInputValidationError reports whether err unwraps to *InputValidationError (e.g. SubmitInputResult.Err).

type Instance

type Instance struct {
	// contains filtered or unexported fields
}

Instance is a single workflow run. Create one with NewInstance or NewInstanceFromSnapshot.

Instance is not safe for concurrent mutation. If multiple goroutines need to access the same Instance, coordinate access externally (for example with a mutex) and avoid calling methods that mutate state concurrently (RunUntilBlocked, SubmitInput).

Advance execution with Instance.RunUntilBlocked and Instance.SubmitInput. Inspect RunResult and SubmitInputResult status values before reading Err.

func NewInstance

func NewInstance(def *definition.WorkflowDefinition, opts Options) (*Instance, error)

NewInstance starts execution at def.InitialStepID. def must be non-nil.

func NewInstanceFromSnapshot

func NewInstanceFromSnapshot(def *definition.WorkflowDefinition, snap Snapshot, opts Options) (*Instance, error)

NewInstanceFromSnapshot restores execution state from snap using the same workflow definition as before.

func (*Instance) CurrentStepID

func (in *Instance) CurrentStepID() string

CurrentStepID returns the step the engine is currently on.

func (*Instance) Definition

func (in *Instance) Definition() *definition.WorkflowDefinition

Definition returns the workflow bound to this instance, or nil if in is nil. Callers must not mutate the returned pointer or its contents.

func (*Instance) Events

func (in *Instance) Events() []Event

Events returns a copy of recorded trace events (safe to read without racing the instance).

func (*Instance) IsTerminal

func (in *Instance) IsTerminal() bool

IsTerminal reports whether the current step is both kind "end" and listed in terminalStepIds.

func (*Instance) RunID

func (in *Instance) RunID() string

RunID returns the correlation id for this run (may be empty).

func (*Instance) RunUntilBlocked

func (in *Instance) RunUntilBlocked() RunResult

RunUntilBlocked advances execution until the engine must stop and yield to the host.

RunBlocked: current step is human - call Instance.SubmitInput next. RunCompleted: reached a declared terminal end step. RunFailed: Err describes the failure; StepID and Events reflect progress up to the failure.

Returned Events is a snapshot at return time (same ordering as Instance.Events).

func (*Instance) Snapshot

func (in *Instance) Snapshot() Snapshot

Snapshot builds a Snapshot value from the current instance. Variables and Events are shallow-copied; nested values may still alias live state.

func (*Instance) Step

func (in *Instance) Step() (*definition.Step, error)

Step returns the definition for the current step.

func (*Instance) StepByID

func (in *Instance) StepByID(id string) (*definition.Step, error)

StepByID returns the step definition for id. If id is not in the workflow, the error satisfies AsUnknownStepError.

func (*Instance) SubmitInput

func (in *Instance) SubmitInput(input map[string]any) SubmitInputResult

SubmitInput applies user input on the current human step.

It validates against inputSchema (when present), merges top-level keys into variables, evaluates outbound transitions, runs onExit actions when leaving, and moves currentStepID when a transition fires.

SubmitStayOnStep means input was accepted but no transition matched (caller may prompt again). SubmitAdvanced means the instance advanced to SubmitInputResult.StepID. SubmitFailed sets Err (schema failure wraps InputValidationError when applicable).

func (*Instance) Variables

func (in *Instance) Variables() map[string]any

Variables returns a shallow copy of the variable map (nested values are still shared).

type Options

type Options struct {
	// RunID is an optional correlation id stored on the instance and in snapshots.
	RunID string

	// InitialVariables are shallow-copied into the instance at creation (nested values may still alias).
	InitialVariables map[string]any

	// TraceGuards records transition guard evaluation in the event trace.
	TraceGuards bool

	// ActionRegistry provides runners for workflow action types. When nil, DefaultRegistry is used.
	ActionRegistry *Registry
}

Options configures a new workflow instance (identity, initial variables, tracing, action runners).

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry maps workflow action "type" strings to ActionRunner implementations. Register every type referenced by the workflow before passing the registry to NewInstance.

func DefaultRegistry

func DefaultRegistry() *Registry

DefaultRegistry includes the built-in "stub" runner.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty action registry.

func RegistryWithHTTP

func RegistryWithHTTP(client *http.Client) *Registry

RegistryWithHTTP returns DefaultRegistry plus an "http" runner using client. Pass your own *http.Client in production; the maestro simulate CLI uses a private long-timeout client.

func (*Registry) Lookup

func (r *Registry) Lookup(actionType string) (ActionRunner, bool)

Lookup returns the runner for actionType and whether it exists.

func (*Registry) MustRegister

func (r *Registry) MustRegister(actionType string, runner ActionRunner)

MustRegister calls Registry.Register and panics if Register returns an error.

func (*Registry) Register

func (r *Registry) Register(actionType string, runner ActionRunner) error

Register binds actionType to runner. Duplicate types return an error.

type RunResult

type RunResult = iengine.RunResult

RunResult is the outcome of Instance.RunUntilBlocked.

Events is a point-in-time snapshot (matches Instance.Events at return). Err is non-nil only when Status is RunFailed.

type RunStatus

type RunStatus = iengine.RunStatus

RunStatus explains why Instance.RunUntilBlocked stopped.

const (
	// RunBlocked means execution paused on a human step; call [Instance.SubmitInput] next.
	RunBlocked RunStatus = iengine.RunBlocked
	// RunCompleted means execution reached a declared terminal end step.
	RunCompleted RunStatus = iengine.RunCompleted
	// RunFailed means execution stopped with an error; see [RunResult.Err].
	RunFailed RunStatus = iengine.RunFailed
)

RunStatus values returned by Instance.RunUntilBlocked.

type Snapshot

type Snapshot = iengine.Snapshot

Snapshot is JSON-friendly runtime state: run id, step position, variables, and trace. Compiled CEL programs and input schemas are rebuilt after restore.

type SubmitInputResult

type SubmitInputResult = iengine.SubmitInputResult

SubmitInputResult is returned by Instance.SubmitInput.

StepID is the current step after the call. Err is set only when Status is SubmitFailed.

type SubmitInputStatus

type SubmitInputStatus = iengine.SubmitInputStatus

SubmitInputStatus is the outcome of Instance.SubmitInput.

const (
	// SubmitStayOnStep means input was stored but no outbound transition matched.
	SubmitStayOnStep SubmitInputStatus = iengine.SubmitStayOnStep
	// SubmitAdvanced means the instance moved to SubmitInputResult.StepID.
	SubmitAdvanced SubmitInputStatus = iengine.SubmitAdvanced
	// SubmitFailed means validation or leaving the step failed; see [SubmitInputResult.Err].
	SubmitFailed SubmitInputStatus = iengine.SubmitFailed
)

SubmitInputStatus values returned by Instance.SubmitInput.

type UnknownStepError

type UnknownStepError = iengine.UnknownStepError

UnknownStepError means a step id was not found in the workflow (see Instance.StepByID).

func AsUnknownStepError

func AsUnknownStepError(err error) (*UnknownStepError, bool)

AsUnknownStepError reports whether err unwraps to *UnknownStepError (e.g. from Instance.StepByID).