framework

Documentation

Index

• func BuildSubstitutionFunction(metadata map[string]interface{}, resources map[string]OutputLookupFunc) func(string) (string, error)
• func DefaultUnEscaper(original string) (string, error)
• func OverrideMapInMap(input map[string]interface{}, overrides map[string]interface{}) (map[string]interface{}, error)
• func OverridePathInMap(input map[string]interface{}, path []string, isDelete bool, value interface{}) (map[string]interface{}, error)
• func ParseDotPathParts(input string) []string
• func SplitRefParts(ref string) []string
• func Substitute(source interface{}, inner func(string) (string, error)) (interface{}, error)
• func SubstituteString(src string, inner func(string) (string, error)) (string, error)
• type NoExtras
• type OutputLookupFunc
• type ResourceUid
  • func NewResourceUid(workloadName string, resName string, resType string, resClass *string, ...) ResourceUid
  • func (r ResourceUid) Class() string
  • func (r ResourceUid) Id() string
  • func (r ResourceUid) Type() string
• type ScoreResourceState
  • func (s *ScoreResourceState[ResourceExtras]) OutputLookup(keys ...string) (interface{}, error)
• type ScoreWorkloadState
• type State
  • func (s *State[StateExtras, WorkloadExtras, ResourceExtras]) GetResourceOutputForWorkload(workloadName string) (map[string]OutputLookupFunc, error)
  • func (s *State[StateExtras, WorkloadExtras, ResourceExtras]) GetSortedResourceUids() ([]ResourceUid, error)
  • func (s *State[StateExtras, WorkloadExtras, ResourceExtras]) WithPrimedResources() (*State[StateExtras, WorkloadExtras, ResourceExtras], error)
  • func (s *State[StateExtras, WorkloadExtras, ResourceExtras]) WithWorkload(spec *score.Workload, filePath *string, extras WorkloadExtras) (*State[StateExtras, WorkloadExtras, ResourceExtras], error)
• type Substituter
  • func (s *Substituter) Substitute(source interface{}) (interface{}, error)
  • func (s *Substituter) SubstituteString(src string) (string, error)

Functions

func BuildSubstitutionFunction

func BuildSubstitutionFunction(metadata map[string]interface{}, resources map[string]OutputLookupFunc) func(string) (string, error)

func DefaultUnEscaper

func DefaultUnEscaper(original string) (string, error)

func OverrideMapInMap

func OverrideMapInMap(input map[string]interface{}, overrides map[string]interface{}) (map[string]interface{}, error)

OverrideMapInMap will take in a decoded json or yaml struct and merge an override map into it. Any maps are merged together, other value types are replaced. Nil values will delete overridden keys or otherwise are ignored. This returns a shallow copy of the map in a copy-on-write way, so only modified elements are copied.

func OverridePathInMap

func OverridePathInMap(input map[string]interface{}, path []string, isDelete bool, value interface{}) (map[string]interface{}, error)

OverridePathInMap will take in a decoded json or yaml struct and override a particular path within it with either a new value or deletes it. This returns a shallow copy of the map in a copy-on-write way, so only modified elements are copied.

func ParseDotPathParts

func ParseDotPathParts(input string) []string

ParseDotPathParts will parse a common .-separated override path into path elements to traverse.

func SplitRefParts

func SplitRefParts(ref string) []string

func Substitute

func Substitute(source interface{}, inner func(string) (string, error)) (interface{}, error)

Substitute does the same thing as SubstituteString but recursively through a map. It returns a copy of the original map.

func SubstituteString

func SubstituteString(src string, inner func(string) (string, error)) (string, error)

SubstituteString replaces all matching '${...}' templates in a source string with whatever is returned from the inner function. Double $'s are unescaped using DefaultUnEscaper.

Types

type NoExtras

type NoExtras struct {
}

NoExtras can be used in place of the state or workload extras if no additional fields are needed.

type OutputLookupFunc

type OutputLookupFunc func(keys ...string) (interface{}, error)

type ResourceUid

type ResourceUid string

ResourceUid is a string for a unique resource identifier. This must be constructed through NewResourceUid

func NewResourceUid

func NewResourceUid(workloadName string, resName string, resType string, resClass *string, resId *string) ResourceUid

NewResourceUid constructs a new ResourceUid string.

func (ResourceUid) Class

func (r ResourceUid) Class() string

Class returns the class of the resource, defaulted to "default"

func (ResourceUid) Id

func (r ResourceUid) Id() string

Id returns the id of the resource, either <workload>.<name> or <id> if id is specified

func (ResourceUid) Type

func (r ResourceUid) Type() string

Type returns the type of the resource

type ScoreResourceState

