github.com/kanishk98/terraform@v1.3.0-dev.0.20220917174235-661ca8088a6a/internal/states/instance_object.go (about)

     1  package states
     2  
     3  import (
     4  	"sort"
     5  
     6  	"github.com/zclconf/go-cty/cty"
     7  	ctyjson "github.com/zclconf/go-cty/cty/json"
     8  
     9  	"github.com/hashicorp/terraform/internal/addrs"
    10  )
    11  
    12  // ResourceInstanceObject is the local representation of a specific remote
    13  // object associated with a resource instance. In practice not all remote
    14  // objects are actually remote in the sense of being accessed over the network,
    15  // but this is the most common case.
    16  //
    17  // It is not valid to mutate a ResourceInstanceObject once it has been created.
    18  // Instead, create a new object and replace the existing one.
    19  type ResourceInstanceObject struct {
    20  	// Value is the object-typed value representing the remote object within
    21  	// Terraform.
    22  	Value cty.Value
    23  
    24  	// Private is an opaque value set by the provider when this object was
    25  	// last created or updated. Terraform Core does not use this value in
    26  	// any way and it is not exposed anywhere in the user interface, so
    27  	// a provider can use it for retaining any necessary private state.
    28  	Private []byte
    29  
    30  	// Status represents the "readiness" of the object as of the last time
    31  	// it was updated.
    32  	Status ObjectStatus
    33  
    34  	// Dependencies is a set of absolute address to other resources this
    35  	// instance dependeded on when it was applied. This is used to construct
    36  	// the dependency relationships for an object whose configuration is no
    37  	// longer available, such as if it has been removed from configuration
    38  	// altogether, or is now deposed.
    39  	Dependencies []addrs.ConfigResource
    40  
    41  	// CreateBeforeDestroy reflects the status of the lifecycle
    42  	// create_before_destroy option when this instance was last updated.
    43  	// Because create_before_destroy also effects the overall ordering of the
    44  	// destroy operations, we need to record the status to ensure a resource
    45  	// removed from the config will still be destroyed in the same manner.
    46  	CreateBeforeDestroy bool
    47  }
    48  
    49  // ObjectStatus represents the status of a RemoteObject.
    50  type ObjectStatus rune
    51  
    52  //go:generate go run golang.org/x/tools/cmd/stringer -type ObjectStatus
    53  
    54  const (
    55  	// ObjectReady is an object status for an object that is ready to use.
    56  	ObjectReady ObjectStatus = 'R'
    57  
    58  	// ObjectTainted is an object status representing an object that is in
    59  	// an unrecoverable bad state due to a partial failure during a create,
    60  	// update, or delete operation. Since it cannot be moved into the
    61  	// ObjectRead state, a tainted object must be replaced.
    62  	ObjectTainted ObjectStatus = 'T'
    63  
    64  	// ObjectPlanned is a special object status used only for the transient
    65  	// placeholder objects we place into state during the refresh and plan
    66  	// walks to stand in for objects that will be created during apply.
    67  	//
    68  	// Any object of this status must have a corresponding change recorded
    69  	// in the current plan, whose value must then be used in preference to
    70  	// the value stored in state when evaluating expressions. A planned
    71  	// object stored in state will be incomplete if any of its attributes are
    72  	// not yet known, and the plan must be consulted in order to "see" those
    73  	// unknown values, because the state is not able to represent them.
    74  	ObjectPlanned ObjectStatus = 'P'
    75  )
    76  
    77  // Encode marshals the value within the receiver to produce a
    78  // ResourceInstanceObjectSrc ready to be written to a state file.
    79  //
    80  // The given type must be the implied type of the resource type schema, and
    81  // the given value must conform to it. It is important to pass the schema
    82  // type and not the object's own type so that dynamically-typed attributes
    83  // will be stored correctly. The caller must also provide the version number
    84  // of the schema that the given type was derived from, which will be recorded
    85  // in the source object so it can be used to detect when schema migration is
    86  // required on read.
    87  //
    88  // The returned object may share internal references with the receiver and
    89  // so the caller must not mutate the receiver any further once once this
    90  // method is called.
    91  func (o *ResourceInstanceObject) Encode(ty cty.Type, schemaVersion uint64) (*ResourceInstanceObjectSrc, error) {
    92  	// If it contains marks, remove these marks before traversing the
    93  	// structure with UnknownAsNull, and save the PathValueMarks
    94  	// so we can save them in state.
    95  	val, pvm := o.Value.UnmarkDeepWithPaths()
    96  
    97  	// Our state serialization can't represent unknown values, so we convert
    98  	// them to nulls here. This is lossy, but nobody should be writing unknown
    99  	// values here and expecting to get them out again later.
   100  	//
   101  	// We get unknown values here while we're building out a "planned state"
   102  	// during the plan phase, but the value stored in the plan takes precedence
   103  	// for expression evaluation. The apply step should never produce unknown
   104  	// values, but if it does it's the responsibility of the caller to detect
   105  	// and raise an error about that.
   106  	val = cty.UnknownAsNull(val)
   107  
   108  	src, err := ctyjson.Marshal(val, ty)
   109  	if err != nil {
   110  		return nil, err
   111  	}
   112  
   113  	// Dependencies are collected and merged in an unordered format (using map
   114  	// keys as a set), then later changed to a slice (in random ordering) to be
   115  	// stored in state as an array. To avoid pointless thrashing of state in
   116  	// refresh-only runs, we can either override comparison of dependency lists
   117  	// (more desirable, but tricky for Reasons) or just sort when encoding.
   118  	// Encoding of instances can happen concurrently, so we must copy the
   119  	// dependencies to avoid mutating what may be a shared array of values.
   120  	dependencies := make([]addrs.ConfigResource, len(o.Dependencies))
   121  	copy(dependencies, o.Dependencies)
   122  
   123  	sort.Slice(dependencies, func(i, j int) bool { return dependencies[i].String() < dependencies[j].String() })
   124  
   125  	return &ResourceInstanceObjectSrc{
   126  		SchemaVersion:       schemaVersion,
   127  		AttrsJSON:           src,
   128  		AttrSensitivePaths:  pvm,
   129  		Private:             o.Private,
   130  		Status:              o.Status,
   131  		Dependencies:        dependencies,
   132  		CreateBeforeDestroy: o.CreateBeforeDestroy,
   133  	}, nil
   134  }
   135  
   136  // AsTainted returns a deep copy of the receiver with the status updated to
   137  // ObjectTainted.
   138  func (o *ResourceInstanceObject) AsTainted() *ResourceInstanceObject {
   139  	if o == nil {
   140  		// A nil object can't be tainted, but we'll allow this anyway to
   141  		// avoid a crash, since we presumably intend to eventually record
   142  		// the object has having been deleted anyway.
   143  		return nil
   144  	}
   145  	ret := o.DeepCopy()
   146  	ret.Status = ObjectTainted
   147  	return ret
   148  }