lifecycle

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Aug 7, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package lifecycle computes durable desired-state reconciliation actions.

Index

Constants

This section is empty.

Variables

View Source
var LoadFileAssetCatalog = assetcatalog.LoadFileAssetCatalog

Functions

func ValidTerminationReason

func ValidTerminationReason(reason string) bool

ValidTerminationReason recognizes the complete stable v1 reason vocabulary.

Types

type Action

type Action string
const (
	ActionWait          Action = "wait"
	ActionStartInstance Action = "start_instance"
	ActionMarkReady     Action = "mark_ready"
	ActionDrain         Action = "drain"
	ActionStopInstance  Action = "stop_instance"
	ActionFinishStop    Action = "finish_stop"
	ActionDelete        Action = "delete"
	ActionFail          Action = "fail"
)

type ActiveSessionCanceller

type ActiveSessionCanceller interface {
	CancelSandboxSessions(context.Context, string, int64, string, time.Time) (int64, error)
}

ActiveSessionCanceller sends fenced cancellation to in-flight generation operations.

type AssignmentScheduler

type AssignmentScheduler interface {
	Schedule(context.Context, scheduler.ScheduleRequest) (scheduler.DurableAssignment, bool, error)
}

AssignmentScheduler persists one fenced placement and runner command atomically.

type BatchReconcileStore

type BatchReconcileStore interface {
	ClaimLifecycleBatch(ctx context.Context, workerID string, now time.Time, claimDuration time.Duration, batchSize int, wakeTrigger ports.LifecycleWakeTrigger) ([]ports.LifecycleReconcileClaim, error)
}

BatchReconcileStore claims an ordered cohort under the same worker fence.

type Decision

type Decision struct {
	Action            Action
	TerminationReason string
}

Decision is the single next action and any stable termination reason it establishes.

func Decide

func Decide(view View, now time.Time) Decision

Decide computes one restart-safe transition without performing side effects.

type EffectBrokerConfig

type EffectBrokerConfig struct {
	AssignmentClaimDuration time.Duration
	AssignmentDeadline      time.Duration
	HeartbeatTimeout        time.Duration
	RetryLimit              int64
	SerializationRetryLimit int
	AssetCatalog            SignedAssetCatalog
	SessionCanceller        ActiveSessionCanceller
	NewID                   func(string) string
	NewFencingToken         func() ([]byte, error)
	Now                     func() time.Time
}

EffectBrokerConfig contains explicit lifecycle effect bounds and artifact trust.

type EffectExecutor

type EffectExecutor interface {
	ExecuteLifecycleEffect(
		ctx context.Context,
		claim ports.LifecycleReconcileClaim,
		decision Decision,
		now time.Time,
		nextReconcileAt time.Time,
	) error
}

EffectExecutor performs one durable runner or object-store effect.

type FileAssetCatalog

type FileAssetCatalog = assetcatalog.FileAssetCatalog

type GarbageCatalog

type GarbageCatalog interface {
	ListGarbageObjectsDue(ctx context.Context, now time.Time, grace time.Duration, limit int) ([]ports.GarbageObject, error)
	CompleteGarbageObject(ctx context.Context, object ports.GarbageObject, now time.Time) error
}

GarbageCatalog publishes only objects that have passed a durable reachability grace.

type GarbageCollector

type GarbageCollector struct {
	Catalog   GarbageCatalog
	Objects   objectstore.Store
	Grace     time.Duration
	BatchSize int
}

GarbageCollector removes unreachable immutable bytes and records terminal evidence.

func (GarbageCollector) Sweep

func (collector GarbageCollector) Sweep(ctx context.Context, now time.Time) (int, error)

Sweep performs one bounded mark/recheck/delete batch.

type PostgresEffectBroker

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

PostgresEffectBroker turns lifecycle decisions into durable scheduler and runner commands.

func NewPostgresEffectBroker

