states: New package with modern models for Terraform state

Our previous state models in the "terraform" package had a few limitations
that are addressed here:

- Instance attributes were stored as map[string]string with dot-separated
  keys representing traversals through a data structure. Now that we have
  a full type system, it's preferable to store it as a real data
  structure.

- The existing state structures skipped over the "resource" concept and
  went straight to resource instance, requiring heuristics to decide
  whether a particular resource should appear as a single object or as
  a list of objects when used in configuration expressions.

- Related to the previous point, the state models also used incorrect
  terminology where "ResourceState" was really a resource instance state
  and "InstanceState" was really the state of a particular remote object
  associated with an instance. These new models use the correct names for
  each of these, introducing the idea of a "ResourceInstanceObject" as
  the local record of a remote object associated with an instance.

This is a first pass at fleshing out a new model for state. Undoubtedly
there will be further iterations of this as we work on integrating these
new models into the "terraform" package.

These new model types no longer serve double-duty as a description of the
JSON state file format, since they are for in-memory use only. A
subsequent commit will introduce a separate package that deals with
persisting state to files and reloading those files later.

states/doc.go

@@ -0,0 +1,3 @@
+// Package states contains the types that are used to represent Terraform
+// states.
+package states

states/eachmode_string.go

@@ -0,0 +1,26 @@
+// Code generated by "stringer -type EachMode"; DO NOT EDIT.
+
+package states
+
+import "strconv"
+
+const (
+	_EachMode_name_0 = "NoEach"
+	_EachMode_name_1 = "EachListEachMap"
+)
+
+var (
+	_EachMode_index_1 = [...]uint8{0, 8, 15}
+)
+
+func (i EachMode) String() string {
+	switch {
+	case i == 0:
+		return _EachMode_name_0
+	case 76 <= i && i <= 77:
+		i -= 76
+		return _EachMode_name_1[_EachMode_index_1[i]:_EachMode_index_1[i+1]]
+	default:
+		return "EachMode(" + strconv.FormatInt(int64(i), 10) + ")"
+	}
+}

states/import.go

@@ -0,0 +1,22 @@
+package states
+
+import (
+	"github.com/zclconf/go-cty/cty"
+)
+
+// ImportedObject represents an object being imported into Terraform with the
+// help of a provider. An ImportedObject is a RemoteObject that has been read
+// by the provider's import handler but hasn't yet been committed to state.
+type ImportedObject struct {
+	ResourceType string
+
+	// Value is the value (of the object type implied by the associated resource
+	// type schema) that represents this remote object in Terraform Language
+	// expressions and is compared with configuration when producing a diff.
+	Value cty.Value
+
+	// Private corresponds to the field of the same name on
+	// ResourceInstanceObject, where the provider can record private data that
+	// will be available for future operations.
+	Private cty.Value
+}

states/instance_generation.go

@@ -0,0 +1,24 @@
+package states
+
+// Generation is used to represent multiple objects in a succession of objects
+// represented by a single resource instance address. A resource instance can
+// have multiple generations over its lifetime due to object replacement
+// (when a change can't be applied without destroying and re-creating), and
+// multiple generations can exist at the same time when create_before_destroy
+// is used.
+//
+// A Generation value can either be the value of the variable "CurrentGen" or
+// a value of type DeposedKey. Generation values can be compared for equality
+// using "==" and used as map keys. The zero value of Generation (nil) is not
+// a valid generation and must not be used.
+type Generation interface {
+	generation()
+}
+
+// CurrentGen is the Generation representing the currently-active object for
+// a resource instance.
+var CurrentGen Generation
+
+type currentGen struct{}
+
+func (g currentGen) generation() {}

states/instance_object.go

