staterecord

type BucketContractAPI ¶ added in v0.18.0

type BucketContractAPI interface {
	GetBucketVersioning(ctx context.Context, in *s3.GetBucketVersioningInput, optFns ...func(*s3.Options)) (*s3.GetBucketVersioningOutput, error)
	GetBucketLifecycleConfiguration(ctx context.Context, in *s3.GetBucketLifecycleConfigurationInput, optFns ...func(*s3.Options)) (*s3.GetBucketLifecycleConfigurationOutput, error)
	GetPublicAccessBlock(ctx context.Context, in *s3.GetPublicAccessBlockInput, optFns ...func(*s3.Options)) (*s3.GetPublicAccessBlockOutput, error)
}

BucketContractAPI is the three reads the contract needs, and the permissions they cost: s3:GetBucketVersioning, s3:GetLifecycleConfiguration and s3:GetBucketPublicAccessBlock. *s3.Client satisfies it.

type BucketContractChecker ¶ added in v0.18.0

type BucketContractChecker interface {
	CheckBucketContract(ctx context.Context, namespaces []string) ([]BucketFinding, error)
}

BucketContractChecker is implemented by a store that lives in a bucket. The local store does not implement it: a directory has no such settings, and a store with nothing to assert is not a store that failed.

func AsBucketContractChecker(s Store) (BucketContractChecker, bool)

type BucketFinding ¶ added in v0.18.0

type BucketFinding struct {
	Setting BucketSetting

	// OK is true when the bucket satisfies the assertion.
	OK bool

	// Unreadable is true when the setting could not be read at all - the
	// role lacks the Get* permission, typically. It is never true together
	// with OK. From the caller's side it is the same refusal a wrong setting
	// gets, because a bucket nobody could check is not a bucket that passed.
	Unreadable bool

	// Found says what the bucket actually has, in one clause, for the
	// refusal to quote: "versioning is Suspended", "no lifecycle
	// configuration", "s3:GetBucketVersioning was denied".
	Found string
}

BucketFinding is what one setting turned out to be.

func CheckBucketContract(ctx context.Context, api BucketContractAPI, bucket string, namespaces []string) ([]BucketFinding, error)

func SplitWaived(findings []BucketFinding, waived []string) (refused, waivedFailing []BucketFinding)

type BucketSetting ¶ added in v0.18.0

type BucketSetting string

