step

Documentation

Index

• Constants
• func AfterRun(st *Step, values *values.Values, ss StateSetter)
• func DependencyParts(dep string) (string, string)
• func PreRun(st *Step, values *values.Values, ss StateSetter)
• func RegisterRunner(name string, r Runner) error
• func Run(st *Step, baseConfig map[string]json.RawMessage, values *values.Values, ...)
• type Assert
  • func (a *Assert) Eval(v *values.Values, item interface{}, stepName string) error
  • func (a *Assert) Valid() error
• type Condition
  • func (sc *Condition) Eval(v *values.Values, item interface{}, stepName string) error
  • func (sc *Condition) Valid(stepName string, steps map[string]*Step) error
• type Context
• type ErrConditionNotMet
  • func (e ErrConditionNotMet) Error() string
• type Executor
• type Runner
• type StateSetter
• type Step
  • func (st *Step) ExecutorMetadata() json.RawMessage
  • func (st *Step) IsChild() bool
  • func (st *Step) IsFinal() bool
  • func (st *Step) IsRetriable() bool
  • func (st *Step) IsRunnable() bool
  • func (st *Step) ValidAndNormalize(name string, baseConfigs map[string]json.RawMessage, steps map[string]*Step) error

Constants

const (
	EQ     = "EQ"
	NE     = "NE"
	GT     = "GT"
	LT     = "LT"
	GE     = "GE"
	LE     = "LE"
	REGEXP = "REGEXP"
)

accepted condition operators

const (
	RetrySeconds = "seconds"
	RetryMinutes = "minutes"
	RetryHours   = "hours"
)

retry patterns for a step

const (
	StateAny           = "ANY" // wildcard
	StateTODO          = "TODO"
	StateRunning       = "RUNNING"
	StateDone          = "DONE"
	StateClientError   = "CLIENT_ERROR"
	StateServerError   = "SERVER_ERROR"
	StateFatalError    = "FATAL_ERROR"
	StateCrashed       = "CRASHED"
	StatePrune         = "PRUNE"
	StateToRetry       = "TO_RETRY"
	StateAfterrunError = "AFTERRUN_ERROR"

	// steps that carry a foreach list of arguments
	StateExpanded = "EXPANDED"
)

possible states of a step

const (
	SKIP  = "skip"
	CHECK = "check"
)

Functions

func AfterRun

func AfterRun(st *Step, values *values.Values, ss StateSetter)

AfterRun evaluates a step's "check" conditions after the Step's action has been performed and impacts the entire task's execution flow through the provided StateSetter

func DependencyParts

func DependencyParts(dep string) (string, string)

DependencyParts de-composes a Step's dependency into its constituent parts: step name + step state a dependency expressed only as a step name is equivalent to depending on that step being in DONE state

func PreRun

func PreRun(st *Step, values *values.Values, ss StateSetter)

PreRun evaluates a step's "skip" conditions before the Step's action has been performed and impacts the entire task's execution flow through the provided StateSetter

func RegisterRunner

func RegisterRunner(name string, r Runner) error

RegisterRunner makes a named runner available for use in a Step's configuration

func Run

func Run(st *Step, baseConfig map[string]json.RawMessage, values *values.Values, stepChan chan<- *Step, stopRunningSteps <-chan struct{})

Run carries out the action defined by a Step, by providing values to its configuration - a stepChan channel is provided for committing the result back - a stopRunningSteps channel is provided to interrupt execution in flight values IS NOT CONCURRENT SAFE, DO NOT SHARE WITH OTHER GOROUTINES

Types

type Assert

type Assert struct {
	Value    string `json:"value"`
	Operator string `json:"operator"`
	Expected string `json:"expected"`
	Message  string `json:"message"`
}

Assert describes a challenge to a value an expected value is compared through an operator the intent of this condition can be explained through a contextual message for clearer error surfacing

func (*Assert) Eval

func (a *Assert) Eval(v *values.Values, item interface{}, stepName string) error

Eval applies a condition on a particular item, asserting if the item meets the condition or not

func (*Assert) Valid

func (a *Assert) Valid() error

Valid asserts that a condition's definition is valid ie. the operator is among the accepted values listed above

type Condition

type Condition struct {
	Type    string            `json:"type"`
	If      []*Assert         `json:"if"`
	Then    map[string]string `json:"then"`
	Message string            `json:"message"`
}

Condition defines a condition to be evaluated before or after a step's action

func (*Condition) Eval

func (sc *Condition) Eval(v *values.Values, item interface{}, stepName string) error

Eval runs the condition against a set of values, evaluating the underlying Condition

func (*Condition) Valid

func (sc *Condition) Valid(stepName string, steps map[string]*Step) error

Valid asserts that the definition for a StepCondition is valid

type Context

