get.porter.sh/porter@v1.3.0/pkg/manifest/manifest.go

package manifest

import (
	"context"
	"errors"
	"fmt"
	"io"
	"net/http"
	"path"
	"reflect"
	"regexp"
	"sort"
	"strings"

	"get.porter.sh/porter/pkg/cnab"
	"get.porter.sh/porter/pkg/config"
	"get.porter.sh/porter/pkg/experimental"
	"get.porter.sh/porter/pkg/portercontext"
	"get.porter.sh/porter/pkg/schema"
	"get.porter.sh/porter/pkg/tracing"
	"get.porter.sh/porter/pkg/yaml"
	"github.com/Masterminds/semver/v3"
	"github.com/cbroglie/mustache"
	"github.com/cnabio/cnab-go/bundle"
	"github.com/cnabio/cnab-go/bundle/definition"
	"github.com/dustin/go-humanize"
	"github.com/hashicorp/go-multierror"
	"github.com/opencontainers/go-digest"
	"go.opentelemetry.io/otel/attribute"
)

const (
	invalidStepErrorFormat = "validation of action \"%s\" failed: %w"

	// SchemaTypeBundle is the default schemaType value for Bundle resources
	SchemaTypeBundle = "Bundle"

	// TemplateDelimiterPrefix must be present at the beginning of any porter.yaml
	// that wants to use ${} as the template delimiter instead of the mustache
	// default of {{}}.
	TemplateDelimiterPrefix = "{{=${ }=}}\n"
)

var (
	// TODO(PEP003): Version 1.1.0 is behind the DependenciesV2 feature flag. We update the supported versions later
	// when validating a bundle and only allow that version when it is enabled.
	// The default version remains on the last stable version 1.0.1.
	// When the schema version is stable and not behind a feature flag, we can update the supported versions and default version.

	// SupportedSchemaVersions is the Porter manifest (porter.yaml) schema
	// versions supported by this version of Porter, specified as a semver range.
	// When the Manifest structure is changed, this field should be incremented.
	SupportedSchemaVersions, _ = semver.NewConstraint("1.0.0-alpha.1 || 1.0.0 - 1.0.1")

	// DefaultSchemaVersion is the most recently supported schema version.
	// When the Manifest structure is changed, this field should be incremented.
	DefaultSchemaVersion = semver.MustParse("1.0.1")
)

type Manifest struct {
	// ManifestPath is location to the original, user-supplied manifest, such as the path on the filesystem or a url
	ManifestPath string `yaml:"-"`

	// TemplateVariables are the variables used in the templating, e.g. bundle.parameters.NAME, or bundle.outputs.NAME
	TemplateVariables []string `yaml:"-"`

	// SchemaType indicates the type of resource contained in an imported file.
	SchemaType string `yaml:"schemaType,omitempty"`

	// SchemaVersion is a semver value that indicates which version of the porter.yaml schema is used in the file.
	SchemaVersion string `yaml:"schemaVersion"`
	Name          string `yaml:"name,omitempty"`
	Description   string `yaml:"description,omitempty"`
	Version       string `yaml:"version,omitempty"`

	Maintainers []MaintainerDefinition `yaml:"maintainers,omitempty"`

	// Registry is the OCI registry and org/subdomain for the bundle
	Registry string `yaml:"registry,omitempty"`

	// Reference is the optional, full bundle reference
	// in the format REGISTRY/NAME or REGISTRY/NAME:TAG
	Reference string `yaml:"reference,omitempty"`

	// DockerTag is the Docker tag portion of the published bundle
	// image and bundle.  It will only be set at time of publishing.
	DockerTag string `yaml:"-"`

	// Image is the name of the bundle image in the format REGISTRY/NAME:TAG
	// It doesn't map to any field in the manifest as it has been deprecated
	// and isn't meant to be user-specified
	Image string `yaml:"-"`

	// Dockerfile is the relative path to the Dockerfile template for the bundle image
	Dockerfile string `yaml:"dockerfile,omitempty"`

	Mixins []MixinDeclaration `yaml:"mixins,omitempty"`

	Install   Steps `yaml:"install"`
	Uninstall Steps `yaml:"uninstall"`
	Upgrade   Steps `yaml:"upgrade"`

	Custom                  CustomDefinitions                 `yaml:"custom,omitempty"`
	CustomActions           map[string]Steps                  `yaml:"-"`
	CustomActionDefinitions map[string]CustomActionDefinition `yaml:"customActions,omitempty"`

	StateBag     StateBag              `yaml:"state,omitempty"`
	Parameters   ParameterDefinitions  `yaml:"parameters,omitempty"`
	Credentials  CredentialDefinitions `yaml:"credentials,omitempty"`
	Dependencies Dependencies          `yaml:"dependencies,omitempty"`
	Outputs      OutputDefinitions     `yaml:"outputs,omitempty"`

	// ImageMap is a map of images referenced in the bundle. If an image relocation mapping is later provided, that
	// will be mounted at as a file at runtime to /cnab/app/relocation-mapping.json.
	ImageMap map[string]MappedImage `yaml:"images,omitempty"`

	Required []RequiredExtension `yaml:"required,omitempty"`
}

func (m *Manifest) Validate(ctx context.Context, cfg *config.Config) error {
	ctx, span := tracing.StartSpan(ctx)
	defer span.EndSpan()

	var result error

	err := m.validateMetadata(ctx, cfg)
	if err != nil {
		return err
	}

	err = m.SetDefaults()
	if err != nil {
		return span.Error(err)
	}

	if strings.ToLower(m.Dockerfile) == "dockerfile" {
		return span.Error(errors.New("Dockerfile template cannot be named 'Dockerfile' because that is the filename generated during porter build"))
	}

	if len(m.Mixins) == 0 {
		result = multierror.Append(result, errors.New("no mixins declared"))
	}

	if m.Install == nil {
		result = multierror.Append(result, errors.New("no install action defined"))
	}
	err = m.Install.Validate(m)
	if err != nil {
		result = multierror.Append(result, fmt.Errorf(invalidStepErrorFormat, "install", err))
	}

	if m.Uninstall == nil {
		result = multierror.Append(result, errors.New("no uninstall action defined"))
	}
	err = m.Uninstall.Validate(m)
	if err != nil {
		result = multierror.Append(result, fmt.Errorf(invalidStepErrorFormat, "uninstall", err))
	}

	if m.Upgrade != nil {
		err = m.Upgrade.Validate(m)
		if err != nil {
			result = multierror.Append(result, fmt.Errorf(invalidStepErrorFormat, "upgrade", err))
		}
	}

	for actionName, steps := range m.CustomActions {
		err := steps.Validate(m)
		if err != nil {
			result = multierror.Append(result, fmt.Errorf(invalidStepErrorFormat, actionName, err))
		}
	}

	for _, dep := range m.Dependencies.Requires {
		err = dep.Validate(cfg.Context)
		if err != nil {
			result = multierror.Append(result, err)
		}
	}

	for _, output := range m.Outputs {
		err = output.Validate()
		if err != nil {
			result = multierror.Append(result, err)
		}
	}

	for _, parameter := range m.Parameters {
		err = parameter.Validate()
		if err != nil {
			result = multierror.Append(result, err)
		}
	}

	for _, image := range m.ImageMap {
		err = image.Validate()
		if err != nil {
			result = multierror.Append(result, err)
		}
	}

	return span.Error(result)
}