BucketSetting names one asserted setting. The values are the names an operator writes in configuration (#1340's allow_insecure), so they are part of the configuration language and do not change casually.

const (
	BucketVersioning        BucketSetting = "versioning"
	BucketLifecycle         BucketSetting = "lifecycle"
	BucketPublicAccessBlock BucketSetting = "public_access_block"
)

type BulkReader ¶ added in v0.5.0

type BulkReader interface {
	GetAll(ctx context.Context, keyPrefix string) (map[string]Record, error)
}

BulkReader is the optional half of Store that loads a whole namespace in one call. It exists because a plan needs the entire estate's records and stock OpenTofu gets its whole equivalent — the state file — in one read. Without it, a converged plan's cheapest possible shape is still one call per instance for information no per-instance decision needed separately.

GetAll returns every record whose key begins with keyPrefix, keyed by the same key Store.Get and Store.List use. An empty keyPrefix means every key. The returned map is the CALLER's; implementations must not retain or reuse it.

The result is complete for that prefix: a key absent from the map holds no record. That is what makes it usable as a snapshot rather than a warm cache — a reader can answer "there is nothing recorded for this address" from it without going back to the store.

It is optional rather than part of Store because it is an optimization and not a semantic: a backend with no way to enumerate values simply does not implement it, and every caller keeps working through Store.Get.

type CountingStore ¶ added in v0.5.0

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

CountingStore wraps a Store and counts every operation that reaches it, which is the record-store half of what internal/live/flocitest's CountingProxy counts for provider traffic. The proxy stands in front of the AWS endpoint and is therefore blind to these: a record read goes to a local directory or an S3 object, neither of which the provider's endpoint ever sees. Until this existed, no instrument in this repository counted them at all, so "a plan costs N calls" was a partial number by construction.

A "trip" is one call to the wrapped store, because that is the unit that costs something: against LocalStore a stat plus a read, against S3Store a network round trip. Stock OpenTofu makes zero of them — it reads its whole state once, from one file.

Each trip records more than a method name, because a bare per-method total cannot answer either question a reduction needs answered:

• Site is the first frame outside this package and outside projection.(*RecordStore) — the code that actually wanted the record. This is the per-site breakdown; without it, "158 Gets" names no line to fix.
• Via is the outermost projection.(*RecordStore) method the call came through (GetIdentity, GetResidue, getProvisioned, ...), so several sites reading the same underlying envelope through different accessors stay distinguishable.
• Key is the store key, so [CountingStore.RepeatTrips] can report how many trips re-read a key some earlier trip already read. That number is the size of the prize a cache can win, measured rather than assumed.

It is safe for concurrent use; the sweep and the projection both run goroutines.

func NewCountingStore(inner Store, log io.Writer) *CountingStore

func (c *CountingStore) Counts() TripCounts

func (c *CountingStore) Delete(ctx context.Context, key string, expectedVersion string) error

func (c *CountingStore) Get(ctx context.Context, key string) ([]byte, string, bool, error)

func (c *CountingStore) GetAll(ctx context.Context, keyPrefix string) (map[string]Record, error)

func (c *CountingStore) List(ctx context.Context, keyPrefix string) ([]string, error)

func (c *CountingStore) PutIfAbsent(ctx context.Context, key string, payload []byte) (string, error)

func (c *CountingStore) PutIfVersion(ctx context.Context, key string, payload []byte, expectedVersion string) (string, error)

func (c *CountingStore) Reset()

func (c *CountingStore) Total() int

func (c *CountingStore) Trips() []Trip

func (c *CountingStore) Unwrap() Store

type KMSDeniedError ¶ added in v0.18.0

type KMSDeniedError struct {
	// Action is the KMS action refused, for example "kms:Decrypt".
	Action string
	// KeyARN is the key that refused it. Empty if AWS did not say.
	KeyARN string
	// Principal is who was refused, as AWS names them. Empty if AWS did not say.
	Principal string
	// Where is which policy AWS blamed: KMSDeniedByKeyPolicy,
	// KMSDeniedByIdentityPolicy, KMSDeniedExplicitly, or "" when the message
	// did not say.
	Where string
	// Err is the S3 error as it arrived.
	Err error
}

KMSDeniedError is an S3 request refused because of the bucket's KMS key, and not because of anything about S3.

A bucket whose default encryption is a customer managed key makes every GetObject a kms:Decrypt and every PutObject a kms:GenerateDataKey, made by S3 with the caller's identity. When KMS refuses, S3 reports it as a plain 403 AccessDenied on the S3 operation, and the only sign that the cause is the key is inside the message text. An operator who reads "AccessDenied ... PutObject" goes to the bucket policy and the role's S3 statements, which are correct, and the mistake is almost always somewhere they did not look: a key policy that does not name the role. A customer managed key is usable only by the principals its key policy allows, and an IAM policy alone never grants it unless the key policy delegates to IAM.

The wording below was written against what real AWS says (GitHub issue #1345, us-east-2, 2026-09-18), which is, on one line:

User: arn:aws:sts::<acct>:assumed-role/<role>/<session> is not authorized
to perform: kms:GenerateDataKey on resource: arn:aws:kms:<region>:<acct>:key/<id>
because no resource-based policy allows the kms:GenerateDataKey action

func (e *KMSDeniedError) Error() string

func (e *KMSDeniedError) Headline() string

func (e *KMSDeniedError) Remedy() string

func (e *KMSDeniedError) Unwrap() error

type LocalStore ¶

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

LocalStore is a Store backed by a directory of files: one file per key, nested directories mirroring any "/" the key contains. It is the zero-configuration default — solo development, tests, air-gapped runs — mirroring plain local state's own "just works, no backend to configure" shape.

Version ¶

A record's version is its content hash ("sha256:<hex>"), not a timestamp or a counter: two writes of byte-identical payloads carry the same version, and the version never depends on the clock or on how many times the key has been written.

Atomicity and its limit: single-operator only ¶

LocalStore.PutIfAbsent is a single O_CREATE|O_EXCL open — atomic on its own, no locking needed, exactly like a real filesystem's create primitive already guarantees. LocalStore.PutIfVersion and LocalStore.Delete are a read, a compare, and a write (or removal); nothing in POSIX makes that sequence atomic by itself, so each one holds a sidecar "<file>.lock" file — itself an O_CREATE|O_EXCL create — for the duration, and the write half lands via a temp file plus os.Rename so a reader never observes a half-written file.

That gives real compare-and-swap for every writer on one machine: two goroutines in one process, or two separate `tofu` invocations racing on the same directory, serialize through the lockfile and the loser gets a *VersionConflictError rather than a silently clobbered write. It gives nothing across machines — there is no network protocol here, only local filesystem primitives — which is the store's fundamental limit rather than an oversight: LocalStore is for a single operator (or a single machine's worth of concurrent processes), never for a team sharing state across laptops. Reaching for S3Store is what "more than one operator" means in this package.

What this store does not manage ¶

The directory's location, its presence or absence in version control, and its backup story are the caller's to decide — this store only reads and writes files under the directory it is given. That is an acceptable hands-off position specifically because a micro-state record's blast radius is small (an effect re-runs, a random id regenerates) in a way a full Terraform state file's loss never was.

func NewLocalStore(dir string) (*LocalStore, error)

func (s *LocalStore) Delete(ctx context.Context, key string, expectedVersion string) error

func (s *LocalStore) Get(_ context.Context, key string) ([]byte, string, bool, error)

func (s *LocalStore) GetAll(_ context.Context, keyPrefix string) (map[string]Record, error)

func (s *LocalStore) List(_ context.Context, keyPrefix string) ([]string, error)

func (s *LocalStore) PutIfAbsent(_ context.Context, key string, payload []byte) (string, error)

func (s *LocalStore) PutIfVersion(ctx context.Context, key string, payload []byte, expectedVersion string) (string, error)

type Record ¶ added in v0.5.0

type Record struct {
	Payload []byte
	Version string
}

Record is one stored record's content and version, as BulkReader.GetAll returns it — the same pair Store.Get returns for one key, for a caller that asked for many.

type RunCache ¶ added in v0.5.0

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

RunCache is the estate's records loaded the way stock OpenTofu loads its state file: once, in bulk, at the moment something first asks for any of it, held in memory for the rest of the read phase, and never written back through.

What it replaces ¶

A migrated plan asks the store about the same instance three to eight times. Every accessor on projection's RecordStore - identity, residue, the provisioner bit, the deposed set, the envelope kind - decodes the same physical key, and each went to the store for itself. Measured at scale 1 over 78 instances: 377 trips over 80 distinct keys. Caching the repeats takes that to 80, one per instance. Loading the namespace in bulk takes it to 1, which is what stock pays, and is the only figure that makes the two state models comparable at all.

The bulk load is lazy - it happens on the first read under the namespace, not at construction - because that is exactly when stock reads its state file, and because a command that touches no record should pay for none. A store that does not implement BulkReader silently keeps the per-key behaviour: still one trip per key instead of one per accessor.

Why it cannot serve a stale value ¶

One rule, and it is not a balance of risks: **the cache is switched off permanently, process-wide, by the first write through any RunCache.** Nothing it serves was ever read after something was written. A plan writes nothing, so a plan is served entirely from the snapshot; the instant a write-back, a migration or a seeder writes anything, every later read in that process goes to the store, for good.

That is deliberately blunter than invalidating the key that was written. Invalidation has to be right about which reads a write can affect, and the three reads it must never be wrong about - projection's mergeEnvelope read-modify-write, its currentVersion, and the seeders' read-before-write halves - are the ones where being wrong means a lost update rather than a slow run. A switch that is simply off after the first write cannot be wrong about any of them. Those three call sites additionally bypass this cache explicitly, through RunCache.Uncached, so they are correct even before the first write has happened.

Nothing conditional is ever decided here either: PutIfVersion, PutIfAbsent and Delete always go to the wrapped store, so the compare-and-swap that guards against a writer OUTSIDE this process is performed by the store on the store's own current version, exactly as before.

Lifetime ¶

The process, and never longer. A record is live state; whether one has gone stale between runs is the charter's business, and a cache must never be what answers it. There is no expiry, no file, no shared daemon.

func (c *RunCache) Delete(ctx context.Context, key string, expectedVersion string) error

func (c *RunCache) Get(ctx context.Context, key string) ([]byte, string, bool, error)

func (c *RunCache) GetAll(ctx context.Context, keyPrefix string) (map[string]Record, error)

func (c *RunCache) List(ctx context.Context, keyPrefix string) ([]string, error)

func (c *RunCache) PutIfAbsent(ctx context.Context, key string, payload []byte) (string, error)

func (c *RunCache) PutIfVersion(ctx context.Context, key string, payload []byte, expectedVersion string) (string, error)

func (c *RunCache) Uncached() Store

func (c *RunCache) Unwrap() Store

type S3Config ¶

type S3Config struct {
	// Client is the S3 client every call goes through. The caller builds
	// and authenticates it — region, credentials, any endpoint override
	// for a local emulator — this package has no opinion on any of that.
	Client *s3.Client

	// Bucket is the S3 bucket every key lives in.
	Bucket string

	// KeyPrefix is joined ahead of every key this store is asked for, so
	// one bucket can host more than one caller's keyspace without either
	// seeing the other's keys in [S3Store.List]. Empty means keys map
	// directly to object keys. This package does not interpret
	// KeyPrefix's structure at all — it is an opaque string, the same as
	// every key passed to the [Store] interface.
	KeyPrefix string

	// GetAllParallelism bounds how many GetObject calls [S3Store.GetAll] has
	// in flight at once. Zero or negative takes
	// [DefaultS3GetAllParallelism]; 1 is a sequential read.
	GetAllParallelism int

	// BaseTags go on every object this store writes. The record store sets
	// tofu-estate here, because every object in an estate's namespaces -
	// its records, its sentinel, its hint, its outputs - is the estate's,
	// whether or not it records a resource. See [WithObjectTags] for the
	// per-write half. GitHub issue #1337.
	BaseTags map[string]string
}

S3Config configures an S3Store.

type S3Store ¶

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

S3Store is a Store backed by S3 object versions via conditional writes: If-Match and If-None-Match, the ETag-based compare-and-swap primitive S3 added for general-purpose buckets. This is the store's strongest offering — a real, server-enforced CAS, not a read-compare-write approximation — and a version here is exactly an object's ETag, unmodified.

What is genuinely atomic ¶

Every conditional operation is a single S3 request carrying the condition; there is no read-compare-write window for this store to document a caveat about:

• S3Store.PutIfAbsent and a "" S3Store.PutIfVersion call send If-None-Match: * — S3 rejects the write with HTTP 412 if any object already exists at the key.
• A non-"" S3Store.PutIfVersion call sends If-Match: <version> — S3 rejects the write with HTTP 412 if the object's current ETag does not match.
• S3Store.Delete sends If-Match: <version> on DeleteObject, which S3 honors for general-purpose buckets, not only the directory-bucket case the S3 API docs otherwise reserve conditional deletes for.

On a 412, this store issues one extra read (Get) purely to populate VersionConflictError.ActualVersion with an accurate answer; that read is not part of the conditional guarantee itself; the conditional write already failed atomically before it.

What this store does not manage ¶

Bucket creation, lifecycle policy, and encryption configuration are the caller's concern — S3Store only issues GetObject/PutObject/DeleteObject/ ListObjectsV2 against a bucket and (optional) key prefix it is given. It does not build or authenticate the s3.Client itself; the caller supplies one already configured for the target account, region and endpoint, which is what keeps this store's own surface free of anything AWS-credential-shaped.

func NewS3Store(cfg S3Config) (*S3Store, error)

func (s *S3Store) CheckBucketContract(ctx context.Context, namespaces []string) ([]BucketFinding, error)

func (s *S3Store) Delete(ctx context.Context, key string, expectedVersion string) error

func (s *S3Store) Get(ctx context.Context, key string) ([]byte, string, bool, error)

func (s *S3Store) GetAll(ctx context.Context, keyPrefix string) (map[string]Record, error)

func (s *S3Store) List(ctx context.Context, keyPrefix string) ([]string, error)

func (s *S3Store) ObjectKey(key string) string

func (s *S3Store) PutIfAbsent(ctx context.Context, key string, payload []byte) (string, error)

func (s *S3Store) PutIfVersion(ctx context.Context, key string, payload []byte, expectedVersion string) (string, error)

type Store ¶

type Store interface {
	// Get reads the current record at key. exists is false when no record
	// is there; payload and version are then the zero value and err is nil
	// — a missing key is not itself an error. version is "" if and only if
	// exists is false: no implementation ever assigns "" as a live record's
	// version, so a caller may treat it as a stable "absent" sentinel.
	Get(ctx context.Context, key string) (payload []byte, version string, exists bool, err error)

	// PutIfVersion writes payload to key, but only if the record's current
	// version equals expectedVersion. expectedVersion == "" asserts that no
	// record exists yet at key (the same assertion PutIfAbsent makes,
	// reachable here for callers that hold a uniform "expected version"
	// value rather than branching on whether they have seen the key
	// before). On success it returns the record's new version. On a
	// mismatch, it returns a *VersionConflictError naming both
	// expectedVersion and the version the store actually found — never a
	// bare error a caller has to parse.
	PutIfVersion(ctx context.Context, key string, payload []byte, expectedVersion string) (newVersion string, err error)

	// PutIfAbsent creates key with payload, but only if no record exists
	// there yet. It is PutIfVersion(ctx, key, payload, "") under a name
	// that does not require the caller to know the empty-string
	// convention. On success it returns the new record's version; on
	// conflict it returns a *VersionConflictError with ExpectedVersion ""
	// and ActualVersion set to whatever is already there.
	PutIfAbsent(ctx context.Context, key string, payload []byte) (version string, err error)

	// Delete removes key, but only if its current version equals
	// expectedVersion — the same conditional discipline PutIfVersion
	// applies to writes, applied here to removal. Deleting an
	// already-absent key with expectedVersion == "" succeeds silently
	// (idempotent); deleting an already-absent key with a non-empty
	// expectedVersion, or a present key whose version does not match, both
	// return a *VersionConflictError.
	Delete(ctx context.Context, key string, expectedVersion string) error

	// List returns every key currently stored whose name begins with
	// keyPrefix, as an ordinary Go string prefix (not a path-hierarchy
	// match), sorted lexically. keyPrefix == "" lists every key. See each
	// implementation's own doc comment for how closely its underlying
	// primitive matches this; the returned set is exactly this contract
	// regardless.
	List(ctx context.Context, keyPrefix string) ([]string, error)
}

Store is a conditional-write key/value backend: a name for a small blob, versioned so a writer can prove it is updating what it last read rather than clobbering someone else's change. It has no notion of what a key names or what a payload contains — that belongs entirely to the caller. See doc.go for the full contract every implementation must honor.

func Fresh(s Store) Store

func NewRunCache(inner Store, prefix string) Store

type Trip ¶ added in v0.5.0

type Trip struct {
	Method string
	Key    string
	Via    string
	Site   string
}

Trip is one operation that reached the wrapped store. See CountingStore for what each field is for.

func ParseTripLog(data []byte) ([]Trip, error)

func (t Trip) String() string

type TripCounts ¶ added in v0.5.0

type TripCounts struct {
	Total int

	ByMethod map[string]int
	BySite   map[string]int
	ByVia    map[string]int

	// DistinctKeys is how many different keys the trips touched, and
	// RepeatTrips is Total minus DistinctKeys: the trips that re-read
	// something an earlier trip had already read. A cache can remove at
	// most RepeatTrips of them and never fewer than zero of the rest,
	// which is the whole reason this is reported beside the total.
	DistinctKeys int
	RepeatTrips  int
}

TripCounts is a set of trips summarized several ways at once. Every field is a total over the same trips, so a reader can check them against each other rather than having to trust one.

func Summarize(trips []Trip) TripCounts

type VersionConflictError ¶

type VersionConflictError struct {
	Key             string
	ExpectedVersion string
	ActualVersion   string
}

VersionConflictError reports that a conditional operation's expected version did not match what the store actually holds for Key. It names both versions so a caller can decide how to react — reread and retry, surface a merge conflict, give up loudly — without parsing an error string.

ActualVersion is "" when the store holds no record at Key at all (including the case where ExpectedVersion was itself "" and the key turned out to already exist would instead set ActualVersion to that existing version — "" only ever means "no record").

func (e *VersionConflictError) Error() string