lifecycle

type ComponentValue ¶

type ComponentValue struct {
	// Name identifies the component in every [TransitionValue] and in every
	// error field. It must be non-empty and unique within one Lifecycle.
	Name string
	// Start brings the component up. It is called in registration order.
	Start Start
	// Stop takes the component down. It is called ONLY if Start returned nil,
	// and in reverse of the order the components started in.
	Stop Stop
}

ComponentValue is one named unit of the application's startup order: what brings it up, and what takes it down.

The zero value is not runnable and is refused by Add (InvalidComponent) rather than accepted and silently skipped. Both halves are required: a component with nothing to stop is still asked to declare that explicitly, because "I forgot the teardown" and "there is no teardown" are the same nil, and only one of them is a defect. `func(context.Context) error { return nil }` is two seconds of typing and it puts the claim in the diff.

type Lifecycle ¶

type Lifecycle interface {
	// Add registers a component at the end of the order. It is refused while
	// the Lifecycle is started ([LifecycleRunning]), on a name already
	// registered ([DuplicateComponent]), and on a component that could never
	// run — empty name, nil Start, nil Stop ([InvalidComponent]).
	Add(component ComponentValue) error
	// Start runs every registered Start in registration order and returns nil
	// once all of them have. On the first failure it stops the components
	// already up, in reverse order, and reports the failure; the Lifecycle is
	// then back in its not-started state, so a caller may fix the cause, Add,
	// and Start again.
	Start(ctx context.Context) error
	// Stop runs the Stop of every component that started, in reverse of the
	// order they started in, and reports what failed. It is idempotent: a
	// Lifecycle that never started, or that has already stopped, returns nil
	// without calling anything.
	Stop(ctx context.Context) error
}

Lifecycle owns an ordered set of ComponentValue and drives it up and down. Implementations MUST be safe for concurrent use.

IFACE-PLUGIN: the concrete engine stays unexported behind its constructor in internal/service/lifecycle.

type Phase ¶

type Phase uint8

Phase names which half of a component's contract a TransitionValue reports. It is a closed set of two: a component goes up or it goes down.

const PhaseStart Phase = 1

const PhaseStop Phase = 2

func (p Phase) String() string

type Start ¶

type Start func(ctx context.Context) error

Start brings one component up. It MUST honour ctx: the Lifecycle passes the context Start was called with, so cancelling that context is how a caller aborts a startup that is taking too long.

Returning a non-nil error means the component is NOT up. The Lifecycle then stops every component that IS up, in reverse order, and never calls this component's Stop — a Start that fails owns its own cleanup, which is the only rule under which a Stop may assume its Start succeeded.

type Stop ¶

type Stop func(ctx context.Context) error

Stop takes one component down. It is called only for a component whose Start returned nil, and only once.

ctx carries this component's shutdown budget and is cancelled when that budget expires. Cancellation is an ANNOUNCEMENT, not a severance: the Lifecycle stops waiting, but it does not and cannot kill the goroutine, and it closes nothing on the component's behalf. A Stop that ignores ctx therefore delays nothing except its own report — the components after it in the reverse order each get their own full budget.

type TransitionValue ¶

type TransitionValue struct {
	// Name is the component's registered name.
	Name string
	// Phase says whether this was the Start half or the Stop half.
	Phase Phase
	// Begun is the instant the call was made, read from the injected clock.
	Begun time.Time
	// Ended is the instant the Lifecycle stopped waiting for it. On a
	// TimedOut transition that is when the budget expired, NOT when the
	// component eventually returned — the Lifecycle does not know when that
	// was, and reporting a guess would be worse than reporting the fact.
	Ended time.Time
	// TimedOut reports that the component's Stop had not returned when its
	// budget expired. The goroutine was abandoned, not killed; see [Stop].
	TimedOut bool
	// Err is what the component returned, verbatim, so the caller's errors.Is
	// keeps working. A panic is the one exception: it becomes
	// [ComponentPanicked] with the recovered value in a field.
	Err error
}

TransitionValue reports one call the Lifecycle made into a component: which component, which half of its contract, when it began and ended, and what came back.

It reports DECISIONS, not only successes. A Stop abandoned at its budget produces one too, with TimedOut set and an Err naming the component — a lifecycle that reported only the calls that returned would make a component which never stops look exactly like one that stops instantly, and would leave "this component overran" provable only by timing the process.