func (m *Manifest) validateMetadata(ctx context.Context, cfg *config.Config) error {
	ctx, span := tracing.StartSpan(ctx)
	defer span.EndSpan()

	strategy := cfg.GetSchemaCheckStrategy(ctx)
	span.SetAttributes(attribute.String("schemaCheckStrategy", string(strategy)))

	if m.SchemaType == "" {
		m.SchemaType = SchemaTypeBundle
	} else if !strings.EqualFold(m.SchemaType, SchemaTypeBundle) {
		return span.Errorf("invalid schemaType %s, expected %s", m.SchemaType, SchemaTypeBundle)
	}

	// Check what the supported schema version is based on if depsv2 is enabled
	supportedVersions := SupportedSchemaVersions
	if cfg.IsFeatureEnabled(experimental.FlagDependenciesV2) {
		supportedVersions, _ = semver.NewConstraint("1.0.0-alpha.1 || 1.0.0 - 1.0.1 || 1.1.0")
	}

	if warnOnly, err := schema.ValidateSchemaVersion(strategy, supportedVersions, m.SchemaVersion, DefaultSchemaVersion); err != nil {
		if warnOnly {
			span.Warn(err.Error())
		} else {
			return span.Error(err)
		}
	}

	if m.Name == "" {
		return span.Error(errors.New("bundle name must be set"))
	}

	if m.Registry == "" && m.Reference == "" {
		return span.Error(errors.New("a registry or reference value must be provided"))
	}

	if m.Reference != "" && m.Registry != "" {
		span.Warnf("WARNING: both registry and reference were provided; "+
			"using the reference value of %s for the bundle reference\n", m.Reference)
	}

	// Allow for the user to have specified the version with a leading v prefix but save it as
	// proper semver
	if m.Version != "" {
		v, err := semver.NewVersion(m.Version)
		if err != nil {
			return span.Errorf("version %q is not a valid semver value: %w", m.Version, err)
		}
		m.Version = v.String()
	}
	return nil
}

var templatedOutputRegex = regexp.MustCompile(`^bundle\.outputs\.(.+)$`)

// getTemplateOutputName returns the output name from the template variable.
func (m *Manifest) getTemplateOutputName(value string) (string, bool) {
	matches := templatedOutputRegex.FindStringSubmatch(value)
	if len(matches) < 2 {
		return "", false
	}

	outputName := matches[1]
	return outputName, true
}

var templatedDependencyOutputRegex = regexp.MustCompile(`^bundle\.dependencies\.(.+).outputs.(.+)$`)

// getTemplateDependencyOutputName returns the dependency and output name from the
// template variable.
func (m *Manifest) getTemplateDependencyOutputName(value string) (string, string, bool) {
	matches := templatedDependencyOutputRegex.FindStringSubmatch(value)
	if len(matches) < 3 {
		return "", "", false
	}

	dependencyName := matches[1]
	outputName := matches[2]
	return dependencyName, outputName, true
}

var templatedDependencyShortOutputRegex = regexp.MustCompile(`^outputs.(.+)$`)

// getTemplateDependencyShortOutputName returns the dependency output name from the
// template variable.
func (m *Manifest) getTemplateDependencyShortOutputName(value string) (string, bool) {
	matches := templatedDependencyShortOutputRegex.FindStringSubmatch(value)
	if len(matches) < 2 {
		return "", false
	}

	outputName := matches[1]
	return outputName, true
}

var templatedParameterRegex = regexp.MustCompile(`^bundle\.parameters\.(.+)$`)

// GetTemplateParameterName returns the parameter name from the template variable.
func (m *Manifest) GetTemplateParameterName(value string) (string, bool) {
	matches := templatedParameterRegex.FindStringSubmatch(value)
	if len(matches) < 2 {
		return "", false
	}

	parameterName := matches[1]
	return parameterName, true
}

// GetTemplatedOutputs returns the output definitions for any bundle level outputs
// that have been templated, keyed by the output name.
func (m *Manifest) GetTemplatedOutputs() OutputDefinitions {
	outputs := make(OutputDefinitions, len(m.TemplateVariables))
	for _, tmplVar := range m.TemplateVariables {
		if name, ok := m.getTemplateOutputName(tmplVar); ok {
			outputDef, ok := m.Outputs[name]
			if !ok {
				// Only return bundle level definitions
				continue
			}
			outputs[name] = outputDef
		}
	}
	return outputs
}

// GetTemplatedOutputs returns the output definitions for any bundle level outputs
// that have been templated, keyed by "DEPENDENCY.OUTPUT".
func (m *Manifest) GetTemplatedDependencyOutputs() DependencyOutputReferences {
	outputs := make(DependencyOutputReferences, len(m.TemplateVariables))
	for _, tmplVar := range m.TemplateVariables {
		if dep, output, ok := m.getTemplateDependencyOutputName(tmplVar); ok {
			ref := DependencyOutputReference{
				Dependency: dep,
				Output:     output,
			}
			outputs[ref.String()] = ref
		}
	}
	return outputs
}

// GetTemplatedParameters returns the output definitions for any bundle level outputs
// that have been templated, keyed by the output name.
func (m *Manifest) GetTemplatedParameters() ParameterDefinitions {
	parameters := make(ParameterDefinitions, len(m.TemplateVariables))
	for _, tmplVar := range m.TemplateVariables {
		if name, ok := m.GetTemplateParameterName(tmplVar); ok {
			parameterDef, ok := m.Parameters[name]
			if !ok {
				// Only return bundle level definitions
				continue
			}
			parameters[name] = parameterDef
		}
	}
	return parameters
}