@@ -0,0 +1,87 @@
+package states
+
+import (
+	"github.com/zclconf/go-cty/cty"
+
+	"github.com/hashicorp/terraform/addrs"
+)
+
+// ResourceInstanceObject is the local representation of a specific remote
+// object associated with a resource instance. In practice not all remote
+// objects are actually remote in the sense of being accessed over the network,
+// but this is the most common case.
+//
+// It is not valid to mutate a ResourceInstanceObject once it has been created.
+// Instead, create a new object and replace the existing one.
+type ResourceInstanceObject struct {
+	// SchemaVersion identifies which version of the resource type schema the
+	// Attrs or AttrsFlat value conforms to. If this is less than the schema
+	// version number given by the current provider version then the value
+	// must be upgraded to the latest version before use. If it is greater
+	// than the current version number then the provider must be upgraded
+	// before any operations can be performed.
+	SchemaVersion uint64
+
+	// AttrsJSON is a JSON-encoded representation of the object attributes,
+	// encoding the value (of the object type implied by the associated resource
+	// type schema) that represents this remote object in Terraform Language
+	// expressions, and is compared with configuration when producing a diff.
+	//
+	// This is retained in JSON format here because it may require preprocessing
+	// before decoding if, for example, the stored attributes are for an older
+	// schema version which the provider must upgrade before use. If the
+	// version is current, it is valid to simply decode this using the
+	// type implied by the current schema, without the need for the provider
+	// to perform an upgrade first.
+	//
+	// When writing a ResourceInstanceObject into the state, AttrsJSON should
+	// always be conformant to the current schema version and the current
+	// schema version should be recorded in the SchemaVersion field.
+	AttrsJSON []byte
+
+	// AttrsFlat is a legacy form of attributes used in older state file
+	// formats, and in the new state format for objects that haven't yet been
+	// upgraded. This attribute is mutually exclusive with Attrs: for any
+	// ResourceInstanceObject, only one of these attributes may be populated
+	// and the other must be nil.
+	//
+	// An instance object with this field populated should be upgraded to use
+	// Attrs at the earliest opportunity, since this legacy flatmap-based
+	// format will be phased out over time. AttrsFlat should not be used when
+	// writing new or updated objects to state; instead, callers must follow
+	// the recommendations in the AttrsJSON documentation above.
+	AttrsFlat map[string]string
+
+	// Internal is an opaque value set by the provider when this object was
+	// last created or updated. Terraform Core does not use this value in
+	// any way and it is not exposed anywhere in the user interface, so
+	// a provider can use it for retaining any necessary private state.
+	Private cty.Value
+
+	// Status represents the "readiness" of the object as of the last time
+	// it was updated.
+	Status ObjectStatus
+
+	// Dependencies is a set of other addresses in the same module which
+	// this instance depended on when the given attributes were evaluated.
+	// This is used to construct the dependency relationships for an object
+	// whose configuration is no longer available, such as if it has been
+	// removed from configuration altogether, or is now deposed.
+	Dependencies []addrs.Referenceable
+}
+
+// ObjectStatus represents the status of a RemoteObject.
+type ObjectStatus rune
+
+//go:generate stringer -type ObjectStatus
+
+const (
+	// ObjectReady is an object status for an object that is ready to use.
+	ObjectReady ObjectStatus = 'R'
+
+	// ObjectTainted is an object status representing an object that is in
+	// an unrecoverable bad state due to a partial failure during a create,
+	// update, or delete operation. Since it cannot be moved into the
+	// ObjectRead state, a tainted object must be replaced.
+	ObjectTainted ObjectStatus = 'T'
+)

states/module.go

