engine

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 31, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNilDefinition = errors.New("engine: workflow definition is nil")

	ErrEmptyInitialStepID = errors.New("engine: initialStepId is empty")

	ErrInitialStepUnknown = errors.New("engine: initialStepId not found in steps")

	ErrEmptyStepID = errors.New("engine: step id is empty")

	ErrEmptyStepKind = errors.New("engine: step kind is empty")

	ErrDuplicateStepID = errors.New("engine: duplicate step id")

	ErrNoMatchingTransition = errors.New("engine: no matching transition")

	ErrUnknownActionType = errors.New("engine: unknown action type")

	ErrCELGuard = errors.New("engine: cel guard evaluation failed")
)

Functions

This section is empty.

Types

type ActionContext 

type ActionContext struct {
	RunID     string
	StepID    string
	ListName  string // "onEnter" or "onExit"
	Index     int
	Action    definition.Action
	Variables map[string]any
}

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

type ActionRunner 

type ActionRunner interface {
	Run(ctx ActionContext) error
}

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

func NewHTTPRunner 

func NewHTTPRunner(client *http.Client) ActionRunner

NewHTTPRunner builds an ActionRunner for workflow actions with type "http".

func NewStubRunner 

func NewStubRunner() ActionRunner

NewStubRunner returns the built-in "stub" runner (params.set merges JSON values into variables).

type Event 

type Event struct {
	Seq   int       `json:"seq"`
	RunID string    `json:"runId,omitempty"`
	Type  EventType `json:"type"`

	StepID string `json:"stepId,omitempty"`

	// input.accepted
	InputKeys []string `json:"inputKeys,omitempty"`

	// action.ran
	ActionList string `json:"actionList,omitempty"` // "onEnter" or "onExit"
	ActionID   string `json:"actionId,omitempty"`
	ActionType string `json:"actionType,omitempty"`

	// transition.guard / transition.taken:
	TransitionIndex int    `json:"transitionIndex,omitempty"`
	FromStepID      string `json:"fromStepId,omitempty"`
	ToStepID        string `json:"toStepId,omitempty"`

	// transition.guard:
	GuardResult string `json:"guardResult,omitempty"` // "true", "false", "error"
	GuardError  string `json:"guardError,omitempty"`
}

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

func (Event) String 

func (e Event) String() string

String returns a short human-readable log line for demos and CLI output.

type EventType 

type EventType string

EventType identifies the kind of trace Event. 

const (
	EventStepEntered     EventType = "step.entered"
	EventInputAccepted   EventType = "input.accepted"
	EventActionRan       EventType = "action.ran"
	EventTransitionGuard EventType = "transition.guard"
	EventTransitionTaken EventType = "transition.taken"
	EventBlocked         EventType = "run.blocked"
	EventCompleted       EventType = "run.completed"
)

type InputValidationError 

type InputValidationError struct {
	StepID string
	Err    error
}

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

func (*InputValidationError) Error 

func (e *InputValidationError) Error() string

func (*InputValidationError) Unwrap 

func (e *InputValidationError) Unwrap() error

type Instance 

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

func NewInstance 

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

NewInstance creates an Instance positioned at def.InitialStepID with a shallow copy of opts.InitialVariables. It validates step ids, initial step presence, and terminal rules (via workflowgraph.BuildTerminalSet).

func NewInstanceFromSnapshot 

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

NewInstanceFromSnapshot restores an Instance from Snapshot plus the workflow used when the run began. def must describe the same graph as at snapshot time (same ids and compatible steps/transitions).

Registry: pass the same ActionRegistry semantics as then the run was created (or rely on defaults consistently). RunID uses opts.RunID when non-empty, otherwise snap.RunID. TraceGuards is true if either opts.TraceGuards or snap.TraceGuards is true.

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 Options.RunID (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 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 (top-level maps/slices only); 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 errors.As(..., *UnknownStepError).

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 or extend variables). SubmitAdvanced means the instance advanced to StepID (now the next step). 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 string

	InitialVariables map[string]any

	TraceGuards bool

	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 everything needed by the workflow before passing the registry to NewInstance.

func DefaultRegistry 

func DefaultRegistry() *Registry

DefaultRegistry returns a registry with the built-in "stub" runner registered.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry returns an empty registry (no built-in types registered).

func RegistryWithHTTP 

func RegistryWithHTTP(client *http.Client) *Registry

RegistryWithHTTP returns DefaultRegistry plus an "http" runner using 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 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 struct {
	Status RunStatus
	StepID string
	Events []Event
	Err    error
}

RunResult is the outcome of 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 int

RunStatus explains why RunUntilBlocked stopped. 

const (
	// RunBlocked means execution paused on a human step; call SubmitInput next.
	RunBlocked RunStatus = iota + 1

	// RunCompleted means execution reached a declared terminal end step.
	RunCompleted

	// RunFailed means execution stopped with an error; see RunResult.Err.
	RunFailed
)

type Snapshot 

type Snapshot struct {
	RunID         string         `json:"runId"`
	TraceGuards   bool           `json:"traceGuards"`
	CurrentStepID string         `json:"currentStepId"`
	OnEnterRan    bool           `json:"onEnterRan"`
	Variables     map[string]any `json:"variables"`
	Events        []Event        `json:"events,omitempty"`
	NextSeq       int            `json:"nextSeq"`
}

Snapshot is JSON-friendly runtime state: correlation id, step position, variables, and trace. It does not store compiled CEL programs or compiled input schemas; those are rebuilt after restore.

type SubmitInputResult 

type SubmitInputResult struct {
	Status SubmitInputStatus
	StepID string
	Err    error
}

SubmitInputResult is returned by Instance.SubmitInput.

StepID is the current step after the call (unchanged on SubmitStayOnStep and SubmitFailed except where noted). Err is set only when Status is SubmitFailed.

type SubmitInputStatus 

type SubmitInputStatus int

SubmitInputStatus is the outcome of SubmitInput. 

const (
	// SubmitStayOnStep means input was stored but no outbound transition matched; still on the human step.
	SubmitStayOnStep SubmitInputStatus = iota + 1

	// SubmitAdvanced means input was accepted and currentStepID moved to StepID (the next step).
	SubmitAdvanced

	// SubmitFailed means validation or leaving the step failed; see SubmitInputResult.Err.
	SubmitFailed
)

type UnknownStepError 

type UnknownStepError struct {
	StepID string
}

func (*UnknownStepError) Error 

func (e *UnknownStepError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.