// DetermineDependenciesExtensionUsed looks for how dependencies are used
// by the bundle and which version of the dependency extension can be used.
func (m *Manifest) DetermineDependenciesExtensionUsed() string {
	// Check if v2 deps are explicitly specified
	for _, ext := range m.Required {
		if ext.Name == cnab.DependenciesV2ExtensionShortHand ||
			ext.Name == cnab.DependenciesV2ExtensionKey {
			return cnab.DependenciesV2ExtensionKey
		}
	}

	// Check each dependency for use of v2 only features
	for _, dep := range m.Dependencies.Requires {
		if dep.UsesV2Features() {
			return cnab.DependenciesV2ExtensionKey
		}
	}

	// Check if the bundle declares that it can satisfy a v2 dependency
	if m.Dependencies.Provides != nil {
		return cnab.DependenciesV2ExtensionKey
	}

	if len(m.Dependencies.Requires) > 0 {
		// Dependencies are declared but only use v1 features
		return cnab.DependenciesV1ExtensionKey
	}

	// No dependencies are used at all
	return ""
}

type CustomDefinitions map[string]interface{}

func (cd *CustomDefinitions) UnmarshalYAML(unmarshal func(interface{}) error) error {
	raw, err := yaml.UnmarshalMap(unmarshal)
	if err != nil {
		return err
	}
	*cd = raw
	return nil
}

type DependencyOutputReference struct {
	Dependency string
	Output     string
}

func (r DependencyOutputReference) String() string {
	return fmt.Sprintf("%s.%s", r.Dependency, r.Output)
}

type DependencyOutputReferences map[string]DependencyOutputReference

// DependencyProvider specifies how the current bundle can be used to satisfy a dependency.
type DependencyProvider struct {
	// Interface declares the bundle interface that the current bundle provides.
	Interface InterfaceDeclaration `yaml:"interface,omitempty"`
}

// InterfaceDeclaration declares that the current bundle supports the specified bundle interface
// Reserved for future use. Right now we only use an interface id, but could support other fields later.
type InterfaceDeclaration struct {
	// ID is the URI of the interface that this bundle provides. Usually a well-known name defined by Porter or CNAB.
	ID string `yaml:"id,omitempty"`
}

// ParameterDefinitions allows us to represent parameters as a list in the YAML
// and work with them as a map internally
type ParameterDefinitions map[string]ParameterDefinition

func (pd ParameterDefinitions) MarshalYAML() (interface{}, error) {
	raw := make([]ParameterDefinition, 0, len(pd))

	for _, param := range pd {
		raw = append(raw, param)
	}

	return raw, nil
}

func (pd *ParameterDefinitions) UnmarshalYAML(unmarshal func(interface{}) error) error {
	var raw []ParameterDefinition
	err := unmarshal(&raw)
	if err != nil {
		return err
	}

	if *pd == nil {
		*pd = make(map[string]ParameterDefinition, len(raw))
	}

	for _, item := range raw {
		(*pd)[item.Name] = item
	}

	return nil
}

var _ bundle.Scoped = &ParameterDefinition{}

// ParameterDefinition defines a single parameter for a CNAB bundle
type ParameterDefinition struct {
	Name      string          `yaml:"name"`
	Sensitive bool            `yaml:"sensitive"`
	Source    ParameterSource `yaml:"source,omitempty"`

	// These fields represent a subset of bundle.Parameter as defined in cnabio/cnab-go,
	// minus the 'Description' field (definition.Schema's will be used) and `Definition` field
	ApplyTo     []string `yaml:"applyTo,omitempty"`
	Destination Location `yaml:",inline,omitempty"`

	definition.Schema `yaml:",inline"`

	// IsState identifies if the parameter was generated from a state variable
	IsState bool `yaml:"-"`
}

func (pd *ParameterDefinition) GetApplyTo() []string {
	return pd.ApplyTo
}

func (pd *ParameterDefinition) Validate() error {
	var result *multierror.Error

	if pd.Name == "" {
		result = multierror.Append(result, errors.New("parameter name is required"))
	}

	// Porter supports declaring a parameter of type: "file",
	// which we will convert to the appropriate bundle.Parameter type in adapter.go
	// Here, we copy the ParameterDefinition and make the same modification before validation
	pdCopy := pd.DeepCopy()
	if pdCopy.Type == "file" {
		if pd.Destination.Path == "" {
			result = multierror.Append(result, fmt.Errorf("no destination path supplied for parameter %s", pd.Name))
		}
		pdCopy.Type = "string"
		pdCopy.ContentEncoding = "base64"
	}

	// Validate the Parameter Definition schema itself
	if _, err := pdCopy.Schema.ValidateSchema(); err != nil {
		return multierror.Append(result, fmt.Errorf("encountered an error while validating definition for parameter %q: %w", pdCopy.Name, err))
	}

	if pdCopy.Default != nil {
		schemaValidationErrs, err := pdCopy.Schema.Validate(pdCopy.Default)
		if err != nil {
			result = multierror.Append(result, fmt.Errorf("encountered error while validating parameter %s: %w", pdCopy.Name, err))
		}
		for _, schemaValidationErr := range schemaValidationErrs {
			result = multierror.Append(result, fmt.Errorf("encountered an error validating the default value %v for parameter %q: %s", pdCopy.Default, pdCopy.Name, schemaValidationErr.Error))
		}
	}

	return result.ErrorOrNil()
}

// DeepCopy copies a ParameterDefinition and returns the copy
func (pd *ParameterDefinition) DeepCopy() *ParameterDefinition {
	p2 := *pd
	p2.ApplyTo = make([]string, len(pd.ApplyTo))
	copy(p2.ApplyTo, pd.ApplyTo)
	return &p2
}

// AppliesTo returns a boolean value specifying whether or not
// the Parameter applies to the provided action
func (pd *ParameterDefinition) AppliesTo(action string) bool {
	return bundle.AppliesTo(pd, action)
}

// exemptFromInstall returns true if a parameter definition:
//   - has an output source (which will not exist prior to install)
//   - doesn't already have applyTo specified
//   - doesn't have a default value
func (pd *ParameterDefinition) exemptFromInstall() bool {
	return pd.Source.Output != "" && pd.ApplyTo == nil && pd.Default == nil
}

