lifecycle

package
v0.4.2 Latest Latest
Warning

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

Go to latest
Published: Aug 8, 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 IdleSince added in v0.3.1

func IdleSince(view View) time.Time

IdleSince is the instant the running Instance's idle window is measured from, and the single reference both the drain decision and the wake-up it schedules use. Useful activity is generation-scoped, but the Sandbox carries one denormalized `last_activity_at` across generations, so a restarted Sandbox reports activity that belongs to the Instance before it. An Instance cannot have been idle for longer than it has been ready, so readiness bounds the window and a restart earns its full idle timeout instead of draining on its first reconciliation.

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