state

type Backend ¶

type Backend interface {
	Stack() string
	Current() (*Snapshot, error)
	CurrentRev() (string, error)
	Get(rev string) (*Snapshot, error)
	Write(snap *Snapshot) (string, error)
	SetCurrent(rev string) error
	List() ([]string, error)
	Delete(rev string) error
	Lock(ctx context.Context) (Lock, error)
	ForceUnlock() error
}

Backend is the contract a state backend satisfies. The runtime reads and writes snapshots through it; concrete implementations decide where the bytes live. Apply and refresh acquire the stack's lock through Lock and release it through the returned Lock value. Plan is read-only and never locks. ForceUnlock is the escape hatch for a leaked lock.

type BackendType ¶

type BackendType struct {
	Name          string
	Description   string
	Configuration *cfg.ConfigurationType
	New           func(config any, factory, stack string, enc encrypt.Encrypter) (Backend, error)
}

BackendType registers a state backend a provider library ships. Configuration describes the schema for the `state:` block fields the operator writes (e.g., path for the local backend, bucket and region for an S3 backend). New is the factory the runtime invokes once it has decoded the configuration against that schema; it returns a ready-to-use Backend.

type Entry ¶

type Entry struct {
	Address string    `json:"address"`
	Type    EntryType `json:"type"`

	Kind             string   `json:"kind,omitempty"`
	SchemaVersion    int      `json:"schema-version,omitempty"`
	SensitiveInputs  []string `json:"sensitive-inputs,omitempty"`
	SensitiveOutputs []string `json:"sensitive-outputs,omitempty"`

	Library     string `json:"library,omitempty"`
	LibraryType string `json:"library-type,omitempty"`

	// Configuration names the library configuration the resource was
	// created against, as "<alias>.<configuration>". It is recorded only
	// when that differs from the import's own default, since destroy and
	// refresh need it to find the right credentials once the resource is
	// no longer described in source.
	Configuration string `json:"configuration,omitempty"`

	TriggerHash string `json:"trigger-hash,omitempty"`

	Inputs    map[string]any `json:"inputs,omitempty"`
	Outputs   map[string]any `json:"outputs,omitempty"`
	DependsOn []string       `json:"depends-on,omitempty"`
}

Entry is one record in a snapshot. Type discriminates the fields used: leaf entries hold a primitive resource's Kind, SchemaVersion, Inputs, and Outputs; library-call entries hold a composite type's Library, LibraryType, and call-site Inputs/Outputs.

SensitiveInputs and SensitiveOutputs name the kebab-case fields whose values came from a sensitive source. Renderers mask the matching entries when printing.

type EntryType ¶

type EntryType string

EntryType discriminates the three records a snapshot can hold.

const (
	EntryLeaf        EntryType = "leaf"
	EntryLibraryCall EntryType = "library-call"
	EntryAction      EntryType = "action"
)

type Envelope ¶ added in v0.5.0

type Envelope struct {
	EnvelopeVersion int    `json:"envelope-version"`
	Encrypter       *Ref   `json:"encrypter,omitempty"`
	Ciphertext      []byte `json:"ciphertext"`
}

Envelope is the on-disk container for a plan or a state snapshot. The envelope is plaintext; it names which encrypter sealed the inner body so a reader can build the matching encrypter before opening it. The Encrypter ref holds only non-secret configuration (env-var name, KMS key id, region). Key material is never on disk; the operator must have it available through the encrypter's own channel.

type FactoryInfo ¶

type FactoryInfo struct {
	Name            string `json:"name"`
	Version         string `json:"version"`
	ContentRevision string `json:"content-revision"`
}

FactoryInfo identifies the stack a snapshot belongs to. ContentRevision is the content-addressable hash the binary was compiled with.

type Lock ¶

type Lock interface {
	Unlock() error
}

Lock is a held exclusion on one stack. Callers must invoke Unlock; a leaked lock blocks future apply and refresh runs until an operator calls ForceUnlock.

type Ref ¶ added in v0.5.0

type Ref struct {
	Alias string         `json:"alias,omitempty"`
	Name  string         `json:"name"`
	Body  map[string]any `json:"body,omitempty"`
}

Ref names one entry in a library's StateBackends or Encrypters map. Alias is empty for the bare names registered under the built-in core library (`local`, `env-key`); otherwise it is the import alias from `imports:`. Body holds the operator-provided configuration the resolver decodes against the backend or encrypter type's schema.

A plan file records a Backend ref so apply can reconstruct the same backend without re-reading config.ub, and an Encrypter ref rides in the envelope so a reader can build the encrypter before opening the body.

type Snapshot ¶

type Snapshot struct {
	FormatVersion int            `json:"format-version"`
	Factory       FactoryInfo    `json:"factory"`
	Stack         string         `json:"stack"`
	GeneratedAt   time.Time      `json:"generated-at"`
	Entries       []*Entry       `json:"entries"`
	Outputs       map[string]any `json:"outputs,omitempty"`
}

Snapshot is the in-memory record of one state file. The runtime reads the current snapshot at the start of plan or apply, and writes a fresh one after each successful resource action.

func DecodeSnapshot(b []byte) (*Snapshot, error)

func NewSnapshot(factory FactoryInfo, stack string) *Snapshot

func (s *Snapshot) Find(address string) *Entry

func (s *Snapshot) Validate() error