Documentation
¶
Overview ¶
Package branching coordinates database-only scenario checkpoints and branches.
Index ¶
- Variables
- type Branch
- type BranchResult
- type BranchSpec
- type Capability
- type Checkpoint
- func (c *Checkpoint) Evidence() Evidence
- func (c *Checkpoint) Release(ctx context.Context) error
- func (c *Checkpoint) RunSequential(ctx context.Context, specs ...BranchSpec) []BranchResult
- func (c *Checkpoint) StartBranch(ctx context.Context, name string, factory EnvironmentFactory) (*Branch, error)
- type CheckpointMeta
- type CleanupEvidence
- type EnvironmentFactory
- type Evidence
- type Handles
- type Holder
- type HolderBranch
- type HolderCheckpoint
- type HolderEvidence
- type LifecycleError
- type QuarantinedResource
- type Registration
- type Registry
- type Scope
Constants ¶
This section is empty.
Variables ¶
var ( ErrEmptyHolderName = errors.New("branching: holder name is empty") ErrDuplicateHolderName = errors.New("branching: duplicate holder name") ErrNilHolder = errors.New("branching: holder is nil") ErrNilCheckpoint = errors.New("branching: holder returned a nil checkpoint") ErrEmptyGeneration = errors.New("branching: holder checkpoint generation is empty") ErrNilBranch = errors.New("branching: holder returned a nil branch") ErrNilReplacementHandle = errors.New("branching: holder returned a nil replacement handle") ErrReleasedCheckpoint = errors.New("branching: checkpoint is released") ErrEmptyCheckpointID = errors.New("branching: checkpoint identity is empty") ErrEmptyBranchName = errors.New("branching: branch name is empty") ErrDuplicateBranchName = errors.New("branching: duplicate branch name") ErrNilEnvironmentFactory = errors.New("branching: environment factory is nil") )
var DefaultExcludedState = []string{
"chatwright-emulator",
"message-handles",
"message-consumption-cursors",
"clock",
"queue",
"process",
"cache",
"filesystem",
}
DefaultExcludedState is copied into every evidence record. It prevents a database checkpoint from being presented as a complete process snapshot.
Functions ¶
This section is empty.
Types ¶
type Branch ¶
type Branch struct {
// contains filtered or unexported fields
}
Branch is one fully bound sibling environment.
func (*Branch) Environment ¶
Environment returns the freshly bound application environment.
type BranchResult ¶
BranchResult records continuation and cleanup for one sibling.
type BranchSpec ¶
type BranchSpec struct {
Name string
Factory EnvironmentFactory
Continue func(context.Context, any, Evidence) error
}
BranchSpec is one sibling executed by RunSequential.
type Capability ¶
Capability describes the implementation behind one registered holder.
type Checkpoint ¶
type Checkpoint struct {
// contains filtered or unexported fields
}
Checkpoint is an all-holders immutable checkpoint.
func (*Checkpoint) Evidence ¶
func (c *Checkpoint) Evidence() Evidence
Evidence returns a defensive snapshot of checkpoint evidence.
func (*Checkpoint) Release ¶
func (c *Checkpoint) Release(ctx context.Context) error
Release releases every holder checkpoint in reverse registration order. Repeated calls return the same cleanup result without calling providers again.
func (*Checkpoint) RunSequential ¶
func (c *Checkpoint) RunSequential(ctx context.Context, specs ...BranchSpec) []BranchResult
RunSequential starts, runs and finishes each sibling before starting the next.
func (*Checkpoint) StartBranch ¶
func (c *Checkpoint) StartBranch(ctx context.Context, name string, factory EnvironmentFactory) (*Branch, error)
StartBranch creates all replacements before invoking the application factory.
type CheckpointMeta ¶
CheckpointMeta supplies the semantic identity and lineage owned by a scenario.
type CleanupEvidence ¶
type CleanupEvidence struct {
Status string
Quarantined []QuarantinedResource
}
CleanupEvidence records whether lifecycle resources were released cleanly.
type EnvironmentFactory ¶
EnvironmentFactory binds a complete replacement group into a fresh app world.
type Evidence ¶
type Evidence struct {
Scope Scope
CheckpointID string
ParentCheckpointID string
Source string
Revision string
BranchName string
Mechanism string
Holders []HolderEvidence
ExcludedState []string
Cleanup CleanupEvidence
}
Evidence states exactly what a checkpoint or branch isolated.
type Holder ¶
type Holder interface {
Capability() Capability
Capture(context.Context) (HolderCheckpoint, error)
}
Holder creates immutable checkpoints of one application-owned database.
type HolderBranch ¶
HolderBranch owns one fresh replacement database handle.
type HolderCheckpoint ¶
type HolderCheckpoint interface {
Generation() string
Branch(context.Context) (HolderBranch, error)
Release(context.Context) error
}
HolderCheckpoint is the provider-owned state captured for one holder.
type HolderEvidence ¶
HolderEvidence identifies one captured database generation.
type LifecycleError ¶
type LifecycleError struct {
Phase string
Holder string
Cause error
Quarantined []QuarantinedResource
}
LifecycleError retains the primary lifecycle failure and any failed cleanup.
func (*LifecycleError) Error ¶
func (e *LifecycleError) Error() string
func (*LifecycleError) Unwrap ¶
func (e *LifecycleError) Unwrap() error
Unwrap preserves the primary failure for errors.Is and errors.As.
type QuarantinedResource ¶
QuarantinedResource is a partial resource whose compensation failed.
type Registration ¶
Registration assigns the application-level identity used in evidence and errors.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is an immutable, validated holder registration order.
func NewRegistry ¶
func NewRegistry(registrations ...Registration) (*Registry, error)
NewRegistry validates all names before any holder lifecycle method can run.
func (*Registry) Capture ¶
func (r *Registry) Capture(ctx context.Context, meta CheckpointMeta) (*Checkpoint, error)
Capture creates one publishable checkpoint only after all holders succeed.
type Scope ¶
type Scope string
Scope is the state boundary covered by checkpoint and branch evidence.
const ( // ScopeDatabaseOnly means only registered database holders are isolated. ScopeDatabaseOnly Scope = "database-only" // MechanismBranch identifies a native branch created from a checkpoint. MechanismBranch = "branch" )