branching

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jul 23, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package branching coordinates database-only scenario checkpoints and branches.

Index

Constants

This section is empty.

Variables

View Source
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")
)
View Source
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

func (b *Branch) Environment() any

Environment returns the freshly bound application environment.

func (*Branch) Evidence

func (b *Branch) Evidence() Evidence

Evidence returns a defensive copy of branch evidence.

func (*Branch) Finish

func (b *Branch) Finish(ctx context.Context) error

Finish cleans the replacement group in reverse order and is idempotent.

func (*Branch) Handles

func (b *Branch) Handles() Handles

Handles returns a defensive copy of the replacements bound for this branch.

type BranchResult

type BranchResult struct {
	Name     string
	Evidence Evidence
	Err      error
}

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

type Capability struct {
	Provider string
	Version  string
}

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

type CheckpointMeta struct {
	ID       string
	ParentID string
	Source   string
	Revision string
}

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

type EnvironmentFactory func(context.Context, Handles) (any, error)

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 Handles

type Handles map[string]any

Handles maps application names to fresh provider replacement handles.

type Holder

type Holder interface {
	Capability() Capability
	Capture(context.Context) (HolderCheckpoint, error)
}

Holder creates immutable checkpoints of one application-owned database.

type HolderBranch

type HolderBranch interface {
	Handle() any
	Finish(context.Context) error
}

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

type HolderEvidence struct {
	Name       string
	Provider   string
	Version    string
	Generation string
}

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

type QuarantinedResource struct {
	Holder string
	Phase  string
	Err    error
}

QuarantinedResource is a partial resource whose compensation failed.

type Registration

type Registration struct {
	Name   string
	Holder Holder
}

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"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL