state

package
v0.12.0-a.3 Latest Latest
Warning

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

 Go to latest Published: Sep 6, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package state defines the contract a state backend implements.

A backend stores snapshots, advances a current pointer, and arbitrates a per-stack lock. A backend implementation satisfies the Backend interface and joins the fixed set in pkg/backends, where an operator selects it by name. Encryption is a separate concern; see the sibling pkg/sdk/encrypt package.

Index

Constants

View Source 
const CurrentFormatVersion = 2
View Source 
const EnvelopeVersion = 1

EnvelopeVersion is the on-disk version of the envelope that wraps a plan or a state snapshot. Bump it when the envelope itself changes; the inner body keeps its own format version, which moves independently.

Variables

View Source 
var ErrNoCurrent = errors.New("no current snapshot")

ErrNoCurrent is returned by Backend.CurrentRev when no snapshot has been written for the stack yet.

Functions

func EncodeSnapshotV2 

func EncodeSnapshotV2(snapshot SnapshotV2) ([]byte, error)

func Open added in v0.5.0 

func Open(
	b []byte,
	expectedPayloadType PayloadType,
	resolveEnc func(*Ref) (encrypt.Encrypter, error),
) ([]byte, error)

Open reads an envelope and returns the decrypted inner body. resolveEnc builds or selects an encrypter from the envelope's ref; it receives nil when the envelope has no encrypter ref.

func Seal added in v0.5.0 

func Seal(body []byte, payloadType PayloadType, enc encrypt.Encrypter) ([]byte, error)

Seal encrypts body with enc and wraps the result in an Envelope ready for atomic write. The envelope records enc's description, taken after encrypting so it includes facts resolved on first use, like the kms encrypter's key ARN.

func SealSnapshotV2 

func SealSnapshotV2(snapshot SnapshotV2, enc encrypt.Encrypter) ([]byte, error)

SealSnapshotV2 encodes and seals a strict version-2 snapshot.

func SortRevisions added in v0.11.0 

func SortRevisions(revisions []string) []string

Types

type ActionStatePayload 

type ActionStatePayload struct {
	Binding              CanonicalBinding    `json:"binding"`
	Inputs               encodedvalue.Value  `json:"inputs"`
	Outputs              encodedvalue.Value  `json:"outputs"`
	Configuration        ConfigurationRecord `json:"configuration"`
	TriggerHash          string              `json:"trigger-hash"`
	DependsOn            []string            `json:"depends-on"`
	SensitiveInputPaths  []string            `json:"sensitive-input-paths"`
	SensitiveOutputPaths []string            `json:"sensitive-output-paths"`
}

func (ActionStatePayload) Validate 

func (p ActionStatePayload) Validate() error

type Backend 

