workflow

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Jul 30, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package workflow provides a declarative workflow engine for orchestrating multi-step chain operations. Workflows are defined as YAML files with typed steps (tx, query, wait, prompt, provider, output, shell, check).

Built-in workflows (deploy, update, close) ship as embedded defaults. Users can override them globally or per-context.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EvalCondition 

func EvalCondition(condition string, data json.RawMessage, state *RunState) (bool, error)

EvalCondition evaluates a condition expression against the run state. Returns true if the condition is met. The condition is a Go template that should render to "true" or a non-empty, non-"false" string.

func ExtractOutputs 

func ExtractOutputs(outputDefs map[string]string, raw json.RawMessage, state *RunState) (map[string]any, error)

ExtractOutputs extracts named outputs from a raw JSON result using template expressions. Each output entry maps a name to a template that extracts a value from the result.

func ParseList 

func ParseList(data string) ([]map[string]any, error)

ParseList attempts to parse a string as a JSON array of objects. If the input is not JSON, returns nil.

func ResolveParams 

func ResolveParams(params map[string]string, state *RunState) (map[string]string, error)

ResolveParams resolves all template values in a params map.

func ResolveTemplate 

func ResolveTemplate(tmpl string, state *RunState) (string, error)

ResolveTemplate evaluates a Go template string against the workflow run state. Templates use {{ .Params.key }}, {{ .Steps.name.key }}, {{ .Account }}, etc.

Types

type ActionLogAdapter 

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

ActionLogAdapter implements Logger by writing one type=workflow entry per completed step to the per-context action log (SPEC §5.6). A nil adapter or nil underlying logger is a no-op, so wiring is always safe.

func NewActionLogAdapter 

func NewActionLogAdapter(l *actionlog.Logger, workflow string) *ActionLogAdapter

NewActionLogAdapter creates an adapter that records steps of the named workflow to l. Returns nil when l is nil, which the engine treats as "no logging".

func (*ActionLogAdapter) LogStep 

func (a *ActionLogAdapter) LogStep(workflowID string, stepIndex int, result *StepResult)

LogStep records a completed workflow step. Logging is best-effort and never interrupts workflow execution.

type DisplayDef 

type DisplayDef struct {
	Columns []string `yaml:"columns,omitempty" json:"columns,omitempty"`
}

DisplayDef defines how data is displayed in a prompt step.

type Engine 

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

Engine executes workflow definitions step by step.

func NewEngine 

func NewEngine(registry StepRegistry, logger Logger) *Engine

NewEngine creates a workflow engine with the given step registry and logger.

func (*Engine) Run 

func (e *Engine) Run(ctx context.Context, wf *WorkflowDef, account string, params map[string]any) (*RunState, error)

Run executes a workflow definition with the given parameters. It returns the final run state containing all step results.

type ErrorAction 

type ErrorAction string

ErrorAction defines what happens when a step fails. 

const (
	OnErrorAbort    ErrorAction = "abort"    // Stop the workflow
	OnErrorContinue ErrorAction = "continue" // Log the error and proceed
	OnErrorSkip     ErrorAction = "skip"     // Skip this step silently
)

type Loader 

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

Loader resolves and loads workflow definitions from the filesystem and embedded defaults.

Resolution order:

  1. Per-context: <home>/contexts/<ctx>/workflows/<name>.yaml
  2. Global user: <home>/workflows/<name>.yaml
  3. Embedded built-in defaults

func NewLoader 

func NewLoader(home, contextName string, builtins map[string][]byte) *Loader

NewLoader creates a workflow loader for the given home directory and context.

func (*Loader) List 

func (l *Loader) List() []string

List returns the names of all available workflows (from all sources, deduplicated).

func (*Loader) Load 

func (l *Loader) Load(name string) (*WorkflowDef, error)

Load loads a workflow definition by name, following the resolution order.

type Logger 

type Logger interface {
	LogStep(workflowID string, stepIndex int, result *StepResult)
}

Logger is called after each step completes. The workflow engine uses this to write entries to the action log. Nil logger means no logging.

type ParamDef 

type ParamDef struct {
	Type        ParamType `yaml:"type"                  json:"type"`
	Required    bool      `yaml:"required,omitempty"    json:"required,omitempty"`
	Default     string    `yaml:"default,omitempty"     json:"default,omitempty"`
	Description string    `yaml:"description,omitempty" json:"description,omitempty"`
}

ParamDef defines a workflow input parameter. CLI flags are auto-generated from these definitions.

type ParamType 

type ParamType string

ParamType defines the type of a workflow parameter. 

const (
	ParamString   ParamType = "string"
	ParamInt      ParamType = "int"
	ParamBool     ParamType = "bool"
	ParamDuration ParamType = "duration"
	ParamFile     ParamType = "file"
)

type RetryDef 

type RetryDef struct {
	Max   int    `yaml:"max,omitempty"   json:"max,omitempty"`
	Delay string `yaml:"delay,omitempty" json:"delay,omitempty"` // duration string
}

RetryDef defines retry behavior for a step.

type RunState 

type RunState struct {
	WorkflowID string                 `json:"workflow_id"`
	Workflow   string                 `json:"workflow"`
	Account    string                 `json:"account"`
	Params     map[string]any         `json:"params"`
	Steps      map[string]*StepResult `json:"steps"`
	StepOrder  []string               `json:"-"` // ordered step names for iteration
}

RunState holds the accumulated state of a workflow execution. It is passed through steps and provides variable resolution context.