func NewPostgresEffectBroker(
	ctx context.Context,
	databaseURL string,
	assignmentScheduler AssignmentScheduler,
	config EffectBrokerConfig,
) (*PostgresEffectBroker, error)

NewPostgresEffectBroker validates the durable effect composition.

func (*PostgresEffectBroker) Close

func (broker *PostgresEffectBroker) Close()

func (*PostgresEffectBroker) ExecuteLifecycleEffect

func (broker *PostgresEffectBroker) ExecuteLifecycleEffect(
	ctx context.Context,
	claim ports.LifecycleReconcileClaim,
	decision Decision,
	now time.Time,
	nextReconcileAt time.Time,
) error

ExecuteLifecycleEffect executes one restart-safe external-effect transition.

type ReconcileStore

type ReconcileStore interface {
	ClaimLifecycle(ctx context.Context, workerID string, now time.Time, claimDuration time.Duration, wakeTrigger ports.LifecycleWakeTrigger) (ports.LifecycleReconcileClaim, bool, error)
	ApplyLifecycleAction(ctx context.Context, claim ports.LifecycleReconcileClaim, action, terminationReason string, now, nextReconcileAt time.Time) error
}

ReconcileStore owns durable claims and compare-and-swap transition commits. The wake trigger is attribution evidence carried into the claim transaction; it never changes which work the claim query finds.

A zero nextReconcileAt is the parked schedule: the commit carries no durable deadline at all, so the Sandbox leaves the reconciliation work set until an external event schedules it again.

type Reconciler

type Reconciler struct {
	Store         ReconcileStore
	Effects       EffectExecutor
	WorkerID      string
	ClaimDuration time.Duration
	PollInterval  time.Duration
	BatchSize     int
}

Reconciler consumes durable desired state one idempotent transition at a time.

func (Reconciler) RunBatch

func (reconciler Reconciler) RunBatch(
	ctx context.Context,
	clock func() time.Time,
	wakeTrigger ports.LifecycleWakeTrigger,
) (bool, error)

RunBatch claims a bounded cohort and executes its effects sequentially.

func (Reconciler) RunOnce

func (reconciler Reconciler) RunOnce(
	ctx context.Context,
	now time.Time,
	wakeTrigger ports.LifecycleWakeTrigger,
) (Decision, bool, error)

RunOnce claims and commits at most one due Sandbox transition.

type SignedAsset

type SignedAsset = assetcatalog.SignedAsset

type SignedAssetCatalog

type SignedAssetCatalog = assetcatalog.SignedAssetCatalog

type SnapshotRetentionStore

type SnapshotRetentionStore interface {
	QueueExpiredSnapshotDelete(
		context.Context,
		ports.SnapshotRetentionInput,
	) (bool, error)
}

SnapshotRetentionStore admits due local Snapshot deletions without involving object storage or retained-byte accounting.

type SnapshotRetentionWorker

type SnapshotRetentionWorker struct {
	Store           SnapshotRetentionStore
	PollInterval    time.Duration
	NewID           func(string) string
	NewFencingToken func() ([]byte, error)
}

SnapshotRetentionWorker queues at most one expired local Snapshot deletion.

func (SnapshotRetentionWorker) RunOnce

func (worker SnapshotRetentionWorker) RunOnce(
	ctx context.Context,
	now time.Time,
) (bool, error)

type View

type View struct {
	Observed                  string
	Desired                   string
	StopEffectState           string
	GuestLiveness             string
	InstanceTerminationReason string
	IntentTerminationReason   string
	HasInstance               bool
	ActiveSessions            int64
	ReadyAt                   time.Time
	LastUsefulActivityAt      time.Time
	DrainStartedAt            time.Time
	DrainGrace                time.Duration
	IdleTimeout               time.Duration
	MaximumDuration           time.Duration
}

View contains only durable inputs needed for one idempotent decision.

Jump to

Keyboard shortcuts

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