@@ -0,0 +1,192 @@
+package states
+
+import (
+	"fmt"
+
+	"github.com/zclconf/go-cty/cty"
+
+	"github.com/hashicorp/terraform/addrs"
+)
+
+// Module is a container for the states of objects within a particular module.
+type Module struct {
+	Addr addrs.ModuleInstance
+
+	// Resources contains the state for each resource. The keys in this map are
+	// an implementation detail and must not be used by outside callers.
+	Resources map[string]*Resource
+
+	// OutputValues contains the state for each output value. The keys in this
+	// map are output value names.
+	OutputValues map[string]*OutputValue
+
+	// LocalValues contains the value for each named output value. The keys
+	// in this map are local value names.
+	LocalValues map[string]cty.Value
+}
+
+// NewModule constructs an empty module state for the given module address.
+func NewModule(addr addrs.ModuleInstance) *Module {
+	return &Module{
+		Addr:         addr,
+		Resources:    map[string]*Resource{},
+		OutputValues: map[string]*OutputValue{},
+		LocalValues:  map[string]cty.Value{},
+	}
+}
+
+// Resource returns the state for the resource with the given address within
+// the receiving module state, or nil if the requested resource is not tracked
+// in the state.
+func (ms *Module) Resource(addr addrs.Resource) *Resource {
+	return ms.Resources[addr.String()]
+}
+
+// ResourceInstance returns the state for the resource instance with the given
+// address within the receiving module state, or nil if the requested instance
+// is not tracked in the state.
+func (ms *Module) ResourceInstance(addr addrs.ResourceInstance) *ResourceInstance {
+	rs := ms.Resource(addr.Resource)
+	if rs == nil {
+		return nil
+	}
+	return rs.Instance(addr.Key)
+}
+
+// SetResourceMeta updates the resource-level metadata for the resource
+// with the given address, creating the resource state for it if it doesn't
+// already exist.
+func (ms *Module) SetResourceMeta(addr addrs.Resource, eachMode EachMode, provider addrs.AbsProviderConfig) {
+	rs := ms.Resource(addr)
+	if rs == nil {
+		rs = &Resource{
+			Addr:      addr,
+			Instances: map[addrs.InstanceKey]*ResourceInstance{},
+		}
+		ms.Resources[addr.String()] = rs
+	}
+
+	rs.EachMode = eachMode
+	rs.ProviderConfig = provider
+}
+
+// RemoveResource removes the entire state for the given resource, taking with
+// it any instances associated with the resource. This should generally be
+// called only for resource objects whose instances have all been destroyed.
+func (ms *Module) RemoveResource(addr addrs.Resource) {
+	delete(ms.Resources, addr.String())
+}
+
+// SetResourceInstanceCurrent saves the given instance object as the current
+// generation of the resource instance with the given address, simulataneously
+// updating the recorded provider configuration address, dependencies, and
+// resource EachMode.
+//
+// Any existing current instance object for the given resource is overwritten.
+// Set obj to nil to remove the primary generation object altogether. If there
+// are no deposed objects then the instance will be removed altogether.
+//
+// The provider address and "each mode" are resource-wide settings and so they
+// are updated for all other instances of the same resource as a side-effect of
+// this call.
+func (ms *Module) SetResourceInstanceCurrent(addr addrs.ResourceInstance, obj *ResourceInstanceObject, provider addrs.AbsProviderConfig) {
+	ms.SetResourceMeta(addr.Resource, eachModeForInstanceKey(addr.Key), provider)
+
+	rs := ms.Resource(addr.Resource)
+	is := rs.EnsureInstance(addr.Key)
+
+	is.Current = obj
+
+	if !is.HasObjects() {
+		// If we have no objects at all then we'll clean up.
+		delete(rs.Instances, addr.Key)
+	}
+	if rs.EachMode == NoEach && len(rs.Instances) == 0 {
+		// Also clean up if we only expect to have one instance anyway
+		// and there are none. We leave the resource behind if an each mode
+		// is active because an empty list or map of instances is a valid state.
+		delete(ms.Resources, addr.Resource.String())
+	}
+}
+
+// SetResourceInstanceDeposed saves the given instance object as a deposed
+// generation of the resource instance with the given address and deposed key.
+//
+// Call this method only for pre-existing deposed objects that already have
+// a known DeposedKey. For example, this method is useful if reloading objects
+// that were persisted to a state file. To mark the current object as deposed,
+// use DeposeResourceInstanceObject instead.
+//
+// The resource that contains the given instance must already exist in the
+// state, or this method will panic. Use Resource to check first if its
+// presence is not already guaranteed.
+//
+// Any existing current instance object for the given resource and deposed key
+// is overwritten. Set obj to nil to remove the deposed object altogether. If
+// the instance is left with no objects after this operation then it will
+// be removed from its containing resource altogether.
+func (ms *Module) SetResourceInstanceDeposed(addr addrs.ResourceInstance, key DeposedKey, obj *ResourceInstanceObject) {
+	rs := ms.Resource(addr.Resource)
+	if rs == nil {
+		panic(fmt.Sprintf("attempt to register deposed instance object for non-existent resource %s", addr.Resource.Absolute(ms.Addr)))
+	}
+	is := rs.EnsureInstance(addr.Key)
+
+	is.Current = obj
+
+	if !is.HasObjects() {
+		// If we have no objects at all then we'll clean up.
+		delete(rs.Instances, addr.Key)
+	}
+	if rs.EachMode == NoEach && len(rs.Instances) == 0 {
+		// Also clean up if we only expect to have one instance anyway
+		// and there are none. We leave the resource behind if an each mode
+		// is active because an empty list or map of instances is a valid state.
+		delete(ms.Resources, addr.Resource.String())
+	}
+}
+
+// DeposeResourceInstanceObject moves the current instance object for the
+// given resource instance address into the deposed set, leaving the instance
+// without a current object.
+//
+// The return value is the newly-allocated deposed key, or NotDeposed if the
+// given instance is already lacking a current object.
+func (ms *Module) DeposeResourceInstanceObject(addr addrs.ResourceInstance) DeposedKey {
+	is := ms.ResourceInstance(addr)
+	if is == nil {
+		return NotDeposed
+	}
+	return is.DeposeCurrentObject()
+}
+
+// SetOutputValue writes an output value into the state, overwriting any
+// existing value of the same name.
+func (ms *Module) SetOutputValue(name string, value cty.Value, sensitive bool) *OutputValue {
+	os := &OutputValue{
+		Value:     value,
+		Sensitive: sensitive,
+	}
+	ms.OutputValues[name] = os
+	return os
+}
+
+// RemoveOutputValue removes the output value of the given name from the state,
+// if it exists. This method is a no-op if there is no value of the given
+// name.
+func (ms *Module) RemoveOutputValue(name string) {
+	delete(ms.OutputValues, name)
+}
+
+// SetLocalValue writes a local value into the state, overwriting any
+// existing value of the same name.
+func (ms *Module) SetLocalValue(name string, value cty.Value) {
+	ms.LocalValues[name] = value
+}
+
+// RemoveLocalValue removes the local value of the given name from the state,
+// if it exists. This method is a no-op if there is no value of the given
+// name.
+func (ms *Module) RemoveLocalValue(name string) {
+	delete(ms.LocalValues, name)
+}

states/objectstatus_string.go