type Backend interface {
	Stack() string
	CurrentRev() (string, error)
	SetCurrent(rev string) error
	// List returns snapshot revisions from oldest to newest.
	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.Registration
	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 CanonicalBinding 

type CanonicalBinding struct {
	LibraryPath string `json:"library-path"`
	Export      string `json:"export"`
}

func (CanonicalBinding) Validate 

func (b CanonicalBinding) Validate() error

type CompositeStatePayload 

type CompositeStatePayload struct {
	Category             string             `json:"category"`
	Binding              CanonicalBinding   `json:"binding"`
	Inputs               encodedvalue.Value `json:"inputs"`
	Outputs              encodedvalue.Value `json:"outputs"`
	DependsOn            []string           `json:"depends-on"`
	SensitiveInputPaths  []string           `json:"sensitive-input-paths"`
	SensitiveOutputPaths []string           `json:"sensitive-output-paths"`
}

func (CompositeStatePayload) Validate 

func (p CompositeStatePayload) Validate() error

type ConfigurationRecord 

type ConfigurationRecord = internalconfig.Record

type DataSourceStatePayload 

type DataSourceStatePayload struct {
	Binding              CanonicalBinding    `json:"binding"`
	Inputs               encodedvalue.Value  `json:"inputs"`
	Outputs              encodedvalue.Value  `json:"outputs"`
	Configuration        ConfigurationRecord `json:"configuration"`
	DependsOn            []string            `json:"depends-on"`
	SensitiveInputPaths  []string            `json:"sensitive-input-paths"`
	SensitiveOutputPaths []string            `json:"sensitive-output-paths"`
}

func (DataSourceStatePayload) Validate 

func (p DataSourceStatePayload) Validate() error

type Envelope added in v0.5.0 

type Envelope struct {
	EnvelopeVersion int         `json:"envelope-version"`
	PayloadType     PayloadType `json:"payload-type,omitempty"`
	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; its Encrypter ref records which key source sealed the inner body and the non-secret configuration (env-var name, KMS key ARN, region) needed to decrypt it, so a state file found long after the config that wrote it still says how to get back to plaintext. Key material is never on disk; the operator must have it available through the encrypter's own channel.

The envelope is not authenticated, so a reader with its own configuration must not let the file choose the key: state backends decrypt with the encrypter resolved from the stack file and treat the recorded ref as information for operators and error messages.

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 IdentityRecord 

type IdentityRecord struct {
	DefinitionDigest string  `json:"definition-digest"`
	Version          int     `json:"version"`
	StableID         *string `json:"stable-id,omitempty"`
}

IdentityRecord describes the identity definition and remote incarnation validated for one resource target.

func (IdentityRecord) Validate 

func (r IdentityRecord) Validate() error

Validate checks the required identity metadata and optional stable ID.

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 PayloadType added in v0.8.0 

type PayloadType string

PayloadType labels the plaintext body sealed inside an Envelope. 

const (
	// PayloadTypePlan marks a sealed plan file body.
	PayloadTypePlan PayloadType = "plan"
	// PayloadTypeState marks a sealed state snapshot body.
	PayloadTypeState PayloadType = "state"
)

type Ref added in v0.5.0 

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

Ref names an entry in the fixed backend or encrypter registry. Name is the bare state backend or encryption key-source from the stack file; Body is the configuration the resolver decodes against that entry's schema.

A plan file records a Backend ref so apply can reconstruct the same backend without re-reading the stack file, and every envelope records an Encrypter ref naming the key source that sealed it.

type ResourceStatePayload 

type ResourceStatePayload struct {
	Target ResourceTarget `json:"target"`
}

func (ResourceStatePayload) Validate 

func (p ResourceStatePayload) Validate() error

type ResourceTarget 

type ResourceTarget struct {
	Binding              CanonicalBinding    `json:"binding"`
	SchemaVersion        int                 `json:"schema-version"`
	Inputs               encodedvalue.Value  `json:"inputs"`
	Outputs              encodedvalue.Value  `json:"outputs"`
	Configuration        ConfigurationRecord `json:"configuration"`
	Identity             IdentityRecord      `json:"identity"`
	DependsOn            []string            `json:"depends-on"`
	SensitiveInputPaths  []string            `json:"sensitive-input-paths"`
	SensitiveOutputPaths []string            `json:"sensitive-output-paths"`
}

func (ResourceTarget) Validate 

func (t ResourceTarget) Validate() error

type SensitiveValueRecord 

type SensitiveValueRecord = internalconfig.SensitiveValueRecord

type SnapshotBackendV2 

type SnapshotBackendV2 interface {
	GetV2(rev string) (*SnapshotV2, error)
	WriteV2(snap *SnapshotV2) (string, error)
}

SnapshotBackendV2 reads and writes strict version-2 snapshots by revision. CurrentRev and SetCurrent remain on Backend so snapshot persistence can keep the existing write-before-current-pointer contract.

type SnapshotV2 

type SnapshotV2 struct {
	FormatVersion  int                `json:"format-version"`
	Factory        FactoryInfo        `json:"factory"`
	Stack          string             `json:"stack"`
	GeneratedAt    time.Time          `json:"generated-at"`
	Entries        []StateEntryV2     `json:"entries"`
	Outputs        encodedvalue.Value `json:"outputs"`
	SensitivePaths []string           `json:"sensitive-paths"`
}

func DecodeSnapshotV2 

func DecodeSnapshotV2(data []byte) (SnapshotV2, error)

func NewSnapshotV2 

func NewSnapshotV2(factory FactoryInfo, stack string) (*SnapshotV2, error)

func OpenSnapshotV2 

func OpenSnapshotV2(data []byte, enc encrypt.Encrypter) (SnapshotV2, error)

OpenSnapshotV2 opens and decodes a strict version-2 snapshot using the backend-configured encrypter.

func (*SnapshotV2) Clone 

func (s *SnapshotV2) Clone() (*SnapshotV2, error)

func (*SnapshotV2) Find 

func (s *SnapshotV2) Find(address string) *StateEntryV2

func (*SnapshotV2) RemoveEntry 

func (s *SnapshotV2) RemoveEntry(address string) error

func (*SnapshotV2) SetEntry 

func (s *SnapshotV2) SetEntry(entry StateEntryV2) error

func (*SnapshotV2) SetOutputs 

func (s *SnapshotV2) SetOutputs(
	outputs encodedvalue.Value,
	sensitivePaths []string,
) error

func (SnapshotV2) Validate 

func (s SnapshotV2) Validate() error

type StateEntryKind 

type StateEntryKind string
const (
	StateResource   StateEntryKind = "resource"
	StateAction     StateEntryKind = "action"
	StateDataSource StateEntryKind = "data-source"
	StateComposite  StateEntryKind = "composite"
)

type StateEntryV2 

type StateEntryV2 struct {
	Address string         `json:"address"`
	Kind    StateEntryKind `json:"kind"`
	Payload StatePayload   `json:"payload"`
}

func (StateEntryV2) Validate 

func (e StateEntryV2) Validate() error

type StatePayload 

type StatePayload struct {
	Kind       StateEntryKind          `json:"kind"`
	Resource   *ResourceStatePayload   `json:"resource,omitempty"`
	Action     *ActionStatePayload     `json:"action,omitempty"`
	DataSource *DataSourceStatePayload `json:"data-source,omitempty"`
	Composite  *CompositeStatePayload  `json:"composite,omitempty"`
}

func (StatePayload) Validate 

func (p StatePayload) Validate(kind StateEntryKind) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.