func NewRunState 

func NewRunState(workflowID, workflowName, account string, params map[string]any) *RunState

NewRunState creates a fresh run state for a workflow execution.

func (*RunState) SetStepResult 

func (rs *RunState) SetStepResult(name string, result *StepResult)

SetStepResult records a step result in the run state.

func (*RunState) StepOutput 

func (rs *RunState) StepOutput(stepName, key string) any

StepOutput returns a named output value from a completed step. Returns nil if the step or output key does not exist.

type StepDef 

type StepDef struct {
	Name string   `yaml:"name"              json:"name"`
	Type StepType `yaml:"type"              json:"type"`

	// tx step fields
	Msg string `yaml:"msg,omitempty" json:"msg,omitempty"` // message type, e.g. "deployment.MsgCreateDeployment"

	// query / wait step fields
	Query string `yaml:"query,omitempty" json:"query,omitempty"` // query path, e.g. "market.bids"

	// wait step fields
	Timeout string `yaml:"timeout,omitempty" json:"timeout,omitempty"` // duration template
	Until   string `yaml:"until,omitempty"   json:"until,omitempty"`   // condition expression template

	// prompt step fields
	Mode    string     `yaml:"mode,omitempty"    json:"mode,omitempty"`    // "interactive", "cheapest", "provider=<addr>"
	Data    string     `yaml:"data,omitempty"    json:"data,omitempty"`    // template resolving to the data to prompt over
	Display DisplayDef `yaml:"display,omitempty" json:"display,omitempty"` // display configuration

	// provider step fields
	Action string `yaml:"action,omitempty" json:"action,omitempty"` // e.g. "send-manifest", "lease-status"

	// shell step fields
	Command string `yaml:"command,omitempty" json:"command,omitempty"` // shell command template

	// check step fields
	Condition string `yaml:"condition,omitempty" json:"condition,omitempty"` // condition expression template

	// output step fields
	Template string `yaml:"template,omitempty" json:"template,omitempty"` // Go template for output

	// Common fields
	Params  map[string]string `yaml:"params,omitempty"   json:"params,omitempty"`   // template-valued parameters
	Output  map[string]string `yaml:"output,omitempty"   json:"output,omitempty"`   // named outputs extracted from result
	OnError ErrorAction       `yaml:"on-error,omitempty" json:"on_error,omitempty"` // abort, continue, skip
	Retry   *RetryDef         `yaml:"retry,omitempty"    json:"retry,omitempty"`    // retry configuration
	OnFail  ErrorAction       `yaml:"on-fail,omitempty"  json:"on_fail,omitempty"`  // for check steps: skip or abort
}

StepDef defines a single step in a workflow.

type StepExecutor 

type StepExecutor interface {
	Type() StepType
	Execute(ctx context.Context, step StepDef, state *RunState) (*StepResult, error)
}

StepExecutor is the interface step implementations satisfy. Defined here to avoid a circular import with the steps package.

type StepRegistry 

type StepRegistry interface {
	Get(t StepType) (StepExecutor, error)
}

StepRegistry looks up executors by step type.

type StepResult 

type StepResult struct {
	Name      string          `json:"name"`
	Type      StepType        `json:"type"`
	Status    string          `json:"status"` // "success", "failed", "skipped"
	Output    map[string]any  `json:"output,omitempty"`
	RawResult json.RawMessage `json:"raw_result,omitempty"`
	Error     string          `json:"error,omitempty"`
	Duration  time.Duration   `json:"duration"`
	TxHash    string          `json:"tx_hash,omitempty"`
	Height    int64           `json:"height,omitempty"`
}

StepResult holds the outcome of executing a single step.

type StepType 

type StepType string

StepType classifies what a workflow step does. 

const (
	StepTx       StepType = "tx"       // Broadcast a transaction
	StepQuery    StepType = "query"    // Execute a chain query
	StepWait     StepType = "wait"     // Poll a query until a condition is met
	StepPrompt   StepType = "prompt"   // Interactive user input
	StepProvider StepType = "provider" // Provider gateway call
	StepOutput   StepType = "output"   // Display formatted output
	StepShell    StepType = "shell"    // Run a shell command
	StepCheck    StepType = "check"    // Assert a condition
)

type WorkflowDef 

type WorkflowDef struct {
	Name        string              `yaml:"name"                  json:"name"`
	Description string              `yaml:"description,omitempty" json:"description,omitempty"`
	Version     int                 `yaml:"version,omitempty"     json:"version,omitempty"`
	Params      map[string]ParamDef `yaml:"params,omitempty"      json:"params,omitempty"`
	Steps       []StepDef           `yaml:"steps"                 json:"steps"`
}

WorkflowDef is the top-level workflow definition loaded from YAML.

Source Files

View all Source files

Directories

Path Synopsis
Package adapters implements the narrow client interfaces the workflow engine's step executors depend on (steps.ChainClient and steps.ProviderClient), backed by the real Akash node and provider gateway clients.
 Package adapters implements the narrow client interfaces the workflow engine's step executors depend on (steps.ChainClient and steps.ProviderClient), backed by the real Akash node and provider gateway clients.
Package builtin provides embedded default workflow definitions.
 Package builtin provides embedded default workflow definitions.
Package steps defines the StepExecutor interface and a registry of built-in step type implementations for the workflow engine.
 Package steps defines the StepExecutor interface and a registry of built-in step type implementations for the workflow engine.

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.