@@ -0,0 +1,21 @@
+// Code generated by "stringer -type ObjectStatus"; DO NOT EDIT.
+
+package states
+
+import "strconv"
+
+const (
+	_ObjectStatus_name_0 = "ObjectReady"
+	_ObjectStatus_name_1 = "ObjectTainted"
+)
+
+func (i ObjectStatus) String() string {
+	switch {
+	case i == 82:
+		return _ObjectStatus_name_0
+	case i == 84:
+		return _ObjectStatus_name_1
+	default:
+		return "ObjectStatus(" + strconv.FormatInt(int64(i), 10) + ")"
+	}
+}

states/output_value.go

@@ -0,0 +1,14 @@
+package states
+
+import (
+	"github.com/zclconf/go-cty/cty"
+)
+
+// OutputValue represents the state of a particular output value.
+//
+// It is not valid to mutate an OutputValue object once it has been created.
+// Instead, create an entirely new OutputValue to replace the previous one.
+type OutputValue struct {
+	Value     cty.Value
+	Sensitive bool
+}

states/resource.go

@@ -0,0 +1,212 @@
+package states
+
+import (
+	"fmt"
+	"math/rand"
+	"time"
+
+	"github.com/hashicorp/terraform/addrs"
+)
+
+// Resource represents the state of a resource.
+type Resource struct {
+	// Addr is the module-relative address for the resource this state object
+	// belongs to.
+	Addr addrs.Resource
+
+	// EachMode is the multi-instance mode currently in use for this resource,
+	// or NoEach if this is a single-instance resource. This dictates what
+	// type of value is returned when accessing this resource via expressions
+	// in the Terraform language.
+	EachMode EachMode
+
+	// Instances contains the potentially-multiple instances associated with
+	// this resource. This map can contain a mixture of different key types,
+	// but only the ones of InstanceKeyType are considered current.
+	Instances map[addrs.InstanceKey]*ResourceInstance
+
+	// ProviderConfig is the absolute address for the provider configuration that
+	// most recently managed this resource. This is used to connect a resource
+	// with a provider configuration when the resource configuration block is
+	// not available, such as if it has been removed from configuration
+	// altogether.
+	ProviderConfig addrs.AbsProviderConfig
+}
+
+// Instance returns the state for the instance with the given key, or nil
+// if no such instance is tracked within the state.
+func (rs *Resource) Instance(key addrs.InstanceKey) *ResourceInstance {
+	return rs.Instances[key]
+}
+
+// EnsureInstance returns the state for the instance with the given key,
+// creating a new empty state for it if one doesn't already exist.
+//
+// Because this may create and save a new state, it is considered to be
+// a write operation.
+func (rs *Resource) EnsureInstance(key addrs.InstanceKey) *ResourceInstance {
+	ret := rs.Instance(key)
+	if ret == nil {
+		ret = NewResourceInstance()
+		rs.Instances[key] = ret
+	}
+	return ret
+}
+
+// ResourceInstance represents the state of a particular instance of a resource.
+type ResourceInstance struct {
+	// Current, if non-nil, is the remote object that is currently represented
+	// by the corresponding resource instance.
+	Current *ResourceInstanceObject
+
+	// Deposed, if len > 0, contains any remote objects that were previously
+	// represented by the corresponding resource instance but have been
+	// replaced and are pending destruction due to the create_before_destroy
+	// lifecycle mode.
+	Deposed map[DeposedKey]*ResourceInstanceObject
+}
+
+// NewResourceInstance constructs and returns a new ResourceInstance, ready to
+// use.
+func NewResourceInstance() *ResourceInstance {
+	return &ResourceInstance{
+		Deposed: map[DeposedKey]*ResourceInstanceObject{},
+	}
+}
+
+// HasCurrent returns true if this resource instance has a "current"-generation
+// object. Most instances do, but this can briefly be false during a
+// create-before-destroy replace operation when the current has been deposed
+// but its replacement has not yet been created.
+func (i *ResourceInstance) HasCurrent() bool {
+	return i != nil && i.Current != nil
+}
+
+// HasDeposed returns true if this resource instance has a deposed object
+// with the given key.
+func (i *ResourceInstance) HasDeposed(key DeposedKey) bool {
+	return i != nil && i.Deposed[key] != nil
+}
+
+// HasAnyDeposed returns true if this resource instance has one or more
+// deposed objects.
+func (i *ResourceInstance) HasAnyDeposed() bool {
+	return i != nil && len(i.Deposed) > 0
+}
+
+// HasObjects returns true if this resource has any objects at all, whether
+// current or deposed.
+func (i *ResourceInstance) HasObjects() bool {
+	return i.Current != nil || len(i.Deposed) != 0
+}
+
+// DeposeCurrentObject moves the current generation object, if present, into
+// the deposed set. After this method returns, the instance has no current
+// object.
+//
+// The return value is either the newly-allocated deposed key, or NotDeposed
+// if the instance is already lacking a current instance object.
+func (i *ResourceInstance) DeposeCurrentObject() DeposedKey {
+	if !i.HasCurrent() {
+		return NotDeposed
+	}
+
+	key := i.findUnusedDeposedKey()
+	i.Deposed[key] = i.Current
+	i.Current = nil
+	return key
+}
+
+// GetGeneration retrieves the object of the given generation from the
+// ResourceInstance, or returns nil if there is no such object.
+//
+// If the given generation is nil or invalid, this method will panic.
+func (i *ResourceInstance) GetGeneration(gen Generation) *ResourceInstanceObject {
+	if gen == CurrentGen {
+		return i.Current
+	}
+	if dk, ok := gen.(DeposedKey); ok {
+		return i.Deposed[dk]
+	}
+	if gen == nil {
+		panic(fmt.Sprintf("get with nil Generation"))
+	}
+	// Should never fall out here, since the above covers all possible
+	// Generation values.
+	panic(fmt.Sprintf("get invalid Generation %#v", gen))
+}
+
+// findUnusedDeposedKey generates a unique DeposedKey that is guaranteed not to
+// already be in use for this instance.
+func (i *ResourceInstance) findUnusedDeposedKey() DeposedKey {
+	for {
+		key := NewDeposedKey()
+		if _, exists := i.Deposed[key]; !exists {
+			return key
+		}
+		// Spin until we find a unique one. This shouldn't take long, because
+		// we have a 32-bit keyspace and there's rarely more than one deposed
+		// instance.
+	}
+}
+
+// EachMode specifies the multi-instance mode for a resource.
+type EachMode rune
+
+const (
+	NoEach   EachMode = 0
+	EachList EachMode = 'L'
+	EachMap  EachMode = 'M'
+)
+
+//go:generate stringer -type EachMode
+
+func eachModeForInstanceKey(key addrs.InstanceKey) EachMode {
+	switch key.(type) {
+	case addrs.IntKey:
+		return EachList
+	case addrs.StringKey:
+		return EachMap
+	default:
+		if key == addrs.NoKey {
+			return NoEach
+		}
+		panic(fmt.Sprintf("don't know an each mode for instance key %#v", key))
+	}
+}
+
+// DeposedKey is a 8-character hex string used to uniquely identify deposed
+// instance objects in the state.
+type DeposedKey string
+
+// NotDeposed is a special invalid value of DeposedKey that is used to represent
+// the absense of a deposed key. It must not be used as an actual deposed key.
+const NotDeposed = DeposedKey("")
+
+var deposedKeyRand = rand.New(rand.NewSource(time.Now().UnixNano()))
+
+// NewDeposedKey generates a pseudo-random deposed key. Because of the short
+// length of these keys, uniqueness is not a natural consequence and so the
+// caller should test to see if the generated key is already in use and generate
+// another if so, until a unique key is found.
+func NewDeposedKey() DeposedKey {
+	v := deposedKeyRand.Uint32()
+	return DeposedKey(fmt.Sprintf("%08x", v))
+}
+
+func (k DeposedKey) String() string {
+	return string(k)
+}
+
+func (k DeposedKey) GoString() string {
+	ks := string(k)
+	switch {
+	case ks == "":
+		return "states.NotDeposed"
+	default:
+		return fmt.Sprintf("states.DeposedKey(%s)", ks)
+	}
+}
+
+// generation is an implementation of Generation.
+func (k DeposedKey) generation() {}

