clistate

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 24, 2026 License: MPL-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package state exposes common helpers for working with state from the CLI.

This is a separate package so that backends can use this for consistent messaging without creating a circular reference to the command package.

Index

Constants

View Source
const (
	LockThreshold    = 400 * time.Millisecond
	LockErrorMessage = `` /* 272-byte string literal not displayed */

	UnlockErrorMessage = `` /* 719-byte string literal not displayed */

)
View Source
const StateVersion = 3

StateVersion is the current supported version for CLI state files.

Variables

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

Functions

func WriteState

func WriteState(st *CLIState, dst io.Writer) error

WriteState writes CLIState in JSON form.

Types

type BackendState

type BackendState struct {
	Type      string          `json:"type"`   // Backend type
	ConfigRaw json.RawMessage `json:"config"` // Backend raw config
	Hash      uint64          `json:"hash"`   // Hash of configuration from config files
}

BackendState stores the configuration to connect to a backend.

func (*BackendState) Config

func (b *BackendState) Config(schema *configschema.Block) (cty.Value, error)

func (*BackendState) Empty

func (b *BackendState) Empty() bool

func (*BackendState) ForPlan

func (b *BackendState) ForPlan(schema *configschema.Block, workspaceName string) (*plans.Backend, error)

func (*BackendState) SetConfig

func (b *BackendState) SetConfig(val cty.Value, schema *configschema.Block) error

type CLIState

type CLIState struct {
	// Version is the state file protocol version.
	Version int `json:"version"`

	// Backend tracks the configuration for the backend in use with
	// this state. This is used to track any changes in the backend
	// configuration.
	Backend *BackendState `json:"backend,omitempty"`
}

func NewState

func NewState() *CLIState

func ReadState

func ReadState(src io.Reader, dataDirOverridden bool) (*CLIState, error)

ReadState reads the CLI state file format written by WriteState. dataDirOverridden should be true when the data directory was explicitly overridden (e.g. via TF_DATA_DIR).

func (*CLIState) DeepCopy

func (s *CLIState) DeepCopy() *CLIState

DeepCopy performs a deep copy of the CLI state structure and returns a new structure.

type LocalState

type LocalState struct {
	// Path is the path to read the state from. PathOut is the path to
	// write the state to. If PathOut is not specified, Path will be used.
	// If PathOut already exists, it will be overwritten.
	Path    string
	PathOut string

	// DataDirOverridden is true when the data directory was explicitly
	// overridden (e.g. via TF_DATA_DIR).
	DataDirOverridden bool
	// contains filtered or unexported fields
}

LocalState manages a state storage that is local to the filesystem.

func (*LocalState) Lock

func (s *LocalState) Lock(_ context.Context, info *statemgr.LockInfo) (string, error)

Lock implements a local filesystem state.Locker.

func (*LocalState) PersistState

func (s *LocalState) PersistState(_ context.Context) error

PersistState for LocalState is a no-op since WriteState always persists.

StatePersister impl.

func (*LocalState) RefreshState

func (s *LocalState) RefreshState(_ context.Context) error

StateRefresher impl.

func (*LocalState) SetState

func (s *LocalState) SetState(state *CLIState)

SetState will force a specific state in-memory for this local state.

func (*LocalState) State

func (s *LocalState) State() *CLIState

StateReader impl.

func (*LocalState) Unlock

func (s *LocalState) Unlock(_ context.Context, id string) error

func (*LocalState) WriteState

func (s *LocalState) WriteState(state *CLIState) error

WriteState for LocalState always persists the state as well. TODO: this should use a more robust method of writing state, by first writing to a temp file on the same filesystem, and renaming the file over the original.

StateWriter impl.

type Locker

type Locker interface {
	// Returns a shallow copy of the locker with its context changed to ctx.
	WithContext(ctx context.Context) Locker

	// Lock the provided state manager, storing the reason string in the LockInfo.
	Lock(s statemgr.Locker, reason string) tfdiags.Diagnostics

	// Unlock the previously locked state.
	Unlock() tfdiags.Diagnostics

	// Timeout returns the configured timeout duration
	Timeout() time.Duration
}

Locker allows for more convenient usage of the lower-level statemgr.Locker implementations. The statemgr.Locker API requires passing in a statemgr.LockInfo struct. Locker implementations are expected to create the required LockInfo struct when Lock is called, populate the Operation field with the "reason" string provided, and pass that on to the underlying statemgr.Locker. Locker implementations are also expected to store any state required to call Unlock, which is at a minimum the LockID string returned by the statemgr.Locker.

func NewLocker

func NewLocker(timeout time.Duration, view views.StateLocker) Locker

Create a new Locker. This Locker uses state.LockWithContext to retry the lock until the provided timeout is reached, or the context is canceled. Lock progress will be reported to the user through the provided UI.

func NewNoopLocker

func NewNoopLocker() Locker

NewNoopLocker returns a valid Locker that does nothing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL