lifecycle

Documentation

Overview

Package lifecycle defines explicit cleanup and lifecycle coordination types used by Spice compiler phases and generated application code.

Index

• Variables
• type Cleanup
• type ContextFactory
• type Coordinator
  • func NewCoordinator() *Coordinator
  • func (c *Coordinator) Abort(ctx context.Context, cause error) error
  • func (c *Coordinator) RegisterCleanup(id string, cleanup Cleanup) error
  • func (c *Coordinator) RegisterModuleCleanup(module, id string, cleanup Cleanup) error
  • func (c *Coordinator) RegisterObserver(observer Observer) error
  • func (c *Coordinator) Run(ctx context.Context, hooks []Hook, shutdown ContextFactory) error
  • func (c *Coordinator) Start(ctx context.Context, hooks []Hook) error
  • func (c *Coordinator) State() State
  • func (c *Coordinator) Stop(ctx context.Context) error
• type Hook
• type Observation
• type Observer
• type Operation
• type Phase
• type State
• type TransitionError
  • func (e *TransitionError) Error() string
  • func (e *TransitionError) Unwrap() error

Variables

var ErrInvalidTransition = errors.New("invalid application lifecycle transition")

ErrInvalidTransition identifies an operation that is not legal in the coordinator's current state.

Types

type Cleanup

type Cleanup func(context.Context) error

Cleanup releases one successfully constructed provider resource. Generated code invokes it with a caller-owned rollback or shutdown context.

type ContextFactory

type ContextFactory func() (context.Context, context.CancelFunc)

ContextFactory creates a caller-owned context and release function when shutdown begins. It allows Run to obtain a fresh shutdown deadline only after the run context is canceled.

type Coordinator

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

Coordinator implements generic lifecycle state and callback ordering for one generated application. It performs no discovery or dependency resolution.

func NewCoordinator

func NewCoordinator() *Coordinator

NewCoordinator returns a coordinator ready to accept construction cleanups.

func (*Coordinator) Abort

func (c *Coordinator) Abort(ctx context.Context, cause error) error

Abort records a construction failure, runs every armed cleanup in reverse construction order, and joins rollback failures with cause.

func (*Coordinator) RegisterCleanup

func (c *Coordinator) RegisterCleanup(id string, cleanup Cleanup) error

RegisterCleanup arms one provider cleanup. Generated constructors call this immediately after the corresponding provider succeeds. A nil cleanup is a valid no-op.

func (*Coordinator) RegisterModuleCleanup

func (c *Coordinator) RegisterModuleCleanup(module, id string, cleanup Cleanup) error

RegisterModuleCleanup arms one provider cleanup with optional module ownership metadata. Generated constructors use this form.

func (*Coordinator) RegisterObserver

func (c *Coordinator) RegisterObserver(observer Observer) error

RegisterObserver adds a synchronous observer before lifecycle execution.

func (*Coordinator) Run

func (c *Coordinator) Run(ctx context.Context, hooks []Hook, shutdown ContextFactory) error

Run starts the application, waits for ctx cancellation, obtains a fresh caller-owned shutdown context, and stops the application. Cancellation of the run context is the normal shutdown signal and is not returned as an error.

func (*Coordinator) Start

func (c *Coordinator) Start(ctx context.Context, hooks []Hook) error

Start executes explicit hooks serially in the supplied dependency-first order. A failure stops previously successful hooks, then runs every construction cleanup.

func (*Coordinator) State

func (c *Coordinator) State() State

State returns the coordinator's current state.

func (*Coordinator) Stop

func (c *Coordinator) Stop(ctx context.Context) error

Stop is idempotent. It stops successfully started components in reverse order and then runs construction cleanups in reverse order. Concurrent Stop calls wait for the in-progress stop or their own context cancellation.

type Hook

type Hook struct {
	ID     string
	Module string
	Start  Cleanup
	Stop   Cleanup
}

Hook contains explicit generated start and optional stop callbacks for one provider-owned component.

type Observation

type Observation struct {
	Module    string
	Component string
	Operation Operation
	Phase     Phase
	Err       error
}

Observation is one synchronous lifecycle callback observation. Err is set only on an end event when the callback failed.

type Observer

type Observer func(context.Context, Observation)

Observer receives lifecycle observations on the callback-executing goroutine. It has no error return and must not panic or block indefinitely.

type Operation

type Operation string

Operation identifies the lifecycle callback being observed.

const (
	// OperationStart identifies a component start hook.
	OperationStart Operation = "start"
	// OperationStop identifies a component stop hook.
	OperationStop Operation = "stop"
	// OperationCleanup identifies a provider construction cleanup.
	OperationCleanup Operation = "cleanup"
)

type Phase

type Phase string

Phase identifies whether a callback is about to run or has completed.

const (
	// PhaseBegin is emitted immediately before callback invocation.
	PhaseBegin Phase = "begin"
	// PhaseEnd is emitted immediately after callback invocation.
	PhaseEnd Phase = "end"
)

type State

type State string

State is the observable state of one generated application coordinator.

const (
	// StateInvalid is returned for an uninitialized coordinator.
	StateInvalid State = ""
	// StateConstructed means providers exist but lifecycle hooks have not started.
	StateConstructed State = "constructed"
	// StateStarting means start hooks are executing.
	StateStarting State = "starting"
	// StateReady means every start hook completed successfully.
	StateReady State = "ready"
	// StateStopping means stop hooks or construction cleanups are executing.
	StateStopping State = "stopping"
	// StateStopped means normal stop and cleanup completed.
	StateStopped State = "stopped"
	// StateFailed means construction abort or startup rollback completed.
	StateFailed State = "failed"
)

type TransitionError

type TransitionError struct {
	Operation string
	State     State
}

TransitionError reports an invalid lifecycle state transition.

func (*TransitionError) Error

func (e *TransitionError) Error() string

Error describes the rejected operation and current state.

func (*TransitionError) Unwrap

func (e *TransitionError) Unwrap() error

Unwrap supports errors.Is(err, ErrInvalidTransition).