Help us shape the future of Go! Take the 2026 Go Developer Survey

workflow

package
v1.261022.0 Latest Latest
Warning

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

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

Documentation

Overview

Package workflow is a standalone workflow runner for .asc/workflow.json files. It has zero imports from the rest of the codebase. Only depends on Go stdlib plus tidwall/jsonc for JSONC comment support in load.go.

Index

Constants

View Source 
const DefaultPath = ".asc/workflow.json"

DefaultPath is the default location for the workflow definition file.

View Source 
const MaxCallDepth = 16

MaxCallDepth is the maximum nesting depth for sub-workflow calls.

Variables

View Source 
var (
	// ErrUnknownWorkflow indicates a workflow name that the definition does not declare.
	ErrUnknownWorkflow = errors.New("unknown workflow")
	// ErrPrivateWorkflow indicates a private workflow requested as the entry point.
	ErrPrivateWorkflow = errors.New("private workflow")
	// ErrResumeRunNotFound indicates a --resume run ID with no persisted state.
	ErrResumeRunNotFound = errors.New("resume run not found")
	// ErrResumeRejected indicates persisted run state that cannot be resumed
	// with the requested workflow, file, definition, or parameters.
	ErrResumeRejected = errors.New("resume run rejected")
	// ErrCommandFailed indicates a user-defined run step or hook command that
	// did not succeed, including a step that exceeded its workflow-defined
	// timeout or whose declared outputs were invalid.
	ErrCommandFailed = errors.New("workflow command failed")
)
View Source 
var (
	// ErrWorkflowRead indicates workflow file read failure.
	ErrWorkflowRead = errors.New("read workflow")
	// ErrWorkflowParseJSON indicates workflow JSON decode failure.
	ErrWorkflowParseJSON = errors.New("parse workflow JSON")
)

Functions

func ParseParams 

func ParseParams(args []string) (map[string]string, error)

ParseParams converts CLI arguments in KEY:VALUE or KEY=VALUE format to a map.

Types

type AttemptResult added in v1.260810.0 

type AttemptResult struct {
	Invocation    int    `json:"invocation"`
	Attempt       int    `json:"attempt"`
	Status        string `json:"status"`
	DurationMS    int64  `json:"duration_ms"`
	FailureReason string `json:"failure_reason,omitempty"`
	Error         string `json:"error,omitempty"`
}

AttemptResult records one configured run-step attempt.

type Definition 

type Definition struct {
	Env       map[string]string   `json:"env,omitempty"`
	BeforeAll string              `json:"before_all,omitempty"`
	AfterAll  string              `json:"after_all,omitempty"`
	Error     string              `json:"error,omitempty"`
	Workflows map[string]Workflow `json:"workflows"`
}

Definition is the top-level .asc/workflow.json schema.

func Load 

func Load(path string) (*Definition, error)

Load reads and validates a workflow definition file.

func LoadUnvalidated 

func LoadUnvalidated(path string) (*Definition, error)

LoadUnvalidated reads and parses a workflow definition file without validation.

type HookResult 

type HookResult struct {
	Command    string `json:"command,omitempty"`
	Status     string `json:"status"`
	DurationMS int64  `json:"duration_ms"`
	Error      string `json:"error,omitempty"`
}

HookResult records execution of a hook command (before_all/after_all/error).

type HooksResult 

type HooksResult struct {
	BeforeAll *HookResult `json:"before_all,omitempty"`
	AfterAll  *HookResult `json:"after_all,omitempty"`
	Error     *HookResult `json:"error,omitempty"`
}

HooksResult records hook outcomes for a run.

type ResumeInfo 

type ResumeInfo struct {
	Command string `json:"command,omitempty"`
}

ResumeInfo describes how to continue a partially completed workflow run.

type RetryPolicy added in v1.260810.0 

type RetryPolicy struct {
	MaxAttempts int    `json:"max_attempts"`
	Delay       string `json:"delay"`
}

RetryPolicy configures explicit bounded retries for a run step.

type RunOptions 

type RunOptions struct {
	WorkflowName string
	Params       map[string]string
	DryRun       bool
	Stdout       io.Writer
	Stderr       io.Writer
	WorkflowFile string
	StateDir     string
	ResumeRunID  string
}

RunOptions configures a workflow execution.

type RunResult 