states/resource_test.go

@@ -0,0 +1,56 @@
+package states
+
+import (
+	"testing"
+)
+
+func TestResourceInstanceDeposeCurrentObject(t *testing.T) {
+	obj := &ResourceInstanceObject{
+	// Empty for the sake of this test, because we're just going to
+	// compare by pointer below anyway.
+	}
+
+	is := NewResourceInstance()
+	is.Current = obj
+	var dk DeposedKey
+
+	t.Run("first depose", func(t *testing.T) {
+		dk = is.DeposeCurrentObject() // dk is randomly-generated but should be eight characters long
+		t.Logf("deposedKey is %q", dk)
+
+		if got := is.Current; got != nil {
+			t.Errorf("current is %#v; want nil", got)
+		}
+		if got, want := is.Deposed[dk], obj; got != want {
+			t.Errorf("deposed object pointer is %#v; want %#v", got, want)
+		}
+		if got, want := len(is.Deposed), 1; got != want {
+			t.Errorf("wrong len(is.Deposed) %d; want %d", got, want)
+		}
+		if got, want := len(dk), 8; got != want {
+			t.Errorf("wrong len(deposedkey) %d; want %d", got, want)
+		}
+	})
+
+	t.Run("second depose", func(t *testing.T) {
+		notDK := is.DeposeCurrentObject()
+		if notDK != NotDeposed {
+			t.Errorf("got deposedKey %q; want NotDeposed", notDK)
+		}
+
+		// Make sure we really did abort early, and haven't corrupted the
+		// state somehow.
+		if got := is.Current; got != nil {
+			t.Errorf("current is %#v; want nil", got)
+		}
+		if got, want := is.Deposed[dk], obj; got != want {
+			t.Errorf("deposed object pointer is %#v; want %#v", got, want)
+		}
+		if got, want := len(is.Deposed), 1; got != want {
+			t.Errorf("wrong len(is.Deposed) %d; want %d", got, want)
+		}
+		if got, want := len(dk), 8; got != want {
+			t.Errorf("wrong len(deposedkey) %d; want %d", got, want)
+		}
+	})
+}