// UpdateApplyTo updates a parameter definition's applyTo section
// based on the provided manifest
func (pd *ParameterDefinition) UpdateApplyTo(m *Manifest) {
	if pd.exemptFromInstall() {
		applyTo := []string{cnab.ActionUninstall}
		// The core action "Upgrade" is technically still optional
		// so only add it if it is declared in the manifest
		if m.Upgrade != nil {
			applyTo = append(applyTo, cnab.ActionUpgrade)
		}
		// Add all custom actions
		for action := range m.CustomActions {
			applyTo = append(applyTo, action)
		}
		sort.Strings(applyTo)
		pd.ApplyTo = applyTo
	}
}

type ParameterSource struct {
	Dependency string `yaml:"dependency,omitempty"`
	Output     string `yaml:"output"`
}

// CredentialDefinitions allows us to represent credentials as a list in the YAML
// and work with them as a map internally
type CredentialDefinitions map[string]CredentialDefinition

func (cd CredentialDefinitions) MarshalYAML() (interface{}, error) {
	raw := make([]CredentialDefinition, 0, len(cd))

	for _, cred := range cd {
		raw = append(raw, cred)
	}

	return raw, nil
}

func (cd *CredentialDefinitions) UnmarshalYAML(unmarshal func(interface{}) error) error {
	var raw []CredentialDefinition
	err := unmarshal(&raw)
	if err != nil {
		return err
	}

	if *cd == nil {
		*cd = make(map[string]CredentialDefinition, len(raw))
	}

	for _, item := range raw {
		(*cd)[item.Name] = item
	}

	return nil
}

