multistep

Documentation

Overview

multistep is a library for building up complex actions using individual, discrete steps.

Index

• Constants
• func DebugPauseDefault(loc DebugLocation, name string, state StateBag)
• type BasicRunner
  • func (b *BasicRunner) Run(ctx context.Context, state StateBag)
• type BasicStateBag
  • func (b *BasicStateBag) Get(k string) interface{}
  • func (b *BasicStateBag) GetOk(k string) (interface{}, bool)
  • func (b *BasicStateBag) Put(k string, v interface{})
  • func (b *BasicStateBag) Remove(k string)
• type DebugLocation
• type DebugPauseFn
• type DebugRunner
  • func (r *DebugRunner) Run(ctx context.Context, state StateBag)
• type Runner
• type StateBag
• type Step
  • func If(on bool, step Step) Step
• type StepAction
  • func (a StepAction) String() string
• type StepWrapper

Constants

const StateCancelled = "cancelled"

This is the key set in the state bag when using the basic runner to signal that the step sequence was cancelled.

const StateHalted = "halted"

This is the key set in the state bag when a step halted the sequence.

Functions

func DebugPauseDefault

func DebugPauseDefault(loc DebugLocation, name string, state StateBag)

DebugPauseDefault is the default pause function when using the DebugRunner if no PauseFn is specified. It outputs some information to stderr about the step and waits for keyboard input on stdin before continuing.

Types

type BasicRunner

type BasicRunner struct {
	// Steps is a slice of steps to run. Once set, this should _not_ be
	// modified.
	Steps []Step
	// contains filtered or unexported fields
}

BasicRunner is a Runner that just runs the given slice of steps.

func (*BasicRunner) Run

func (b *BasicRunner) Run(ctx context.Context, state StateBag)

type BasicStateBag

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

BasicStateBag implements StateBag by using a normal map underneath protected by a RWMutex.

func (*BasicStateBag) Get

func (b *BasicStateBag) Get(k string) interface{}

func (*BasicStateBag) GetOk

func (b *BasicStateBag) GetOk(k string) (interface{}, bool)

func (*BasicStateBag) Put

func (b *BasicStateBag) Put(k string, v interface{})

func (*BasicStateBag) Remove

func (b *BasicStateBag) Remove(k string)

type DebugLocation

type DebugLocation uint

DebugLocation is the location where the pause is occurring when debugging a step sequence. "DebugLocationAfterRun" is after the run of the named step. "DebugLocationBeforeCleanup" is before the cleanup of the named step.

const (
	DebugLocationAfterRun DebugLocation = iota
	DebugLocationBeforeCleanup
)

type DebugPauseFn

type DebugPauseFn func(DebugLocation, string, StateBag)

DebugPauseFn is the type signature for the function that is called whenever the DebugRunner pauses. It allows the caller time to inspect the state of the multi-step sequence at a given step.

type DebugRunner

type DebugRunner struct {
	// Steps is the steps to run. These will be run in order.
	Steps []Step

	// PauseFn is the function that is called whenever the debug runner
	// pauses. The debug runner continues when this function returns.
	// The function is given the state so that the state can be inspected.
	PauseFn DebugPauseFn
	// contains filtered or unexported fields
}

DebugRunner is a Runner that runs the given set of steps in order, but pauses between each step until it is told to continue.

func (*DebugRunner) Run

func (r *DebugRunner) Run(ctx context.Context, state StateBag)

type Runner

type Runner interface {
	// Run runs the steps with the given initial state.
	Run(context.Context, StateBag)
}

Runner is a thing that runs one or more steps.

type StateBag

type StateBag interface {
	Get(string) interface{}
	GetOk(string) (interface{}, bool)
	Put(string, interface{})
	Remove(string)
}

StateBag holds the state that is used by the Runner and Steps. The StateBag implementation must be safe for concurrent access.

type Step

type Step interface {
	// Run is called to perform the action. The passed through context will be
	// cancelled when the runner is cancelled. The second parameter is a "state
	// bag" of untyped things. Please be very careful about type-checking the
	// items in this bag.
	//
	// The return value determines whether multi-step sequences continue
	// or should halt.
	Run(context.Context, StateBag) StepAction

	// Cleanup is called in reverse order of the steps that have run
	// and allow steps to clean up after themselves. Do not assume if this
	// ran that the entire multi-step sequence completed successfully. This
	// method can be ran in the face of errors and cancellations as well.
	//
	// The parameter is the same "state bag" as Run, and represents the
	// state at the latest possible time prior to calling Cleanup.
	Cleanup(StateBag)
}

Step is a single step that is part of a potentially large sequence of other steps, responsible for performing some specific action.

func If

func If(on bool, step Step) Step

if returns step only if on is true.

type StepAction

type StepAction uint

A StepAction determines the next step to take regarding multi-step actions.

const (
	ActionContinue StepAction = iota
	ActionHalt
)

func (StepAction) String

func (a StepAction) String() string

Implement the stringer interface; useful for testing.

type StepWrapper

type StepWrapper interface {
	// InnerStepName should return the human readable name of the wrapped step.
	InnerStepName() string
}

StepWrapper is an interface that wrapped steps can implement to expose their inner step names to the debug runner.