states/state.go

@@ -0,0 +1,96 @@
+package states
+
+import (
+	"github.com/zclconf/go-cty/cty"
+
+	"github.com/hashicorp/terraform/addrs"
+)
+
+// State is the top-level type of a Terraform state.
+//
+// A state should be mutated only via its accessor methods, to ensure that
+// invariants are preserved.
+//
+// Access to State and the nested values within it is not concurrency-safe,
+// so when accessing a State object concurrently it is the caller's
+// responsibility to ensure that only one write is in progress at a time
+// and that reads only occur when no write is in progress.
+type State struct {
+	// Modules contains the state for each module. The keys in this map are
+	// an implementation detail and must not be used by outside callers.
+	Modules map[string]*Module
+}
+
+// NewState constructs a minimal empty state, containing an empty root module.
+func NewState() *State {
+	modules := map[string]*Module{}
+	modules[addrs.RootModuleInstance.String()] = NewModule(addrs.RootModuleInstance)
+	return &State{
+		Modules: modules,
+	}
+}
+
+// Module returns the state for the module with the given address, or nil if
+// the requested module is not tracked in the state.
+func (s *State) Module(addr addrs.ModuleInstance) *Module {
+	return s.Modules[addr.String()]
+}
+
+// RootModule is a convenient alias for Module(addrs.RootModuleInstance).
+func (s *State) RootModule() *Module {
+	return s.Modules[addrs.RootModuleInstance.String()]
+}
+
+// EnsureModule returns the state for the module with the given address,
+// creating and adding a new one if necessary.
+//
+// Since this might modify the state to add a new instance, it is considered
+// to be a write operation.
+func (s *State) EnsureModule(addr addrs.ModuleInstance) *Module {
+	ms := s.Module(addr)
+	if ms == nil {
+		ms = NewModule(addr)
+		s.Modules[addr.String()] = ms
+	}
+	return ms
+}
+
+// Resource returns the state for the resource with the given address, or nil
+// if no such resource is tracked in the state.
+func (s *State) Resource(addr addrs.AbsResource) *Resource {
+	ms := s.Module(addr.Module)
+	if ms == nil {
+		return nil
+	}
+	return ms.Resource(addr.Resource)
+}
+
+// ResourceInstance returns the state for the resource instance with the given
+// address, or nil if no such resource is tracked in the state.
+func (s *State) ResourceInstance(addr addrs.AbsResourceInstance) *ResourceInstance {
+	ms := s.Module(addr.Module)
+	if ms == nil {
+		return nil
+	}
+	return ms.ResourceInstance(addr.Resource)
+}
+
+// OutputValue returns the state for the output value with the given address,
+// or nil if no such output value is tracked in the state.
+func (s *State) OutputValue(addr addrs.AbsOutputValue) *OutputValue {
+	ms := s.Module(addr.Module)
+	if ms == nil {
+		return nil
+	}
+	return ms.OutputValues[addr.OutputValue.Name]
+}
+
+// LocalValue returns the value of the named local value with the given address,
+// or cty.NilVal if no such value is tracked in the state.
+func (s *State) LocalValue(addr addrs.AbsLocalValue) cty.Value {
+	ms := s.Module(addr.Module)
+	if ms == nil {
+		return cty.NilVal
+	}
+	return ms.LocalValues[addr.LocalValue.Name]
+}

states/state_deepcopy.go