// CredentialDefinition represents the structure or fields of a credential parameter
type CredentialDefinition struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`

	// Required specifies if the credential must be specified for applicable actions. Defaults to true.
	Required bool `yaml:"required,omitempty"`

	// ApplyTo lists the actions to which the credential applies. When unset, defaults to all actions.
	ApplyTo []string `yaml:"applyTo,omitempty"`

	Location `yaml:",inline"`
}

func (cd *CredentialDefinition) UnmarshalYAML(unmarshal func(interface{}) error) error {
	type rawCreds CredentialDefinition
	rawCred := rawCreds{
		Name:        cd.Name,
		Description: cd.Description,
		Required:    true,
		Location:    cd.Location,
	}

	if err := unmarshal(&rawCred); err != nil {
		return err
	}

	*cd = CredentialDefinition(rawCred)

	return nil
}

// Location represents a Parameter or Credential location in an InvocationImage
type Location struct {
	Path                string `yaml:"path,omitempty"`
	EnvironmentVariable string `yaml:"env,omitempty"`
}

func (l Location) IsEmpty() bool {
	var empty Location
	return l == empty
}

type MixinDeclaration struct {
	Name    string
	Version *semver.Constraints
	Config  interface{}
}

func extractVersionFromName(name string) (string, *semver.Constraints, error) {
	parts := strings.Split(name, "@")

	// if there isn't a version in the name, just stop!
	if len(parts) == 1 {
		return name, nil, nil
	}

	// if we somehow got more parts than expected!
	if len(parts) != 2 {
		return "", nil, fmt.Errorf("expected name@version, got: %s", name)
	}

	version, err := semver.NewConstraint(parts[1])
	if err != nil {
		return "", nil, err
	}

	return parts[0], version, nil
}

// UnmarshalYAML allows mixin declarations to either be a normal list of strings
// mixins:
// - exec
// - helm3
// or allow some entries to have config data defined
//   - az:
//     extensions:
//   - iot
//
// for each type, we can optionally support a version number in the name field
// mixins:
// - exec@2.1.1
// or
//   - az@2.1.1
//     extensions:
//   - iot
func (m *MixinDeclaration) UnmarshalYAML(unmarshal func(interface{}) error) error {
	// First try to just read the mixin name
	var mixinNameOnly string
	err := unmarshal(&mixinNameOnly)
	if err == nil {
		name, version, err := extractVersionFromName(mixinNameOnly)
		if err != nil {
			return fmt.Errorf("invalid mixin name/version: %w", err)
		}
		m.Name = name
		m.Version = version
		m.Config = nil
		return nil
	}

	// Next try to read a mixin name with config defined
	mixinWithConfig := map[string]interface{}{}
	err = unmarshal(&mixinWithConfig)
	if err != nil {
		return fmt.Errorf("could not unmarshal raw yaml of mixin declarations: %w", err)
	}

	if len(mixinWithConfig) == 0 {
		return errors.New("mixin declaration was empty")
	} else if len(mixinWithConfig) > 1 {
		return errors.New("mixin declaration contained more than one mixin")
	}

	for mixinName, config := range mixinWithConfig {
		name, version, err := extractVersionFromName(mixinName)
		if err != nil {
			return fmt.Errorf("invalid mixin name/version: %w", err)
		}
		m.Name = name
		m.Version = version
		m.Config = config
		break // There is only one mixin anyway but break for clarity
	}
	return nil
}

// MarshalYAML allows mixin declarations to either be a normal list of strings
// mixins:
// - exec
// - helm3
// or allow some entries to have config data defined
//   - az:
//     extensions:
//   - iot
func (m MixinDeclaration) MarshalYAML() (interface{}, error) {
	if m.Config == nil {
		return m.Name, nil
	}

	raw := map[string]interface{}{
		m.Name: m.Config,
	}
	return raw, nil
}

type MappedImage struct {
	Description string            `yaml:"description"`
	ImageType   string            `yaml:"imageType"`
	Repository  string            `yaml:"repository"`
	Digest      string            `yaml:"digest,omitempty"`
	Size        uint64            `yaml:"size,omitempty"`
	MediaType   string            `yaml:"mediaType,omitempty"`
	Labels      map[string]string `yaml:"labels,omitempty"`
	Tag         string            `yaml:"tag,omitempty"`
}

func (mi *MappedImage) Validate() error {
	if mi.Digest != "" {
		if _, err := digest.Parse(mi.Digest); err != nil {
			return err
		}
	}

	if _, err := cnab.ParseOCIReference(mi.Repository); err != nil {
		return err
	}

	return nil
}

func (mi *MappedImage) ToOCIReference() (cnab.OCIReference, error) {
	ref, err := cnab.ParseOCIReference(mi.Repository)
	if err != nil {
		return cnab.OCIReference{}, err
	}

	if mi.Digest != "" {
		refWithDigest, err := ref.WithDigest(digest.Digest(mi.Digest))
		if err != nil {
			return cnab.OCIReference{}, fmt.Errorf("failed to create a new reference with digest for repository %s: %w", mi.Repository, err)
		}

		return refWithDigest, nil
	}

	if mi.Tag != "" {
		refWithTag, err := ref.WithTag(mi.Tag)
		if err != nil {
			return cnab.OCIReference{}, fmt.Errorf("failed to create a new reference with tag for repository %s: %w", mi.Repository, err)
		}

		return refWithTag, nil
	}

	return ref, nil
}

// Dependencies defies both v2 and v1 dependencies.
// Dependencies v1 is a subset of Dependencies v2.
type Dependencies struct {
	// Requires specifies bundles required by the current bundle.
	Requires []*Dependency `yaml:"requires,omitempty"`

	// Provides specifies how the bundle can satisfy a dependency.
	// This declares that the bundle can provide a dependency that another bundle requires.
	Provides *DependencyProvider `yaml:"provides,omitempty"`
}

// Dependency defines a parent child relationship between this bundle (parent) and the specified bundle (child).
type Dependency struct {
	// Name of the dependency, used to reference the dependency from other parts of
	// the bundle such as the template syntax, bundle.dependencies.NAME
	Name string `yaml:"name"`

	// Bundle specifies criteria for selecting a bundle to satisfy the dependency.
	Bundle BundleCriteria `yaml:"bundle"`

	// Sharing is a set of rules for sharing a dependency with other bundles.
	Sharing SharingCriteria `yaml:"sharing,omitempty"`

	// Parameters is a map of values, keyed by the destination where the value is the
	// source, to pass from the bundle to the dependency. May either be a hard-coded
	// value, or a template value such as ${bundle.parameters.NAME}. The key is the
	// dependency's parameter name, and the value is the data being passed to the
	// dependency parameter.
	Parameters map[string]string `yaml:"parameters,omitempty"`

	// Credentials is a map of values, keyed by the destination where the value is
	// the source, to pass from the bundle to the dependency. May either be a
	// hard-coded value, or a template value such as ${bundle.credentials.NAME}. The
	// key is the dependency's credential name, and the value is the data being
	// passed to the dependency credential.
	Credentials map[string]string `yaml:"credentials,omitempty"`

	// Outputs is a map of values, keyed by the destination where the value is the
	// source, to pass from the dependency and promote to a bundle-level outputs of
	// the parent bundle. May either be the name of an output from the dependency, or
	// a template value such as ${outputs.NAME} where the outputs variable holds the
	// current dependency's outputs. The long form of the template syntax,
	// ${bundle.dependencies.DEP.outputs.NAME}, is also supported. The key is the
	// parent bundle's output name, and the value is the data being passed to the
	// dependency parameter.
	Outputs map[string]string `yaml:"outputs,omitempty"`
}

type DependencySource string

// BundleCriteria criteria for selecting a bundle to satisfy a dependency.
type BundleCriteria struct {
	// Reference is an OCI reference to a bundle for use as the default implementation of the bundle.
	// It should be in the format REGISTRY/NAME:TAG
	Reference string `yaml:"reference"`

	// "When constraint checking is used for checks or validation
	// it will follow a different set of rules that are common for ranges with tools like npm/js and Rust/Cargo.
	// This includes considering prereleases to be invalid if the ranges does not include one.
	// If you want to have it include pre-releases a simple solution is to include -0 in your range."
	// https://github.com/Masterminds/semver/blob/master/README.md#checking-version-constraints
	Version string `yaml:"version,omitempty"`

	// Interface specifies criteria for allowing a bundle to satisfy a dependency.
	Interface *BundleInterface `yaml:"interface,omitempty"`
}

// BundleInterface specifies how a bundle can satisfy a dependency.
// Porter always infers a base interface based on how the dependency is used in porter.yaml
// but this allows the bundle author to extend it and add additional restrictions.
// Either bundle or reference may be specified but not both.
type BundleInterface struct {
	// ID is the identifier or name of the bundle interface. It should be matched
	// against the Dependencies.Provides.Interface.ID to determine if two interfaces
	// are equivalent.
	ID string `yaml:"id,omitempty"`

	// Reference specifies an OCI reference to a bundle to use as the interface on top of how the bundle is used.
	Reference string `yaml:"reference,omitempty"`

	// Document specifies additional constraints that should be added to the bundle interface.
	// By default, Porter only requires the name and the type to match, additional jsonschema values can be specified to restrict matching bundles even further.
	// The value should be a jsonschema document containing relevant sub-documents from a bundle.json that should be applied to the base bundle interface.
	Document *BundleInterfaceDocument `yaml:"document,omitempty"`
}

// BundleInterfaceDocument specifies the interface that a bundle must support in
// order to satisfy a dependency.
type BundleInterfaceDocument struct {
	// Parameters that are defined on the interface.
	Parameters ParameterDefinitions `yaml:"parameters,omitempty"`

	// Credentials that are defined on the interface.
	Credentials CredentialDefinitions `yaml:"credentials,omitempty"`

	// Outputs that are defined on the interface.
	Outputs OutputDefinitions `yaml:"outputs,omitempty"`
}

// SharingCriteria is a set of rules for sharing a dependency with other bundles.
type SharingCriteria struct {
	// Mode defines how a dependency can be shared.
	//  - false: The dependency cannot be shared, even within the same dependency graph.
	//  - true: The dependency is shared with other bundles who defined the dependency
	//    with the same sharing group. This is the default mode.
	Mode bool `yaml:"mode"`

	// Group defines matching criteria for determining if two dependencies are in the same sharing group.
	Group SharingGroup `yaml:"group,omitempty"`
}

// GetEffectiveMode returns the mode, taking into account the default value when
// no mode is specified.
func (s SharingCriteria) GetEffectiveMode() bool {
	return s.Mode
}

// SharingGroup defines a set of characteristics for sharing a dependency with
// other bundles.
// Reserved for future use: We can add more characteristics later to expands how we share if needed
type SharingGroup struct {
	// Name of the sharing group. The name of the group must match for two bundles to share the same dependency.
	Name string `yaml:"name"`
}

func (d *Dependency) Validate(cxt *portercontext.Context) error {
	if d.Name == "" {
		return errors.New("dependency name is required")
	}

	if d.Bundle.Reference == "" {
		return fmt.Errorf("reference is required for dependency %q", d.Name)
	}

	ref, err := cnab.ParseOCIReference(d.Bundle.Reference)
	if err != nil {
		return fmt.Errorf("invalid reference %s for dependency %s: %w", d.Bundle.Reference, d.Name, err)
	}

	if ref.IsRepositoryOnly() && d.Bundle.Version == "" {
		return fmt.Errorf("reference for dependency %q can specify only a repository, without a digest or tag, when a version constraint is specified", d.Name)
	}

	return nil
}

// UsesV2Features returns true if the dependency uses features from v2 of
// Porter's implementation of dependencies, and returns false if the v1
// implementation of dependencies would suffice.
func (d *Dependency) UsesV2Features() bool {
	// Sharing was added in v2
	if d.Sharing != (SharingCriteria{}) {
		return true
	}

	// Credentials and output mapping was added in v2
	if len(d.Credentials) > 0 || len(d.Outputs) > 0 {
		return true
	}

	// Bundle interfaces was added in v2
	if d.Bundle.Interface != nil {
		return true
	}

	// Anything else can be handled with v1
	return false
}

type CustomActionDefinition struct {
	Description       string `yaml:"description,omitempty"`
	ModifiesResources bool   `yaml:"modifies,omitempty"`
	Stateless         bool   `yaml:"stateless,omitempty"`
}

// OutputDefinitions allows us to represent parameters as a list in the YAML
// and work with them as a map internally
type OutputDefinitions map[string]OutputDefinition

func (od OutputDefinitions) MarshalYAML() (interface{}, error) {
	raw := make([]OutputDefinition, 0, len(od))

	for _, output := range od {
		raw = append(raw, output)
	}

	return raw, nil
}

func (od *OutputDefinitions) UnmarshalYAML(unmarshal func(interface{}) error) error {
	var raw []OutputDefinition
	err := unmarshal(&raw)
	if err != nil {
		return err
	}

	if *od == nil {
		*od = make(map[string]OutputDefinition, len(raw))
	}

	for _, item := range raw {
		(*od)[item.Name] = item
	}

	return nil
}

// OutputDefinition defines a single output for a CNAB
type OutputDefinition struct {
	Name      string   `yaml:"name"`
	ApplyTo   []string `yaml:"applyTo,omitempty"`
	Sensitive bool     `yaml:"sensitive"`

	// This is not in the CNAB spec, but it allows a mixin to create a file
	// and porter will take care of making it a proper output.
	Path string `yaml:"path,omitempty"`

	definition.Schema `yaml:",inline"`

	// IsState identifies if the output was generated from a state variable
	IsState bool `yaml:"-"`
}

// DeepCopy copies a ParameterDefinition and returns the copy
func (od *OutputDefinition) DeepCopy() *OutputDefinition {
	o2 := *od
	o2.ApplyTo = make([]string, len(od.ApplyTo))
	copy(o2.ApplyTo, od.ApplyTo)
	return &o2
}

func (od *OutputDefinition) Validate() error {
	var result *multierror.Error

	if od.Name == "" {
		return errors.New("output name is required")
	}

	// Porter supports declaring an output of type: "file",
	// which we will convert to the appropriate type in adapter.go
	// Here, we copy the definition and make the same modification before validation
	odCopy := od.DeepCopy()
	if odCopy.Type == "file" {
		if od.Path == "" {
			result = multierror.Append(result, fmt.Errorf("no path supplied for output %s", od.Name))
		}
		odCopy.Type = "string"
		odCopy.ContentEncoding = "base64"
	}

	// Validate the Output Definition schema itself
	if _, err := odCopy.Schema.ValidateSchema(); err != nil {
		return multierror.Append(result, fmt.Errorf("encountered an error while validating definition for output %q: %w", odCopy.Name, err))
	}

	if odCopy.Default != nil {
		schemaValidationErrs, err := odCopy.Schema.Validate(odCopy.Default)
		if err != nil {
			result = multierror.Append(result, fmt.Errorf("encountered error while validating output %s: %w", odCopy.Name, err))
		}
		for _, schemaValidationErr := range schemaValidationErrs {
			result = multierror.Append(result, fmt.Errorf("encountered an error validating the default value %v for output %q: %s", odCopy.Default, odCopy.Name, schemaValidationErr.Error))
		}
	}

	return result.ErrorOrNil()
}

type BundleOutput struct {
	Name                string `yaml:"name"`
	Path                string `yaml:"path"`
	EnvironmentVariable string `yaml:"env"`
}

type Steps []*Step

func (s Steps) Validate(m *Manifest) error {
	for i, step := range s {
		err := step.Validate(m)
		if err != nil {
			return fmt.Errorf("failed to validate %s step: %s", humanize.Ordinal(i+1), err)
		}
	}
	return nil
}

type Step struct {
	Data map[string]interface{} `yaml:",inline"`
}

func (s *Step) Validate(m *Manifest) error {
	if s == nil {
		return errors.New("found an empty step")
	}
	if len(s.Data) == 0 {
		return errors.New("no mixin specified")
	}
	if len(s.Data) > 1 {
		return errors.New("malformed step, possibly incorrect indentation")
	}

	mixinDeclared := false
	mixinType := s.GetMixinName()
	for _, mixin := range m.Mixins {
		if mixin.Name == mixinType {
			mixinDeclared = true
			break
		}
	}
	if !mixinDeclared {
		return fmt.Errorf("mixin (%s) was not declared", mixinType)
	}

	if _, err := s.GetDescription(); err != nil {
		return err
	}

	return nil
}

// GetDescription returns a description of the step.
// Every step must have this property.
func (s *Step) GetDescription() (string, error) {
	if s.Data == nil {
		return "", errors.New("empty step data")
	}

	mixinName := s.GetMixinName()
	children := s.Data[mixinName]
	m, ok := children.(map[string]interface{})
	if !ok {
		return "", fmt.Errorf("invalid mixin type (%T) for mixin step (%s)", children, mixinName)
	}
	d := m["description"]
	if d == nil {
		return "", nil
	}
	desc, ok := d.(string)
	if !ok {
		return "", fmt.Errorf("invalid description type (%T) for mixin step (%s)", desc, mixinName)
	}

	return desc, nil
}

func (s *Step) GetMixinName() string {
	var mixinName string
	for k := range s.Data {
		mixinName = k
	}
	return mixinName
}

func UnmarshalManifest(cxt *portercontext.Context, manifestData []byte) (*Manifest, error) {
	// Unmarshal the manifest into the normal struct
	manifest := &Manifest{}
	err := yaml.Unmarshal(manifestData, &manifest)
	if err != nil {
		return nil, fmt.Errorf("error unmarshaling the typed manifest: %w", err)
	}

	// Do a second pass to identify custom actions, which don't have yaml tags since they are dynamic
	// 1. Marshal the manifest a second time into a plain map
	// 2. Remove keys for fields that are already mapped with yaml tags
	// 3. Anything left is a custom action

	// Marshal the manifest into an untyped map
	unmappedData := make(map[string]interface{})
	err = yaml.Unmarshal(manifestData, &unmappedData)
	if err != nil {
		return nil, fmt.Errorf("error unmarshaling the untyped manifest: %w", err)
	}

	// Use reflection to figure out which fields are on the manifest and have yaml tags
	objValue := reflect.ValueOf(manifest).Elem()
	knownFields := map[string]reflect.Value{}
	for i := 0; i != objValue.NumField(); i++ {
		tagName := strings.Split(objValue.Type().Field(i).Tag.Get("yaml"), ",")[0]
		knownFields[tagName] = objValue.Field(i)
	}

	// Remove any fields that have yaml tags
	for key := range unmappedData {
		if _, found := knownFields[key]; found {
			delete(unmappedData, key)
		}
		// Delete known deprecated fields with no yaml tags
		if key == "invocationImage" || key == "tag" {
			fmt.Fprintf(cxt.Out, "WARNING: The %q field has been deprecated and can no longer be user-specified; ignoring.\n", key)
			delete(unmappedData, key)
		}
	}

	// Marshal the remaining keys in the unmappedData as custom actions and append them to the typed manifest
	manifest.CustomActions = make(map[string]Steps, len(unmappedData))
	for key, chunk := range unmappedData {
		chunkData, err := yaml.Marshal(chunk)
		if err != nil {
			return nil, fmt.Errorf("error remarshaling custom action %s: %w", key, err)
		}

		steps := Steps{}
		err = yaml.Unmarshal(chunkData, &steps)
		if err != nil {
			return nil, fmt.Errorf("error unmarshaling custom action %s: %w", key, err)
		}

		manifest.CustomActions[key] = steps
	}

	return manifest, nil
}

// SetDefaults updates the manifest with default values where not populated
func (m *Manifest) SetDefaults() error {
	return m.SetBundleImageAndReference("")
}

// SetBundleImageAndReference sets the bundle image name and the
// bundle reference on the manifest per the provided reference or via the
// registry or name values on the manifest.
func (m *Manifest) SetBundleImageAndReference(ref string) error {
	if ref != "" {
		m.Reference = ref
	}

	if m.Reference == "" && m.Registry != "" {
		repo, err := cnab.ParseOCIReference(path.Join(m.Registry, m.Name))
		if err != nil {
			return fmt.Errorf("invalid bundle reference %s: %w", path.Join(m.Registry, m.Name), err)
		}
		m.Reference = repo.Repository()
	}

	bundleRef, err := cnab.ParseOCIReference(m.Reference)
	if err != nil {
		return fmt.Errorf("invalid bundle reference %s: %w", m.Reference, err)
	}

	dockerTag, err := m.getDockerTagFromBundleRef(bundleRef)
	if err != nil {
		return fmt.Errorf("unable to derive docker tag from bundle reference %q: %w", m.Reference, err)
	}

	// If the docker tag is initially missing from bundleTag, update with
	// returned dockerTag
	if !bundleRef.HasTag() {
		bundleRef, err = bundleRef.WithTag(dockerTag)
		if err != nil {
			return fmt.Errorf("could not set bundle tag to %q: %w", dockerTag, err)
		}
		m.Reference = bundleRef.String()
	}

	installerImage, err := cnab.CalculateTemporaryImageTag(bundleRef)
	if err != nil {
		return err
	}

	m.Image = installerImage.String()
	return nil
}

// getDockerTagFromBundleRef returns the Docker tag portion of the bundle tag,
// using the bundle version as a fallback
func (m *Manifest) getDockerTagFromBundleRef(bundleRef cnab.OCIReference) (string, error) {
	// If the manifest has a DockerTag override already set (e.g. on publish), use this
	if m.DockerTag != "" {
		return m.DockerTag, nil
	}

	if bundleRef.HasTag() {
		return bundleRef.Tag(), nil
	}

	if bundleRef.HasDigest() {
		return "", errors.New("invalid bundle tag format, must be an OCI image tag")
	}

	// Docker tag is missing from the provided bundle tag, so default it
	// to use the manifest version prefixed with v
	// Example: bundle version is 1.0.0, so the bundle tag is v1.0.0
	newRef, err := bundleRef.WithVersion(m.Version)
	if err != nil {
		return "", err
	}
	return newRef.Tag(), nil
}

// ResolvePath resolves a path specified in the Porter manifest into
// an absolute path, assuming the current directory is /cnab/app.
// Returns an empty string when the specified value is empty.
func ResolvePath(value string) string {
	if value == "" {
		return ""
	}

	if path.IsAbs(value) {
		return value
	}

	return path.Join("/cnab/app", value)
}

func readFromFile(cxt *portercontext.Context, path string) ([]byte, error) {
	if exists, _ := cxt.FileSystem.Exists(path); !exists {
		return nil, fmt.Errorf("the specified porter configuration file %s does not exist", path)
	}

	data, err := cxt.FileSystem.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("could not read manifest at %q: %w", path, err)
	}
	return data, nil
}

func readFromURL(path string) ([]byte, error) {
	resp, err := http.Get(path)
	if err != nil {
		return nil, fmt.Errorf("could not reach url %s: %w", path, err)
	}

	defer resp.Body.Close()
	data, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("could not read from url %s: %w", path, err)
	}
	return data, nil
}

func ReadManifestData(cxt *portercontext.Context, path string) ([]byte, error) {
	if strings.HasPrefix(path, "http") {
		return readFromURL(path)
	} else {
		return readFromFile(cxt, path)
	}
}

// ReadManifest determines if specified path is a URL or a filepath.
// After reading the data in the path it returns a Manifest and any errors
func ReadManifest(cxt *portercontext.Context, path string, config *config.Config) (*Manifest, error) {
	data, err := ReadManifestData(cxt, path)
	if err != nil {
		return nil, err
	}

	m, err := UnmarshalManifest(cxt, data)
	if err != nil {
		return nil, fmt.Errorf("unsupported property set or a custom action is defined incorrectly: %w", err)
	}

	tmplResult, err := m.ScanManifestTemplating(data, config)
	if err != nil {
		return nil, err
	}

	m.ManifestPath = path
	m.TemplateVariables = tmplResult.Variables

	return m, nil
}

// templateScanResult is the result of parsing the mustache templating used in the manifest.
type templateScanResult struct {
	// Variables used in the template, e.g.  {{ bundle.parameters.NAME }}
	Variables []string
}

func (m *Manifest) GetTemplatePrefix() string {
	if m.SchemaVersion == "" {
		// Super-old bundles use the mustache default
		return ""
	}

	// In 1.0.0-alpha.2+, the prefix is ${}. Beforehand it was {{}}
	v, err := semver.NewVersion(m.SchemaVersion)
	if err == nil {
		if v.GreaterThan(semver.MustParse("v1.0.0-alpha.1")) {
			// Change the delimiter
			return TemplateDelimiterPrefix
		}
	}

	// Fallback to the mustache default if we can't determine the schema version
	return ""
}

func (m *Manifest) ScanManifestTemplating(data []byte, config *config.Config) (templateScanResult, error) {
	// Handle outputs variable
	shortOutputVars, err := m.mapShortDependencyOutputVariables(config)
	if err != nil {
		return templateScanResult{}, fmt.Errorf("error parsing the templating used in the manifest: %w", err)
	}

	vars, err := m.getTemplateVariables(string(data))
	if err != nil {
		return templateScanResult{}, fmt.Errorf("error parsing the templating used in the manifest: %w", err)
	}

	if config.IsFeatureEnabled(experimental.FlagDependenciesV2) {
		m.deduplicateAndFilterShortOutputVariables(shortOutputVars, vars)
	}

	result := templateScanResult{
		Variables: make([]string, 0, len(vars)),
	}
	for v := range vars {
		result.Variables = append(result.Variables, v)
	}

	sort.Strings(result.Variables)
	return result, nil
}

func (m *Manifest) mapShortDependencyOutputVariables(config *config.Config) ([]string, error) {
	shortOutputVars := []string{}
	if config.IsFeatureEnabled(experimental.FlagDependenciesV2) {
		for _, dep := range m.Dependencies.Requires {
			for outputName, output := range dep.Outputs {
				vars, err := m.getTemplateVariables(output)
				if err != nil {
					return nil, fmt.Errorf("error parsing the templating used for dependency %s output %s: %w", dep.Name, outputName, err)
				}

				for tmplVar := range vars {
					outputTemplateName, ok := m.getTemplateDependencyShortOutputName(tmplVar)
					if ok {
						shortOutputVars = append(shortOutputVars, fmt.Sprintf("bundle.dependencies.%s.outputs.%s", dep.Name, outputTemplateName))
					}
				}
			}
		}
	}

	return shortOutputVars, nil
}

func (m *Manifest) deduplicateAndFilterShortOutputVariables(shortOutputVars []string, vars map[string]struct{}) {
	for tmplVar := range vars {
		if strings.HasPrefix(tmplVar, "outputs.") {
			delete(vars, tmplVar)
		}
	}

	for _, shortHandVar := range shortOutputVars {
		vars[shortHandVar] = struct{}{}
	}
}

func (m *Manifest) getTemplateVariables(data string) (map[string]struct{}, error) {
	const disableHtmlEscaping = true
	templateSrc := m.GetTemplatePrefix() + string(data)
	tmpl, err := mustache.ParseStringRaw(templateSrc, disableHtmlEscaping)
	if err != nil {
		return nil, fmt.Errorf("error parsing the templating used in the manifest: %w", err)
	}

	tags := tmpl.Tags()
	vars := map[string]struct{}{} // Keep track of unique variable names
	for _, tag := range tags {
		if tag.Type() != mustache.Variable {
			continue
		}

		vars[tag.Name()] = struct{}{}
	}

	return vars, nil
}

// LoadManifestFrom reads and validates the manifest at the specified location,
// and returns a populated Manifest structure.
func LoadManifestFrom(ctx context.Context, config *config.Config, file string) (*Manifest, error) {
	ctx, log := tracing.StartSpan(ctx)
	defer log.EndSpan()

	m, err := ReadManifest(config.Context, file, config)
	if err != nil {
		return nil, err
	}

	if err = m.Validate(ctx, config); err != nil {
		return nil, err
	}

	return m, nil
}

// RequiredExtension represents a custom extension that is required
// in order for a bundle to work correctly
type RequiredExtension struct {
	Name   string
	Config map[string]interface{}
}

// UnmarshalYAML allows required extensions to either be a normal list of strings
// required:
// - docker
// or allow some entries to have config data defined
//   - vpn:
//     name: mytrustednetwork
func (r *RequiredExtension) UnmarshalYAML(unmarshal func(interface{}) error) error {
	// First try to just read the mixin name
	var extNameOnly string
	err := unmarshal(&extNameOnly)
	if err == nil {
		r.Name = extNameOnly
		r.Config = nil
		return nil
	}

	// Next try to read a required extension with config defined
	extWithConfig := map[string]map[string]interface{}{}
	err = unmarshal(&extWithConfig)
	if err != nil {
		return fmt.Errorf("could not unmarshal raw yaml of required extensions: %w", err)
	}

	if len(extWithConfig) == 0 {
		return errors.New("required extension was empty")
	} else if len(extWithConfig) > 1 {
		return errors.New("required extension contained more than one extension")
	}

	for extName, config := range extWithConfig {
		r.Name = extName
		r.Config = config
		break // There is only one extension anyway but break for clarity
	}
	return nil
}

// Convert a parameter name to an environment variable.
// Anything more complicated should define the variable explicitly.
func ParamToEnvVar(name string) string {
	name = strings.ToUpper(name)
	fixer := strings.NewReplacer("-", "_", ".", "_")
	return fixer.Replace(name)
}

// GetParameterSourceForOutput builds the parameter source name used by Porter
// internally for wiring up an output to a parameter.
func GetParameterSourceForOutput(outputName string) string {
	return fmt.Sprintf("porter-%s-output", outputName)
}

// GetParameterSourceForDependency builds the parameter source name used by Porter
// internally for wiring up an dependency's output to a parameter.
func GetParameterSourceForDependency(ref DependencyOutputReference) string {
	return fmt.Sprintf("porter-%s-%s-dep-output", ref.Dependency, ref.Output)
}

type MaintainerDefinition struct {
	Name  string `yaml:"name,omitempty"`
	Email string `yaml:"email,omitempty"`
	Url   string `yaml:"url,omitempty"`
}

// StateBag is the set of state files and variables that Porter should
// track between bundle executions.
type StateBag []StateVariable

type StateVariable struct {
	// Name of the state variable
	Name string `yaml:"name"`

	// Description of the state variable and how it's used by the bundle
	Description string `yaml:"description,omitempty"`

	// Mixin is the name of the mixin that manages the state variable.
	Mixin string `yaml:"mixin,omitempty"`

	// Location defines where the state variable is located in the bundle.
	Location `yaml:",inline"`
}