plan

package
v0.2.5 Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2021 License: Apache-2.0 Imports: 19 Imported by: 4

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var EmptyState = State(nil)

EmptyState is the empty State.

Functions

func DependOn 

func DependOn(dep string, deps ...string) func(*addOptions)

DependOn expresses dependency between Resources.

func EqualPlans 

func EqualPlans(p1, p2 Plan) bool

EqualPlans Compares Plans for equality; not currently used except in tests

func ParamString added in v0.0.4 

func ParamString(template string, params ...*string) fmt.Stringer

Types

type Builder 

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

Builder is a plan builder.

func NewBuilder 

func NewBuilder(idSegments ...string) *Builder

NewBuilder creates a new Builder.

func (*Builder) AddResource 

func (b *Builder) AddResource(id string, r Resource, options ...func(*addOptions)) *Builder

AddResource adds a resource to the plan.

func (*Builder) Errors 

func (b *Builder) Errors() []error

Errors returns the errors that occurred during the build. The user is expected to check the return value of this function before using the Plan.

func (*Builder) Plan 

func (b *Builder) Plan() (Plan, error)

Plan returns the built Plan.

type Diff 

type Diff struct {
	CurrentState    State
	InvalidatedDeps []Resource
}

Diff represents the motivation for performing an Apply; a cached version of the current State and any dependee Resources that have been invalidated.

func EmptyDiff 

func EmptyDiff() Diff

EmptyDiff returns a default Diff value

type InvalidityReason 

type InvalidityReason int

InvalidityReason describes why a resource isn't valid 

const (
	None InvalidityReason = iota
	ApplyError
	QueryError
	ChildInvalid
	ChildInconclusive
	DependencyInvalid
	DependencyInconclusive
)

func (InvalidityReason) MarshalJSON 

func (r InvalidityReason) MarshalJSON() ([]byte, error)

MarshalJSON marshals the enum as a quoted json string

func (InvalidityReason) String 

func (r InvalidityReason) String() string

func (*InvalidityReason) UnmarshalJSON 

func (r *InvalidityReason) UnmarshalJSON(b []byte) error

UnmarshalJSON unmashals a quoted json string to the enum value

type LocalRunner 

type LocalRunner struct{}

LocalRunner is a runner executing commands on the same host it's running on.

func (*LocalRunner) RunCommand 

func (r *LocalRunner) RunCommand(ctx context.Context, cmd string, stdin io.Reader) (stdouterr string, err error)

RunCommand implements Runner.

type Plan 

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

Plan is a succession of Steps to produce a desired outcome.

func NewPlanFromJSON 

func NewPlanFromJSON(r io.Reader) (Plan, error)

NewPlanFromJSON Reads a Plan from JSON via State

func (*Plan) Apply 

func (p *Plan) Apply(ctx context.Context, r Runner, diff Diff) (bool, error)

