s3state

Documentation

Overview

Package s3state stores state snapshots in an S3 bucket. The layout under the configured prefix mirrors the local store's directory layout, one object per snapshot plus a current pointer and a lock marker:

[<prefix>/]<factory>/<stack>/
  current             // Object holding the rev of the current snapshot.
  lock                // Lock marker with holder info, present while held.
  snapshots/
    <rev>.json.enc    // rev is an RFC3339Nano timestamp.

Exclusion relies on S3 conditional writes: the lock marker and each snapshot are created with If-None-Match, so a concurrent create loses with a precondition failure instead of clobbering. Stores without conditional-write support cannot hold the lock safely and fail at Lock with the store's own error.

Index

• type S3Store
  • func NewS3Store(client *s3.Client, bucket, prefix, kmsKeyID, factory, stack string, ...) (*S3Store, error)
  • func (s *S3Store) Current() (*sdkstate.Snapshot, error)
  • func (s *S3Store) CurrentRev() (string, error)
  • func (s *S3Store) Delete(rev string) error
  • func (s *S3Store) ForceUnlock() error
  • func (s *S3Store) Get(rev string) (*sdkstate.Snapshot, error)
  • func (s *S3Store) List() ([]string, error)
  • func (s *S3Store) Lock(ctx context.Context) (sdkstate.Lock, error)
  • func (s *S3Store) SetCurrent(rev string) error
  • func (s *S3Store) Stack() string
  • func (s *S3Store) Write(snap *sdkstate.Snapshot) (string, error)

Types

type S3Store

type S3Store struct {
	Bucket   string
	Prefix   string
	KMSKeyID string
	// contains filtered or unexported fields
}

S3Store reads and writes snapshots under a per-stack key prefix in one bucket. KMSKeyID, when set, requests SSE-KMS with that key on every object written, the lock marker and current pointer included, so bucket policies that deny unencrypted puts hold.

func NewS3Store

func NewS3Store(
	client *s3.Client,
	bucket, prefix, kmsKeyID, factory, stack string,
	enc sdkencrypt.Encrypter,
) (*S3Store, error)

NewS3Store returns an S3Store for the given factory and stack in bucket, with all objects under prefix when it is not empty. The encrypter is required, but a pass-through (envencrypt.Noop) can be passed for tests.

func (*S3Store) Current

func (s *S3Store) Current() (*sdkstate.Snapshot, error)

Current returns the snapshot named by the current pointer. Returns sdkstate.ErrNoCurrent when no snapshot has been written yet.

func (*S3Store) CurrentRev

func (s *S3Store) CurrentRev() (string, error)

CurrentRev returns the rev the current pointer names, or sdkstate.ErrNoCurrent.

func (*S3Store) Delete

func (s *S3Store) Delete(rev string) error

Delete removes the snapshot with the given rev. Removing a rev that does not exist is not an error.

func (*S3Store) ForceUnlock

func (s *S3Store) ForceUnlock() error

ForceUnlock removes the lock marker without checking who holds it. Operators run this to recover after a leaked lock and must ensure no concurrent run is in progress.

func (*S3Store) Get

func (s *S3Store) Get(rev string) (*sdkstate.Snapshot, error)

Get returns the snapshot with the given rev.

func (*S3Store) List

func (s *S3Store) List() ([]string, error)

List returns the revs of every stored snapshot in chronological order. S3 lists keys lexically, which is chronological for RFC3339Nano revs.

func (*S3Store) Lock

func (s *S3Store) Lock(ctx context.Context) (sdkstate.Lock, error)

Lock acquires the stack's exclusive lock by creating the lock marker with If-None-Match. Lock blocks until the create wins or ctx is canceled; while blocked it polls on the same cadence as the local store. A canceled wait names the holder in its error.

func (*S3Store) SetCurrent

func (s *S3Store) SetCurrent(rev string) error

SetCurrent atomically points "current" at the named rev. The snapshot must already exist.

func (*S3Store) Stack

func (s *S3Store) Stack() string

Stack returns the stack name this store was constructed for. Required by the Backend interface.

func (*S3Store) Write

func (s *S3Store) Write(snap *sdkstate.Snapshot) (string, error)

Write commits snap to the bucket and returns its rev. The caller advances the current pointer with SetCurrent. Each rev starts as an RFC3339Nano timestamp; the snapshot object is created with If-None-Match, and on a precondition failure (two writes sharing the same nanosecond) a numeric suffix is appended until the create wins, so uniqueness does not depend on the clock advancing between writes.