type Context struct {
	RequesterToken    string    `json:"requester_token"`
	RequesterUsername string    `json:"requester_username"`
	ResolverToken     string    `json:"resolver_token"`
	ResolverUsername  string    `json:"resolver_username"`
	TaskID            string    `json:"task_id"`
	Created           time.Time `json:"created"`
}

Context provides a step with extra metadata about the task

type ErrConditionNotMet

type ErrConditionNotMet string

ErrConditionNotMet is the typed error returned by Condition when its evaluation fails

func (ErrConditionNotMet) Error

func (e ErrConditionNotMet) Error() string

Error implements standard error

type Executor

type Executor struct {
	Type              string          `json:"type"`
	BaseConfiguration string          `json:"base_configuration,omitempty"`
	Configuration     json.RawMessage `json:"configuration"`
	BaseOutput        json.RawMessage `json:"base_output"`
}

Executor matches an executor type with its required configuration

type Runner

type Runner interface {
	Exec(stepName string, baseConfig json.RawMessage, config json.RawMessage, ctx interface{}) (interface{}, interface{}, error)
	ValidConfig(baseConfig json.RawMessage, config json.RawMessage) error
	Context(stepName string) interface{}
	MetadataSchema() json.RawMessage
}

Runner represents a component capable of executing a specific action, provided a configuration and a context

type StateSetter

type StateSetter func(step, state, message string)

StateSetter is a handle to apply the effects of a condition evaluation

type Step

type Step struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Idempotent  bool   `json:"idempotent"`
	// action
	Action Executor `json:"action"`
	// result
	Schema         json.RawMessage         `json:"json_schema,omitempty"`
	ResultValidate jsonschema.ValidateFunc `json:"-"`
	Payload        interface{}             `json:"payload,omitempty"` // deprecated, kept for UI backwards compatibility
	Output         interface{}             `json:"output,omitempty"`
	Metadata       interface{}             `json:"metadata,omitempty"`
	Children       []interface{}           `json:"children,omitempty"`
	Error          string                  `json:"error,omitempty"`
	State          string                  `json:"state,omitempty"`
	// hints about ETA latency, async, for retrier to define strategy
	// how often VS how many times
	RetryPattern string    `json:"retry_pattern,omitempty"` // seconds, minutes, hours
	TryCount     int       `json:"try_count,omitempty"`
	MaxRetries   int       `json:"max_retries,omitempty"`
	LastRun      time.Time `json:"last_run,omitempty"`

	// flow control
	Dependencies []string     `json:"dependencies,omitempty"`
	CustomStates []string     `json:"custom_states,omitempty"`
	Conditions   []*Condition `json:"conditions,omitempty"`

	// loop
	ForEach         string          `json:"foreach,omitempty"`        // "parent" step: expression for list of items
	ChildrenSteps   []string        `json:"children_steps,omitempty"` // list of children names
	ChildrenStepMap map[string]bool `json:"children_steps_map,omitempty"`
	Item            interface{}     `json:"item,omitempty"` // "child" step: item value, issued from foreach

	Resources []string `json:"resources"` // resource limits to enforce
	// contains filtered or unexported fields
}

Step describes one unit of work within a task, and its dependency to other steps a step contains an action that makes use of an available executor, with a specific parameter set The result of a step is stored as its output, and can be validated with json schema Any error and metadata returned by the step's executor will also be stored, resulting in a state The state of a step can be customized by the author of a template, to account for business-specific outcomes (eg. a 404 needn't be an error, it can be called NOT_FOUND and determine execution flow without blocking). Through the "foreach" parameter, a step can be configured to spawn sub-steps for a list of items: the result of such a step will be the collection of results of all sub-steps, which can be fed into another "foreach" step A step can be configured to evaluate "conditions" before and after the action is performed:

• a "skip" condition will be run before and might determine that the step's action can be skipped entirely
• a "check" condition will be run after the action, and can control execution flow by examining the step's result and modifying step states through the entire task's resolution

func (*Step) ExecutorMetadata

func (st *Step) ExecutorMetadata() json.RawMessage

ExecutorMetadata returns the step's runner metadata schema

func (*Step) IsChild

func (st *Step) IsChild() bool

IsChild asserts that Step was spawned by a foreach step

func (*Step) IsFinal

func (st *Step) IsFinal() bool

IsFinal asserts that Step is in a final step (not to be run again)

func (*Step) IsRetriable

func (st *Step) IsRetriable() bool

IsRetriable asserts that Step is elligible for retry

func (*Step) IsRunnable

func (st *Step) IsRunnable() bool

IsRunnable asserts that Step is in a runnable state

func (*Step) ValidAndNormalize

func (st *Step) ValidAndNormalize(name string, baseConfigs map[string]json.RawMessage, steps map[string]*Step) error

ValidAndNormalize asserts that a step carries correct configuration - checks that executor is registered - validates retry pattern - validates custom states for the step (no collisions with builtin states) - validates conditions - validates the provided json schema for result validation - checks dependency declaration against the task's execution tree