type ScoreResourceState[ResourceExtras any] struct {
	// Guid is a uuid assigned to this "instance" of the resource.
	Guid string `yaml:"guid"`
	// Type is the resource type.
	Type string `yaml:"type"`
	// Class is the resource class or 'default' if not provided.
	Class string `yaml:"class"`
	// Id is the generated id for the resource, either <workload>.<resName> or <id>. This is tracked so that
	// we can deduplicate and work out where a resource came from.
	Id string `yaml:"id"`

	Metadata map[string]interface{} `yaml:"metadata"`
	Params   map[string]interface{} `yaml:"params"`
	// SourceWorkload holds the workload name that had the best definition for this resource. "best" is either the
	// first one or the one with params defined.
	SourceWorkload string `yaml:"source_workload"`

	// ProvisionerUri is the resolved provisioner uri that should be found in the config. This is tracked so that
	// we identify which provisioner was used for a particular instance of the resource.
	ProvisionerUri string `yaml:"provisioner"`
	// State is the internal state local to this resource. It will be persisted to disk when possible.
	State map[string]interface{} `yaml:"state"`

	// Outputs is the current set of outputs for the resource. This is the output of calling the provider. It may contain
	// secrets so be careful when persisting this to disk.
	Outputs map[string]interface{} `yaml:"outputs,omitempty"`
	// OutputLookupFunc is function that allows certain in-process providers to defer any output generation. If this is
	// not provided, it will fall back to using what's in the outputs.
	OutputLookupFunc OutputLookupFunc `yaml:"-"`

	// Extras stores any implementation specific extras needed for this resource.
	Extras ResourceExtras `yaml:",inline"`
}

ScoreResourceState is the state stored and tracked for each resource.

func (*ScoreResourceState[ResourceExtras]) OutputLookup

func (s *ScoreResourceState[ResourceExtras]) OutputLookup(keys ...string) (interface{}, error)

OutputLookup is a function which can traverse an outputs tree to find a resulting key, this defers to the embedded output function if it exists.

type ScoreWorkloadState

type ScoreWorkloadState[WorkloadExtras any] struct {
	// Spec is the final score spec after all overrides and images have been set. This is a validated score file.
	Spec score.Workload `yaml:"spec"`
	// File is the source score file if known.
	File *string `yaml:"file,omitempty"`
	// Extras stores any implementation specific extras needed for this workload.
	Extras WorkloadExtras `yaml:",inline"`
}

ScoreWorkloadState is the state stored per workload. We store the recorded workload spec, the file it came from if necessary to resolve relative references, and any extras for this implementation.

type State

type State[StateExtras any, WorkloadExtras any, ResourceExtras any] struct {
	Workloads   map[string]ScoreWorkloadState[WorkloadExtras]      `yaml:"workloads"`
	Resources   map[ResourceUid]ScoreResourceState[ResourceExtras] `yaml:"resources"`
	SharedState map[string]interface{}                             `yaml:"shared_state"`
	Extras      StateExtras                                        `yaml:",inline"`
}

State is the mega-structure that contains the state of our workload specifications and resources. Score specs are added to this structure and it stores the current resource set. Extra implementation specific fields are supported by the generic parameters.

func (*State[StateExtras, WorkloadExtras, ResourceExtras]) GetResourceOutputForWorkload

func (s *State[StateExtras, WorkloadExtras, ResourceExtras]) GetResourceOutputForWorkload(workloadName string) (map[string]OutputLookupFunc, error)

GetResourceOutputForWorkload returns an output function per resource name in the given workload. This is for passing into the compose translation context to resolve placeholder references. This does not modify the state.

func (*State[StateExtras, WorkloadExtras, ResourceExtras]) GetSortedResourceUids

func (s *State[StateExtras, WorkloadExtras, ResourceExtras]) GetSortedResourceUids() ([]ResourceUid, error)

GetSortedResourceUids returns a topological sorting of the resource uids. The output order is deterministic and ensures that any resource output placeholder statements are strictly evaluated after their referenced resource. If cycles are detected an error will be thrown.

func (*State[StateExtras, WorkloadExtras, ResourceExtras]) WithPrimedResources

func (s *State[StateExtras, WorkloadExtras, ResourceExtras]) WithPrimedResources() (*State[StateExtras, WorkloadExtras, ResourceExtras], error)

WithPrimedResources returns a new copy of State with all workload resources resolved to at least their initial type, class and id. New resources will have an empty provider set. Existing resources will not be touched. This is not a deep copy, but any writes are executed in a copy-on-write manner to avoid modifying the source.

func (*State[StateExtras, WorkloadExtras, ResourceExtras]) WithWorkload

func (s *State[StateExtras, WorkloadExtras, ResourceExtras]) WithWorkload(spec *score.Workload, filePath *string, extras WorkloadExtras) (*State[StateExtras, WorkloadExtras, ResourceExtras], error)

WithWorkload returns a new copy of State with the workload added, if the workload already exists with the same name then it will be replaced. This is not a deep copy, but any writes are executed in a copy-on-write manner to avoid modifying the source.

type Substituter

type Substituter struct {
	Replacer  func(string) (string, error)
	UnEscaper func(string) (string, error)
}

A Substituter is a type that supports substitutions of $-sign placeholders in strings. This detects and replaces patterns like: fizz ${var} buzz while supporting custom un-escaping of patterns like $$ and $${var}. The Replacer function is _required_ and the substituter will not function without it, but the UnEscaper is optional and will default to simply replacing sequences of $$ with a $. Overriding the UnEscaper may be necessary if non default behavior is required.

func (*Substituter) Substitute

func (s *Substituter) Substitute(source interface{}) (interface{}, error)

func (*Substituter) SubstituteString

func (s *Substituter) SubstituteString(src string) (string, error)