transition

Documentation

Overview

Package transition implements state machine logic for staging operations. It provides reducers (pure functions) that compute new states from current states and actions, separating state computation logic from side effects for testability.

Index

• Variables
• type EntryAction
• type EntryActionAdd
• type EntryActionDelete
• type EntryActionEdit
• type EntryActionReset
• type EntryExecuteOptions
• type EntryStagedState
• type EntryStagedStateCreate
• type EntryStagedStateDelete
• type EntryStagedStateNotStaged
• type EntryStagedStateUpdate
• type EntryState
  • func LoadEntryState(ctx context.Context, store store.ReadOperator, service staging.Service, ...) (EntryState, error)
  • func LoadEntryStateWithMetadata(ctx context.Context, store store.ReadOperator, service staging.Service, ...) (EntryState, *time.Time, error)
• type EntryTransitionResult
  • func ReduceEntry(state EntryState, action EntryAction) EntryTransitionResult
• type Executor
  • func NewExecutor(store store.ReadWriteOperator) *Executor
  • func (e *Executor) ExecuteEntry(ctx context.Context, service staging.Service, name string, state EntryState, ...) (EntryTransitionResult, error)
  • func (e *Executor) ExecuteTag(ctx context.Context, service staging.Service, name string, ...) (TagTransitionResult, error)
• type StagedTags
  • func LoadStagedTags(ctx context.Context, store store.ReadOperator, service staging.Service, ...) (StagedTags, *time.Time, error)
  • func (t StagedTags) Clone() StagedTags
  • func (t StagedTags) IsEmpty() bool
• type TagAction
• type TagActionTag
• type TagActionUntag
• type TagTransitionResult
  • func ReduceTag(entryState EntryState, stagedTags StagedTags, action TagAction) TagTransitionResult

Variables

var (
	ErrCannotAddToUpdate    = errors.New("cannot add: already staged for update")
	ErrCannotAddToDelete    = errors.New("cannot add: already staged for deletion")
	ErrCannotAddToExisting  = errors.New("cannot add: resource already exists, use edit instead")
	ErrCannotEditDelete     = errors.New("cannot edit: staged for deletion, reset first")
	ErrCannotDeleteNotFound = errors.New("cannot delete: resource not found")
	ErrCannotTagNotFound    = errors.New("cannot tag: resource not found")
	ErrCannotTagDelete      = errors.New("cannot tag: resource staged for deletion")
	ErrCannotUntagNotFound  = errors.New("cannot untag: resource not found")
	ErrCannotUntagDelete    = errors.New("cannot untag: resource staged for deletion")
)

Error definitions for transition failures.

Types

type EntryAction

type EntryAction interface {
	// contains filtered or unexported methods
}

EntryAction represents an action on an entry. This is a sealed interface - only the types defined in this package implement it.

type EntryActionAdd

type EntryActionAdd struct {
	Value string
}

EntryActionAdd represents adding a new entry (create operation).

type EntryActionDelete

type EntryActionDelete struct{}

EntryActionDelete represents deleting an entry.

type EntryActionEdit

type EntryActionEdit struct {
	Value string
}

EntryActionEdit represents editing an existing entry (update operation).

type EntryActionReset

type EntryActionReset struct{}

EntryActionReset represents resetting (unstaging) an entry.

type EntryExecuteOptions

type EntryExecuteOptions struct {
	BaseModifiedAt *time.Time // Base modification time for conflict detection
	Description    *string    // Optional description for the staged entry
}

EntryExecuteOptions holds optional metadata for entry execution.

type EntryStagedState

type EntryStagedState interface {
	// contains filtered or unexported methods
}

EntryStagedState represents the staging state of an entry. This is a sealed interface - only the types defined in this package implement it.

type EntryStagedStateCreate

type EntryStagedStateCreate struct {
	DraftValue string
}

EntryStagedStateCreate represents an entry staged for creation.

type EntryStagedStateDelete

type EntryStagedStateDelete struct{}

EntryStagedStateDelete represents an entry staged for deletion.

type EntryStagedStateNotStaged

type EntryStagedStateNotStaged struct{}

EntryStagedStateNotStaged represents an entry that is not staged.

type EntryStagedStateUpdate

type EntryStagedStateUpdate struct {
	DraftValue string
}

EntryStagedStateUpdate represents an entry staged for update.

