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, executedSteps map[string]bool)
• func RegisterRunner(name string, r Runner) error
• func Run(st *Step, baseConfig map[string]json.RawMessage, stepValues *values.Values, ...)
• func ValidCondition(sc *condition.Condition, stepName string, steps map[string]*Step) error
• type Context
• type Runner
• type StateSetter
• type Step
  • func (st *Step) CheckIfValidState() (bool, error)
  • func (st *Step) ExecutorMetadata() json.RawMessage
  • func (st *Step) GetConditions() ([]*condition.Condition, error)
  • func (st *Step) GetCustomStates() ([]string, error)
  • func (st *Step) GetPreHook() (*executor.Executor, error)
  • 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
  • func (st *Step) ValidAndNormalizeNewStep() error

Constants

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

	ForEachStrategyParallel = "parallel"
	ForEachStrategySequence = "sequence"
)

retry patterns for a step

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

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

possible states of a step

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, executedSteps map[string]bool)

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, stepValues *values.Values, stepChan chan<- *Step, wg *sync.WaitGroup, shutdownCtx context.Context)

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 shutdownCtx context is provided to interrupt execution in flight values IS NOT CONCURRENT SAFE, DO NOT SHARE WITH OTHER GOROUTINES

func ValidCondition

func ValidCondition(sc *condition.Condition, stepName string, steps map[string]*Step) error

ValidCondition asserts that the definition for a StepCondition is valid

Types

type Context

type Context struct {
	RequesterUsername string    `json:"requester_username"`
	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 Runner

type Runner interface {
	Exec(stepName string, baseConfig json.RawMessage, config json.RawMessage, ctx interface{}) (interface{}, interface{}, map[string]string, error)
	ValidConfig(baseConfig json.RawMessage, config json.RawMessage) error
	Context(stepName string) interface{}
	Resources(baseConfig json.RawMessage, config json.RawMessage) []string
	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.Executor  `json:"action"`
	PreHook *executor.Executor `json:"pre_hook,omitempty"`
	// result
	Schema         json.RawMessage         `json:"json_schema,omitempty"`
	ResultValidate jsonschema.ValidateFunc `json:"-"`
	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"`
	ExecutionDelay time.Duration `json:"execution_delay,omitempty"`

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

	// loop
	ForEach         string          `json:"foreach,omitempty"` // "parent" step: expression for list of items
	ForEachStrategy string          `json:"foreach_strategy"`
	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

	Tags map[string]string `json:"tags"`
	// 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) CheckIfValidState

func (st *Step) CheckIfValidState() (bool, error)

func (*Step) ExecutorMetadata

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

ExecutorMetadata returns the step's runner metadata schema

func (*Step) GetConditions

func (st *Step) GetConditions() ([]*condition.Condition, error)

GetConditions returns the list of conditions of this step resolved (functions included)

func (*Step) GetCustomStates

func (st *Step) GetCustomStates() ([]string, error)

GetCustomStates returns the list of custom states of the Step (functions included)

func (*Step) GetPreHook

func (st *Step) GetPreHook() (*executor.Executor, error)

GetPreHook returns the prehook that need to be executed (function included)

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 eligible 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

func (*Step) ValidAndNormalizeNewStep

func (st *Step) ValidAndNormalizeNewStep() error

ValidAndNormalizeNewStep will validate that a given step doesn't have extragenous fields defined when coming from a task_template.