objchange

Documentation

Overview

Package objchange deals with the business logic of taking a prior state value and a config value and producing a proposed new merged value, along with other related rules in this domain.

Index

• func AllAttributesNull(schema *configschema.Block) cty.Value
• func AssertObjectCompatible(schema *configschema.Block, planned, actual cty.Value) []error
• func AssertPlanValid(schema *configschema.Block, priorState, config, plannedState cty.Value) []error
• func LongestCommonSubsequence(xs, ys []cty.Value) []cty.Value
• func NormalizeObjectFromLegacySDK(val cty.Value, schema *configschema.Block) cty.Value
• func PlannedDataResourceObject(schema *configschema.Block, config cty.Value) cty.Value
• func ProposedNewObject(schema *configschema.Block, prior, config cty.Value) cty.Value

Functions

func AllAttributesNull

func AllAttributesNull(schema *configschema.Block) cty.Value

AllAttributesNull constructs a non-null cty.Value of the object type implied by the given schema that has all of its leaf attributes set to null and all of its nested block collections set to zero-length.

This simulates what would result from decoding an empty configuration block with the given schema, except that it does not produce errors

func AssertObjectCompatible

func AssertObjectCompatible(schema *configschema.Block, planned, actual cty.Value) []error

AssertObjectCompatible checks whether the given "actual" value is a valid completion of the possibly-partially-unknown "planned" value.

This means that any known leaf value in "planned" must be equal to the corresponding value in "actual", and various other similar constraints.

Any inconsistencies are reported by returning a non-zero number of errors. These errors are usually (but not necessarily) cty.PathError values referring to a particular nested value within the "actual" value.

The two values must have types that conform to the given schema's implied type, or this function will panic.

func AssertPlanValid

func AssertPlanValid(schema *configschema.Block, priorState, config, plannedState cty.Value) []error

AssertPlanValid checks checks whether a planned new state returned by a provider's PlanResourceChange method is suitable to achieve a change from priorState to config. It returns a slice with nonzero length if any problems are detected. Because problems here indicate bugs in the provider that generated the plannedState, they are written with provider developers as an audience, rather than end-users.

All of the given values must have the same type and must conform to the implied type of the given schema, or this function may panic or produce garbage results.

During planning, a provider may only make changes to attributes that are null (unset) in the configuration and are marked as "computed" in the resource type schema, in order to insert any default values the provider may know about. If the default value cannot be determined until apply time, the provider can return an unknown value. Providers are forbidden from planning a change that disagrees with any non-null argument in the configuration.

As a special exception, providers _are_ allowed to provide attribute values conflicting with configuration if and only if the planned value exactly matches the corresponding attribute value in the prior state. The provider can use this to signal that the new value is functionally equivalent to the old and thus no change is required.

func LongestCommonSubsequence

func LongestCommonSubsequence(xs, ys []cty.Value) []cty.Value

LongestCommonSubsequence finds a sequence of values that are common to both x and y, with the same relative ordering as in both collections. This result is useful as a first step towards computing a diff showing added/removed elements in a sequence.

The approached used here is a "naive" one, assuming that both xs and ys will generally be small in most reasonable Terraform configurations. For larger lists the time/space usage may be sub-optimal.

A pair of lists may have multiple longest common subsequences. In that case, the one selected by this function is undefined.

func NormalizeObjectFromLegacySDK

func NormalizeObjectFromLegacySDK(val cty.Value, schema *configschema.Block) cty.Value

NormalizeObjectFromLegacySDK takes an object that may have been generated by the legacy Terraform SDK (i.e. returned from a provider with the LegacyTypeSystem opt-out set) and does its best to normalize it for the assumptions we would normally enforce if the provider had not opted out.

In particular, this function guarantees that a value representing a nested block will never itself be unknown or null, instead representing that as a non-null value that may contain null/unknown values.

The input value must still conform to the implied type of the given schema, or else this function may produce garbage results or panic. This is usually okay because type consistency is enforced when deserializing the value returned from the provider over the RPC wire protocol anyway.

func PlannedDataResourceObject

func PlannedDataResourceObject(schema *configschema.Block, config cty.Value) cty.Value

PlannedDataResourceObject is similar to ProposedNewObject but tailored for planning data resources in particular. Specifically, it replaces the values of any Computed attributes not set in the configuration with an unknown value, which serves as a placeholder for a value to be filled in by the provider when the data resource is finally read.

Data resources are different because the planning of them is handled entirely within Terraform Core and not subject to customization by the provider. This function is, in effect, producing an equivalent result to passing the ProposedNewObject result into a provider's PlanResourceChange function, assuming a fixed implementation of PlanResourceChange that just fills in unknown values as needed.

func ProposedNewObject

func ProposedNewObject(schema *configschema.Block, prior, config cty.Value) cty.Value

ProposedNewObject constructs a proposed new object value by combining the computed attribute values from "prior" with the configured attribute values from "config".

Both value must conform to the given schema's implied type, or this function will panic.

The prior value must be wholly known, but the config value may be unknown or have nested unknown values.

The merging of the two objects includes the attributes of any nested blocks, which will be correlated in a manner appropriate for their nesting mode. Note in particular that the correlation for blocks backed by sets is a heuristic based on matching non-computed attribute values and so it may produce strange results with more "extreme" cases, such as a nested set block where _all_ attributes are computed.