statefile

Documentation

Overview

Package statefile deals with the file format used to serialize states for persistent storage and then deserialize them into memory again later.

Index

• Variables
• func StatesMarshalEqual(a, b *states.State) bool
• func Write(s *File, w io.Writer) error
• func WriteForTest(s *File, w io.Writer) error
• type ErrUnusableState
  • func (e *ErrUnusableState) Error() string
  • func (e *ErrUnusableState) Unwrap() error
• type File
  • func New(state *states.State, lineage string, serial uint64) *File
  • func Read(r io.Reader) (*File, error)
  • func (f *File) DeepCopy() *File

Variables

var ErrNoState = errors.New("no state")

ErrNoState is returned by ReadState when the state file is empty.

Functions

func StatesMarshalEqual

func StatesMarshalEqual(a, b *states.State) bool

StatesMarshalEqual returns true if and only if the two given states have an identical (byte-for-byte) statefile representation.

This function compares only the portions of the state that are persisted in state files, so for example it will not return false if the only differences between the two states are local values or descendent module outputs.

func Write

func Write(s *File, w io.Writer) error

Write writes the given state to the given writer in the current state serialization format.

func WriteForTest

func WriteForTest(s *File, w io.Writer) error

WriteForTest writes the given state to the given writer in the current state serialization format without recording the current terraform version. This is intended for use in tests that need to override the current terraform version.

Types

type ErrUnusableState

type ErrUnusableState struct {
	// contains filtered or unexported fields
}

ErrUnusableState is an error wrapper to indicate that we *think* the input represents state data, but can't use it for some reason (as explained in the error text). Callers can check against this type with errors.As() if they need to distinguish between corrupt state and more fundamental problems like an empty file.

func (*ErrUnusableState) Error

func (e *ErrUnusableState) Error() string

func (*ErrUnusableState) Unwrap

func (e *ErrUnusableState) Unwrap() error

type File

type File struct {
	// TerraformVersion is the version of Terraform that wrote this state file.
	TerraformVersion *version.Version

	// Serial is incremented on any operation that modifies
	// the State file. It is used to detect potentially conflicting
	// updates.
	Serial uint64

	// Lineage is set when a new, blank state file is created and then
	// never updated. This allows us to determine whether the serials
	// of two states can be meaningfully compared.
	// Apart from the guarantee that collisions between two lineages
	// are very unlikely, this value is opaque and external callers
	// should only compare lineage strings byte-for-byte for equality.
	Lineage string

	// State is the actual state represented by this file.
	State *states.State
}

File is the in-memory representation of a state file. It includes the state itself along with various metadata used to track changing state files for the same configuration over time.

func New

func New(state *states.State, lineage string, serial uint64) *File

func Read

func Read(r io.Reader) (*File, error)

Read reads a state from the given reader.

Legacy state format versions 1 through 3 are supported, but the result will contain object attributes in the deprecated "flatmap" format and so must be upgraded by the caller before use.

If the state file is empty, the special error value ErrNoState is returned. Otherwise, the returned error might be a wrapper around tfdiags.Diagnostics potentially describing multiple errors.

func (*File) DeepCopy

func (f *File) DeepCopy() *File

DeepCopy is a convenience method to create a new File object whose state is a deep copy of the receiver's, as implemented by states.State.DeepCopy.