@@ -0,0 +1,179 @@
+package states
+
+import (
+	"github.com/hashicorp/terraform/addrs"
+	"github.com/zclconf/go-cty/cty"
+)
+
+// Taking deep copies of states is an important operation because state is
+// otherwise a mutable data structure that is challenging to share across
+// many separate callers. It is important that the DeepCopy implementations
+// in this file comprehensively copy all parts of the state data structure
+// that could be mutated via pointers.
+
+// DeepCopy returns a new state that contains equivalent data to the reciever
+// but shares no backing memory in common.
+//
+// As with all methods on State, this method is not safe to use concurrently
+// with writing to any portion of the recieving data structure. It is the
+// caller's responsibility to ensure mutual exclusion for the duration of the
+// operation, but may then freely modify the receiver and the returned copy
+// independently once this method returns.
+func (s *State) DeepCopy() *State {
+	if s == nil {
+		return nil
+	}
+
+	modules := make(map[string]*Module, len(s.Modules))
+	for k, m := range s.Modules {
+		modules[k] = m.DeepCopy()
+	}
+	return &State{
+		Modules: modules,
+	}
+}
+
+// DeepCopy returns a new module state that contains equivalent data to the
+// receiver but shares no backing memory in common.
+//
+// As with all methods on Module, this method is not safe to use concurrently
+// with writing to any portion of the recieving data structure. It is the
+// caller's responsibility to ensure mutual exclusion for the duration of the
+// operation, but may then freely modify the receiver and the returned copy
+// independently once this method returns.
+func (ms *Module) DeepCopy() *Module {
+	if ms == nil {
+		return nil
+	}
+
+	resources := make(map[string]*Resource, len(ms.Resources))
+	for k, r := range ms.Resources {
+		resources[k] = r.DeepCopy()
+	}
+	outputValues := make(map[string]*OutputValue, len(ms.OutputValues))
+	for k, v := range ms.OutputValues {
+		outputValues[k] = v.DeepCopy()
+	}
+	localValues := make(map[string]cty.Value, len(ms.LocalValues))
+	for k, v := range ms.LocalValues {
+		// cty.Value is immutable, so we don't need to copy these.
+		localValues[k] = v
+	}
+
+	return &Module{
+		Addr:         ms.Addr, // technically mutable, but immutable by convention
+		Resources:    resources,
+		OutputValues: outputValues,
+		LocalValues:  localValues,
+	}
+}
+
+// DeepCopy returns a new resource state that contains equivalent data to the
+// receiver but shares no backing memory in common.
+//
+// As with all methods on Resource, this method is not safe to use concurrently
+// with writing to any portion of the recieving data structure. It is the
+// caller's responsibility to ensure mutual exclusion for the duration of the
+// operation, but may then freely modify the receiver and the returned copy
+// independently once this method returns.
+func (rs *Resource) DeepCopy() *Resource {
+	if rs == nil {
+		return nil
+	}
+
+	instances := make(map[addrs.InstanceKey]*ResourceInstance, len(rs.Instances))
+	for k, i := range rs.Instances {
+		instances[k] = i.DeepCopy()
+	}
+
+	return &Resource{
+		Addr:           rs.Addr,
+		EachMode:       rs.EachMode,
+		Instances:      instances,
+		ProviderConfig: rs.ProviderConfig, // technically mutable, but immutable by convention
+	}
+}
+
+// DeepCopy returns a new resource instance state that contains equivalent data
+// to the receiver but shares no backing memory in common.
+//
+// As with all methods on ResourceInstance, this method is not safe to use
+// concurrently with writing to any portion of the recieving data structure. It
+// is the caller's responsibility to ensure mutual exclusion for the duration
+// of the operation, but may then freely modify the receiver and the returned
+// copy independently once this method returns.
+func (is *ResourceInstance) DeepCopy() *ResourceInstance {
+	if is == nil {
+		return nil
+	}
+
+	deposed := make(map[DeposedKey]*ResourceInstanceObject, len(is.Deposed))
+	for k, obj := range is.Deposed {
+		deposed[k] = obj.DeepCopy()
+	}
+
+	return &ResourceInstance{
+		Current: is.Current.DeepCopy(),
+		Deposed: deposed,
+	}
+}
+
+// DeepCopy returns a new resource instance object that contains equivalent data
+// to the receiver but shares no backing memory in common.
+//
+// As with all methods on ResourceInstanceObject, this method is not safe to use
+// concurrently with writing to any portion of the recieving data structure. It
+// is the caller's responsibility to ensure mutual exclusion for the duration
+// of the operation, but may then freely modify the receiver and the returned
+// copy independently once this method returns.
+func (obj *ResourceInstanceObject) DeepCopy() *ResourceInstanceObject {
+	if obj == nil {
+		return nil
+	}
+
+	var attrsFlat map[string]string
+	if obj.AttrsFlat != nil {
+		attrsFlat := make(map[string]string, len(obj.AttrsFlat))
+		for k, v := range obj.AttrsFlat {
+			attrsFlat[k] = v
+		}
+	}
+
+	var attrsJSON []byte
+	if obj.AttrsJSON != nil {
+		attrsJSON := make([]byte, len(obj.AttrsJSON))
+		copy(attrsJSON, obj.AttrsJSON)
+	}
+
+	// Some addrs.Referencable implementations are technically mutable, but
+	// we treat them as immutable by convention and so we don't deep-copy here.
+	dependencies := make([]addrs.Referenceable, len(obj.Dependencies))
+
+	return &ResourceInstanceObject{
+		Status:        obj.Status,
+		SchemaVersion: obj.SchemaVersion,
+		Private:       obj.Private,
+		AttrsFlat:     attrsFlat,
+		AttrsJSON:     attrsJSON,
+		Dependencies:  dependencies,
+	}
+}
+
+// DeepCopy returns a new output value state that contains equivalent data
+// to the receiver but shares no backing memory in common.
+//
+// As with all methods on OutputValue, this method is not safe to use
+// concurrently with writing to any portion of the recieving data structure. It
+// is the caller's responsibility to ensure mutual exclusion for the duration
+// of the operation, but may then freely modify the receiver and the returned
+// copy independently once this method returns.
+func (os *OutputValue) DeepCopy() *OutputValue {
+	if os == nil {
+		return nil
+	}
+
+	return &OutputValue{
+		Value:     os.Value,
+		Sensitive: os.Sensitive,
+	}
+}