Apply applies this plan. The diff contains:

  1. either a state roll-up of contained resource states or nil
  2. a set of updated resources (of which only direct dependencies will be handed to individual resources

func (*Plan) ApplyResourceGraph 

func (p *Plan) ApplyResourceGraph(ctx context.Context, resourceIDs []string, diff *Diff, runner Runner) map[string]ValidityTree

func (*Plan) EnsureResourceValid 

func (p *Plan) EnsureResourceValid(ctx context.Context, resourceID string, runner Runner) ValidityTree

EnsureResourceValid ensures that a resource is valid by recursively checking dependencies for validity and re-applying as necessary to achieve it

func (*Plan) EnsureResourcesValid 

func (p *Plan) EnsureResourcesValid(ctx context.Context, resourceIDs []string, runner Runner) map[string]ValidityTree

EnsureResourcesValid ensures that a set of resources is valid by recursively checking dependencies for validity and re-applying as necessary to achieve it; returns only results for the top-level resources as results for underlying resources will roll up

func (*Plan) GetResource 

func (p *Plan) GetResource(name string) Resource

func (*Plan) QueryState 

func (p *Plan) QueryState(ctx context.Context, runner Runner) (State, error)

QueryState implements Resource

func (*Plan) SetUndoCondition 

func (p *Plan) SetUndoCondition(checkFun func(Runner, State) bool)

SetUndoCondition sets the function that determines if the Plan will allow undoing its actions

func (*Plan) State 

func (p *Plan) State() State

State implements Resource

func (*Plan) ToDOT 

func (p *Plan) ToDOT() string

ToDOT translates a Plan into DOT output

func (*Plan) ToHumanReadableJSON 

func (p *Plan) ToHumanReadableJSON() string

ToHumanReadableJSON translates a Plan into JSON using State as an intermediate target

func (*Plan) ToJSON 

func (p *Plan) ToJSON() string

ToJSON translates a Plan into JSON using State as an intermediate target

func (*Plan) ToState 

func (p *Plan) ToState() State

ToState translates a Plan into a State

func (*Plan) Undo 

func (p *Plan) Undo(ctx context.Context, runner Runner, current State) error

Undo implements Resource

type Resource 

type Resource interface {
	// State returns the state that this step will realize when applied.
	State() State
	// QueryState returns the current state of this step. For instance, if the step
	// describes the installation of a package, QueryState will return if the
	// package is actually installed and its version.
	QueryState(ctx context.Context, runner Runner) (State, error)

	// Apply this step and indicate whether downstream resources should be re-applied
	Apply(ctx context.Context, runner Runner, diff Diff) (propagate bool, err error)
	// Undo this step.
	Undo(ctx context.Context, runner Runner, current State) error
}

Resource is an atomic step of the plan.

func RegisterResource 

func RegisterResource(r Resource) Resource

RegisterResource is used to map a Resource type name to its type information for deserialization

type RunError 

type RunError struct {
	ExitCode int
}

func (*RunError) Error 

func (e *RunError) Error() string

type Runner 

type Runner interface {
	// RunCommand runs a command in a shell. This means cmd can be more than one
	// single command, it can be a full bourne shell script.
	RunCommand(ctx context.Context, cmd string, stdin io.Reader) (stdouterr string, err error)
}

Runner is something that can realise a step.

type State 

type State map[string]interface{}

State is a collection of (key, value) pairs describing unequivocally a step and, by extension, a plan.

func NewState 

func NewState() State

NewState creates an empty set of parameters.

func NewStateFromJSON 

func NewStateFromJSON(r io.Reader) (State, error)

NewStateFromJSON creates State from JSON.

func (State) Bool 

func (s State) Bool(path string) bool

Bool retrieves a boolean parameter.

func (State) Diff 

func (s State) Diff(t State) (string, error)

Diff returns human-readable diffs from one State to another.

func (State) Equal 

func (s State) Equal(other State) bool

Equal returns true if two States are equal. Note that State deserialised from JSON can contain map types which do not compare equal.

func (State) Get 

func (s State) Get(path string) (interface{}, error)

Get retrieves a parameter.

func (State) GetBool 

func (s State) GetBool(path string) (bool, error)

GetBool retrieves a boolean parameter.

func (State) GetNumber 

func (s State) GetNumber(path string) (float64, error)

GetNumber retrieves a number parameter.

func (State) GetObject 

func (s State) GetObject(path string) (State, error)

GetObject retrieves a object property.

func (State) GetString 

func (s State) GetString(path string) (string, error)

GetString retrieves a string parameter.

func (State) IsEmpty 

func (s State) IsEmpty() bool

IsEmpty returns true if the state doesn't contain any key.

func (State) Merge 

func (s State) Merge(a State)

Merge merges two States.

func (State) Number 

func (s State) Number(path string) float64

Number retrieves a number parameter.

func (State) Object 

func (s State) Object(path string) State

Object retrieves an object parameter.

func (State) Set 

func (s State) Set(path string, v interface{})

Set sets a property.

func (State) SetBool 

func (s State) SetBool(path string, b bool)

SetBool sets a boolean property.

func (State) SetNumber 

func (s State) SetNumber(path string, f float64)

SetNumber sets a number property.

func (State) SetObject 

func (s State) SetObject(path string, o State)

SetObject sets an object property.

func (State) SetString 

func (s State) SetString(path string, str string)

SetString sets a string property.

func (State) String 

func (s State) String(path string) string

String retrieves a string parameter.

func (State) ToJSON 

func (s State) ToJSON() string

ToJSON serialises a State into JSON

type Validity 

type Validity int

Validity is a Resource's measured "goodness" Either 'Valid', 'Invalid', or 'Inconclusive'. The state is 'Inconclusive' if a state query 

fails in the validity tree

const (
	Valid Validity = iota
	Invalid
	Inconclusive
)

func (Validity) MarshalJSON 

func (v Validity) MarshalJSON() ([]byte, error)

MarshalJSON marshals the enum as a quoted json string

func (Validity) String 

func (v Validity) String() string

Functions to translate enums to/from strings for JSON

func (*Validity) UnmarshalJSON 

func (v *Validity) UnmarshalJSON(b []byte) error

UnmarshalJSON unmashals a quoted json string to the enum value

type ValidityTree 

type ValidityTree struct {
	ResourceID     string           `json:"resource"`
	ValidityStatus Validity         `json:"status,omitempty"`
	Reason         InvalidityReason `json:"reason,omitempty"`
	Updated        bool             `json:"updated,omitempty"`
	ObservedError  string           `json:"error,omitempty"`
	Dependencies   []ValidityTree   `json:"dependencies,omitempty"`
	Children       []ValidityTree   `json:"children,omitempty"`
}

ValidityTree is the hierarchical explanation for why a resource is Valid, Invalid, or Inconclusive. Each ValidityTree contains a set of dependency ValidityTrees showing how the Validity status rolls up

func (ValidityTree) Error 

func (v ValidityTree) Error() string

func (ValidityTree) ObservedErrorString 

func (v ValidityTree) ObservedErrorString() string

func (ValidityTree) ToExplanation 

func (v ValidityTree) ToExplanation() ValidityTree

ToExplanation removes all VALID resource dependencies before producing JSON to make it more clear what went wrong. It also only shows full data for a tree the first time it's resource is seen.

func (ValidityTree) ToJSON 

func (v ValidityTree) ToJSON() string

ToJSON returns a JSON representation of the ValidityTree.

Source Files

View all Source files

Directories

Path Synopsis
runners
ssh
sudo

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.