type EntryState

type EntryState struct {
	CurrentValue *string          // nil means non-existing on AWS
	StagedState  EntryStagedState // Current staging state
}

EntryState represents the current state of a staged entry.

func LoadEntryState

func LoadEntryState(
	ctx context.Context,
	store store.ReadOperator,
	service staging.Service,
	name string,
	currentAWSValue *string,
) (EntryState, error)

LoadEntryState loads the current entry state from the store and AWS info.

func LoadEntryStateWithMetadata

func LoadEntryStateWithMetadata(
	ctx context.Context,
	store store.ReadOperator,
	service staging.Service,
	name string,
	currentAWSValue *string,
) (EntryState, *time.Time, error)

LoadEntryStateWithMetadata loads the current entry state and returns BaseModifiedAt metadata. BaseModifiedAt is used for conflict detection when applying changes.

type EntryTransitionResult

type EntryTransitionResult struct {
	NewState    EntryState
	DiscardTags bool // True if tags should also be unstaged (e.g., when deleting a CREATE)
	Error       error
}

EntryTransitionResult holds the result of an entry state transition.

func ReduceEntry

func ReduceEntry(state EntryState, action EntryAction) EntryTransitionResult

ReduceEntry applies an entry action to produce a new state.

type Executor

type Executor struct {
	Store store.ReadWriteOperator
}

Executor executes state transitions and persists results to the store.

func NewExecutor

func NewExecutor(store store.ReadWriteOperator) *Executor

NewExecutor creates a new Executor.

func (*Executor) ExecuteEntry

func (e *Executor) ExecuteEntry(
	ctx context.Context,
	service staging.Service,
	name string,
	state EntryState,
	action EntryAction,
	opts *EntryExecuteOptions,
) (EntryTransitionResult, error)

ExecuteEntry executes an entry action and persists the result.

func (*Executor) ExecuteTag

func (e *Executor) ExecuteTag(
	ctx context.Context,
	service staging.Service,
	name string,
	entryState EntryState,
	stagedTags StagedTags,
	action TagAction,
	baseModifiedAt *time.Time,
) (TagTransitionResult, error)

ExecuteTag executes a tag action and persists the result.

type StagedTags

type StagedTags struct {
	ToSet   map[string]string   // Tags to add or update
	ToUnset maputil.Set[string] // Tag keys to remove
}

StagedTags represents the staged tag changes. Tags are stored as diff operations rather than final state. AWS current values are checked at staging time for auto-skip.

func LoadStagedTags

func LoadStagedTags(ctx context.Context, store store.ReadOperator, service staging.Service, name string) (StagedTags, *time.Time, error)

LoadStagedTags loads the current staged tags from the store.

func (StagedTags) Clone

func (t StagedTags) Clone() StagedTags

Clone returns a deep copy of the staged tags with initialized maps.

func (StagedTags) IsEmpty

func (t StagedTags) IsEmpty() bool

IsEmpty returns true if there are no staged tag changes.

type TagAction

type TagAction interface {
	// contains filtered or unexported methods
}

TagAction represents an action on tags. This is a sealed interface - only the types defined in this package implement it.

type TagActionTag

type TagActionTag struct {
	Tags           map[string]string // Tags to add or update
	CurrentAWSTags map[string]string // Current AWS tag values for auto-skip (nil to disable)
}

TagActionTag represents adding or updating tags. CurrentAWSTags is used to auto-skip tags that match AWS current values. Pass nil to disable auto-skip (e.g., when AWS tags couldn't be fetched).

type TagActionUntag

type TagActionUntag struct {
	Keys              maputil.Set[string] // Tag keys to remove
	CurrentAWSTagKeys maputil.Set[string] // Current AWS tag keys for auto-skip (nil to disable)
}

TagActionUntag represents removing tags. CurrentAWSTagKeys is used to auto-skip tag keys that don't exist on AWS. Pass nil to disable auto-skip (e.g., when AWS tags couldn't be fetched).

type TagTransitionResult

type TagTransitionResult struct {
	NewStagedTags StagedTags
	Error         error
}

TagTransitionResult holds the result of a tag state transition.

func ReduceTag

func ReduceTag(entryState EntryState, stagedTags StagedTags, action TagAction) TagTransitionResult

ReduceTag applies a tag action to produce new staged tags.