type RunResult struct {
	Workflow       string                       `json:"workflow"`
	Status         string                       `json:"status"`
	Error          string                       `json:"error,omitempty"`
	FailedStep     string                       `json:"failed_step,omitempty"`
	Recoverable    bool                         `json:"recoverable,omitempty"`
	Terminal       bool                         `json:"terminal,omitempty"`
	TerminalReason string                       `json:"terminal_reason,omitempty"`
	RunID          string                       `json:"run_id,omitempty"`
	RunFile        string                       `json:"run_file,omitempty"`
	Resumed        bool                         `json:"resumed,omitempty"`
	Resume         *ResumeInfo                  `json:"resume,omitempty"`
	Outputs        map[string]map[string]string `json:"outputs,omitempty"`
	Hooks          *HooksResult                 `json:"hooks,omitempty"`
	Steps          []StepResult                 `json:"steps"`
	DurationMS     int64                        `json:"duration_ms"`
}

RunResult is the structured output of a workflow execution.

func Run 

func Run(ctx context.Context, def *Definition, opts RunOptions) (*RunResult, error)

Run executes a named workflow from the Definition.

type Step 

type Step struct {
	Run      string            `json:"run,omitempty"`
	Workflow string            `json:"workflow,omitempty"`
	Name     string            `json:"name,omitempty"`
	If       string            `json:"if,omitempty"`
	With     map[string]string `json:"with,omitempty"`
	Outputs  map[string]string `json:"outputs,omitempty"`
	Retry    *RetryPolicy      `json:"retry,omitempty"`
	Timeout  *string           `json:"timeout,omitempty"`
	// contains filtered or unexported fields
}

Step is one executable action in a workflow. Bare JSON strings unmarshal to Step{Run: "..."} as shorthand.

func (*Step) UnmarshalJSON 

func (s *Step) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the flexible step format:

  • bare string → Step{Run: "..."}
  • object → normal unmarshal

type StepResult 

type StepResult struct {
	Index          int               `json:"index"`
	Name           string            `json:"name,omitempty"`
	Command        string            `json:"command,omitempty"`
	Workflow       string            `json:"workflow,omitempty"`
	ParentWorkflow string            `json:"parent_workflow,omitempty"`
	Status         string            `json:"status"`
	DurationMS     int64             `json:"duration_ms"`
	FailureReason  string            `json:"failure_reason,omitempty"`
	Error          string            `json:"error,omitempty"`
	Attempts       []AttemptResult   `json:"attempts,omitempty"`
	Outputs        map[string]string `json:"outputs,omitempty"`
}

StepResult records one executed step.

type ValidationCode 

type ValidationCode string

ValidationCode classifies validation failures. 

const (
	ErrNoWorkflows                 ValidationCode = "no_workflows"
	ErrInvalidWorkflowName         ValidationCode = "invalid_workflow_name"
	ErrEmptySteps                  ValidationCode = "empty_steps"
	ErrStepNoAction                ValidationCode = "step_no_action"
	ErrStepEmptyRun                ValidationCode = "step_empty_run"
	ErrStepConflict                ValidationCode = "step_run_and_workflow"
	ErrWorkflowNotFound            ValidationCode = "workflow_not_found"
	ErrCyclicReference             ValidationCode = "cyclic_reference"
	ErrStepWithOnRun               ValidationCode = "step_with_on_run"
	ErrStepOutputsOnWorkflow       ValidationCode = "step_outputs_on_workflow"
	ErrStepOutputsRequireName      ValidationCode = "step_outputs_require_name"
	ErrDuplicateOutputProducerName ValidationCode = "duplicate_output_producer_name"
	ErrInvalidOutputName           ValidationCode = "invalid_output_name"
	ErrInvalidOutputExpr           ValidationCode = "invalid_output_expr"
	ErrStepRetryOnWorkflow         ValidationCode = "step_retry_on_workflow"
	ErrStepTimeoutOnWorkflow       ValidationCode = "step_timeout_on_workflow"
	ErrInvalidStepRetry            ValidationCode = "invalid_step_retry"
	ErrInvalidRetryMaxAttempts     ValidationCode = "invalid_retry_max_attempts"
	ErrInvalidRetryDelay           ValidationCode = "invalid_retry_delay"
	ErrInvalidStepTimeout          ValidationCode = "invalid_step_timeout"
)

type ValidationError 

type ValidationError struct {
	Code     ValidationCode `json:"code"`
	Workflow string         `json:"workflow,omitempty"`
	Step     int            `json:"step,omitempty"`
	Path     string         `json:"path,omitempty"`
	Message  string         `json:"message"`
}

ValidationError describes a structured workflow validation failure.

func Validate 

func Validate(def *Definition) []*ValidationError

Validate checks a Definition for structural errors. Returns all validation errors found (not just the first).

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type Workflow 

type Workflow struct {
	Description string            `json:"description,omitempty"`
	Private     bool              `json:"private,omitempty"`
	Env         map[string]string `json:"env,omitempty"`
	Steps       []Step            `json:"steps"`
}

Workflow is a named automation sequence.

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.