states/state_equal.go

@@ -0,0 +1,18 @@
+package states
+
+import (
+	"reflect"
+)
+
+// Equal returns true if the receiver is functionally equivalent to other,
+// including any ephemeral portions of the state that would not be included
+// if the state were saved to files.
+//
+// To test only the persistent portions of two states for equality, instead
+// use statefile.StatesMarshalEqual.
+func (s *State) Equal(other *State) bool {
+	// For the moment this is sufficient, but we may need to do something
+	// more elaborate in future if we have any portions of state that require
+	// more sophisticated comparisons.
+	return reflect.DeepEqual(s, other)
+}

states/state_test.go

@@ -0,0 +1,117 @@
+package states
+
+import (
+	"testing"
+
+	"github.com/go-test/deep"
+	"github.com/zclconf/go-cty/cty"
+
+	"github.com/hashicorp/terraform/addrs"
+)
+
+func TestState(t *testing.T) {
+	// This basic tests exercises the main mutation methods to construct
+	// a state. It is not fully comprehensive, so other tests should visit
+	// more esoteric codepaths.
+
+	state := NewState()
+
+	rootModule := state.RootModule()
+	if rootModule == nil {
+		t.Errorf("root module is nil; want valid object")
+	}
+
+	rootModule.SetLocalValue("foo", cty.StringVal("foo value"))
+	rootModule.SetOutputValue("bar", cty.StringVal("bar value"), false)
+	rootModule.SetOutputValue("secret", cty.StringVal("secret value"), true)
+	rootModule.SetResourceInstanceCurrent(
+		addrs.Resource{
+			Mode: addrs.ManagedResourceMode,
+			Type: "test_thing",
+			Name: "baz",
+		}.Instance(addrs.IntKey(0)),
+		&ResourceInstanceObject{
+			Status:        ObjectReady,
+			SchemaVersion: 1,
+			AttrsJSON:     []byte(`{"woozles":"confuzles"}`),
+		},
+		addrs.ProviderConfig{
+			Type: "test",
+		}.Absolute(addrs.RootModuleInstance),
+	)
+
+	childModule := state.EnsureModule(addrs.RootModuleInstance.Child("child", addrs.NoKey))
+	childModule.SetOutputValue("pizza", cty.StringVal("hawaiian"), false)
+
+	want := &State{
+		Modules: map[string]*Module{
+			"": {
+				Addr: addrs.RootModuleInstance,
+				LocalValues: map[string]cty.Value{
+					"foo": cty.StringVal("foo value"),
+				},
+				OutputValues: map[string]*OutputValue{
+					"bar": {
+						Value:     cty.StringVal("bar value"),
+						Sensitive: false,
+					},
+					"secret": {
+						Value:     cty.StringVal("secret value"),
+						Sensitive: true,
+					},
+				},
+				Resources: map[string]*Resource{
+					"test_thing.baz": {
+						Addr: addrs.Resource{
+							Mode: addrs.ManagedResourceMode,
+							Type: "test_thing",
+							Name: "baz",
+						},
+						EachMode: EachList,
+						Instances: map[addrs.InstanceKey]*ResourceInstance{
+							addrs.IntKey(0): {
+								Current: &ResourceInstanceObject{
+									SchemaVersion: 1,
+									Status:        ObjectReady,
+									AttrsJSON:     []byte(`{"woozles":"confuzles"}`),
+								},
+								Deposed: map[DeposedKey]*ResourceInstanceObject{},
+							},
+						},
+						ProviderConfig: addrs.ProviderConfig{
+							Type: "test",
+						}.Absolute(addrs.RootModuleInstance),
+					},
+				},
+			},
+			"module.child": {
+				Addr:        addrs.RootModuleInstance.Child("child", addrs.NoKey),
+				LocalValues: map[string]cty.Value{},
+				OutputValues: map[string]*OutputValue{
+					"pizza": {
+						Value:     cty.StringVal("hawaiian"),
+						Sensitive: false,
+					},
+				},
+				Resources: map[string]*Resource{},
+			},
+		},
+	}
+
+	{
+		// Our structure goes deep, so we need to temporarily override the
+		// deep package settings to ensure that we visit the full structure.
+		oldDeepDepth := deep.MaxDepth
+		oldDeepCompareUnexp := deep.CompareUnexportedFields
+		deep.MaxDepth = 50
+		deep.CompareUnexportedFields = true
+		defer func() {
+			deep.MaxDepth = oldDeepDepth
+			deep.CompareUnexportedFields = oldDeepCompareUnexp
+		}()
+	}
+
+	for _, problem := range deep.Equal(state, want) {
+		t.Error(problem)
+	}
+}