environments

README

Pulumi Environments Core

This repository contains the datatypes and evaluator that form the core of Pulumi Environments. Projects that build on this foundation must supply their own implementations for eval.ProviderLoader and eval.EnvironmentLoader in order to be fully functional.

Documentation

Index

• type AccessExpr
• type Accessor
• type BuiltinExpr
• type Environment
• type Expr
• type Interpolation
• type Pos
• type PropertyAccessor
• type Provider
• type Range
  • func (r Range) Contains(pos Pos) bool
• type Trace
• type Value
  • func NewSecret[T ValueType](v T) Value
  • func NewValue[T ValueType](v T) Value
  • func (v Value) String() string
  • func (v Value) ToJSON(redact bool) any
  • func (v Value) ToString(redact bool) string
  • func (v *Value) UnmarshalJSON(data []byte) error
• type ValueType

Types

type AccessExpr

type AccessExpr struct {
	// The receiver to access.
	Receiver Range `json:"receiver"`

	// The accessors to evaluate.
	Accessors []Accessor `json:"accessors"`
}

An AccessExpr represents a property access with a receiving value.

type Accessor

type Accessor struct {
	// The integer index of the element to access. Mutually exclusive with Key.
	Index *int `json:"index,omitempty"`

	// The key of the property to access. Mutually exclusive with Index.
	Key *string `json:"key,omitempty"`
}

An Accessor is an element index or property name.

type BuiltinExpr

type BuiltinExpr struct {
	Name      string         `json:"name"`
	ArgSchema *schema.Schema `json:"argSchema"`
	Arg       Expr           `json:"arg"`
}

A BuiltinExpr is a call to a builtin function.

type Environment

type Environment struct {
	// Exprs contains the AST for each expression in the environment definition.
	Exprs map[string]Expr `json:"exprs,omitempty"`

	// Properties contains the detailed values produced by the environment.
	Properties map[string]Value `json:"properties,omitempty"`

	// Schema contains the schema for Properties.
	Schema *schema.Schema `json:"schema,omitempty"`
}

An Environment contains the result of evaluating an environment definition.

type Expr

type Expr struct {
	// The range of the expression.
	Range Range `json:"range"`

	// The schema of the expression's result.
	Schema *schema.Schema `json:"schema,omitempty"`

	// The expression that defined this expression's base value, if any.
	Base *Expr `json:"base,omitempty"`

	// The literal value, if this is a literal expression (nil, bool, json.Number, or string)
	Literal any `json:"literal,omitempty"`

	// The interpolations, if this is a a string interpolation expression
	Interpolate []Interpolation `json:"interpolate,omitempty"`

	// The property accessors, if this is a a symbol expression
	Symbol []PropertyAccessor `json:"symbol,omitempty"`

	// The access, if this is an access expression
	Access *AccessExpr `json:"access,omitempty"`

	// The list elements, if this isa list expression
	List []Expr `json:"list,omitempty"`

	// The object properties, if this is an object expression.
	Object map[string]Expr `json:"object,omitempty"`

	// The builtin, if this is a call to a builtin function.
	Builtin *BuiltinExpr `json:"builtin,omitempty"`
}

An Expr holds information about an expression in an environment definition.

type Interpolation

type Interpolation struct {
	// The text of the expression. Precedes the stringified Value in the output.
	Text string `json:"text,omitempty"`

	// The value to interpolate.
	Value []PropertyAccessor `json:"value,omitempty"`
}

An Interpolation holds information about a part of an interpolated string expression.

type Pos

type Pos struct {
	// Line is the source code line where this position points. Lines are counted starting at 1 and incremented for each
	// newline character encountered.
	Line int `json:"line"`

	// Column is the source code column where this position points. Columns are counted in visual cells starting at 1,
	// and are incremented roughly per grapheme cluster encountered.
	Column int `json:"column"`

	// Byte is the byte offset into the file where the indicated position begins.
	Byte int `json:"byte"`
}

A Pos defines a position within an environment definition.

type PropertyAccessor

type PropertyAccessor struct {
	Accessor

	// The range of the expression that defines the resolved value.
	Value Range `json:"value"`
}

A PropertyAccessor is a single accessor that is associated with a resolved value.

type Provider

type Provider interface {
	// Schema returns the provider's input and output schemata.
	Schema() (inputs, outputs *schema.Schema)

	// Open retrieves the provider's secrets.
	Open(ctx context.Context, inputs map[string]Value) (Value, error)
}

A Provider provides environments access to dynamic secrets. These secrets may be generated at runtime, fetched from other services, etc.

type Range

type Range struct {
	// The name of the environment.
	Environment string `json:"environment,omitempty"`

	// The beginning of the range.
	Begin Pos `json:"begin"`

	// The end of the range.
	End Pos `json:"end"`
}

A Range defines a range within an environment definition.

func (Range) Contains

func (r Range) Contains(pos Pos) bool

Contains returns true if the range contains the given position.

type Trace

type Trace struct {
	// Def is the range of the expression that computed a value.
	Def Range `json:"def"`

	// Base is the base value with which a value was merged.
	Base *Value `json:"base,omitempty"`
}

Trace holds information about the expression and base of a value.

type Value

type Value struct {
	// Value holds the concrete representation of the value. May be nil, bool, json.Number, string, []Value, or
	// map[string]Value.
	Value any `json:"value,omitempty"`

	// Secret is true if this value is secret.
	Secret bool `json:"secret,omitempty"`

	// Unknown is true if this value is unknown.
	Unknown bool `json:"unknown,omitempty"`

	// Trace holds information about the expression that computed this value and the value (if any) with which it was
	// merged.
	Trace Trace `json:"trace"`
}

A Value is the result of evaluating an expression within an environment definition.

func NewSecret

func NewSecret[T ValueType](v T) Value

NewSecret creates a new secret value with the given representation.

func NewValue

func NewValue[T ValueType](v T) Value

NewValue creates a new value with the given representation.

func (Value) String

func (v Value) String() string

String is shorthand for ToString(true).

func (Value) ToJSON

func (v Value) ToJSON(redact bool) any

ToJSON converts a Value into a plain-old-JSON value (i.e. a value of type nil, bool, json.Number, string, []any, or map[string]any). If redact is true, secrets are replaced with [secret].

func (Value) ToString

func (v Value) ToString(redact bool) string

ToString returns the string representation of this value. If redact is true, secrets are replaced with [secret].

func (*Value) UnmarshalJSON

func (v *Value) UnmarshalJSON(data []byte) error

type ValueType

type ValueType interface {
	bool | json.Number | string | []Value | map[string]Value
}

ValueType defines the types of concrete values stored inside a Value.