Documentation
¶
Overview ¶
Package lifecyclekit owns the uniform worker/operator supervised-component machinery that the generated internal/app/lifecycle_gen.go delegates to.
Status (FORGE_SHAPE_REDESIGN §2 — lib-boundary extraction) ¶
The generated lifecycle_gen.go is the SUPERVISED-component surface: the workers and operators serverkit runs over the constructed *Services. Per the "generated files are tables, not programs" rule, all the uniform machinery lives HERE and the generated file shrinks to thin per-app DATA:
- WorkerList(s) returns explicit lifecyclekit.WrapWorker("name", s.Field) rows;
- OperatorList(s) returns one row per operator;
- RunOperators(s, ...) is a single delegation to lifecyclekit.Run with one dumb Controller row per operator.
What lives here:
- WorkerInstance / ContextWorkerInstance — lifecycle wrappers (Name / Start / Stop, plus the ctx-aware RunContext sibling) that satisfy serverkit.Worker / serverkit.ContextWorker.
- WrapWorker — the runtime type-switch the generated WorkerList rows call per worker: a worker implementing RunContext gets the ctx-aware wrapper (per-worker cancel-on-shutdown), everything else gets the legacy Start wrapper.
- WorkerLifecycle — the Start/Stop shape every generated worker exposes.
- Worker / Operator — re-exports of the serverkit contracts the generated lists return, so the generated file imports only lifecyclekit.
- Controller / Options / Run — the controller-manager bridge over operatorkit the generated RunOperators delegates to.
- HasOperators — the predicate over a serverkit.Operator slice.
Adding a worker needs no `forge generate` change to this package — the type-switch detects RunContext at runtime.
The operator bridge (Run, Controller, Options) is a thin pass-through to forge/pkg/appkit/operatorkit so projects WITHOUT operators never compile controller-runtime and its Kubernetes dependency tree: the generated import of the operatorkit-backed Run is conditional on the project having operators (the template only references RunOperators' operatorkit path when .Operators is non-empty).
Index ¶
- func HasOperators(operators []Operator) bool
- func Run(ctx context.Context, logger *slog.Logger, opts Options, ...) error
- func WrapWorker(name string, w WorkerLifecycle) serverkit.Worker
- type ContextWorkerInstance
- type Controller
- type Operator
- type Options
- type Worker
- type WorkerInstance
- type WorkerLifecycle
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HasOperators ¶
HasOperators reports whether the supplied operator list is non-empty. The generated HasOperators(s) delegates here over OperatorList(s).
func Run ¶
Run creates a controller manager, registers every controller's scheme and setup, and starts the manager. It is the bridge the generated RunOperators delegates to; behaviour (kubeconfig resolution with graceful no-cluster degrade, leader election, scheme / controller registration, health probe) lives in operatorkit.Run. Blocks until ctx is cancelled — the caller runs it in a goroutine.
func WrapWorker ¶
func WrapWorker(name string, w WorkerLifecycle) serverkit.Worker
WrapWorker wraps a constructed worker for the serverkit supervisor. It is the single helper the generated WorkerList rows call — a runtime type-switch (chosen over codegen-time AST detection so the generated table stays one dumb call per row and adding RunContext to a worker needs no `forge generate`):
- the worker implements RunContext(ctx) → *ContextWorkerInstance, which satisfies serverkit.ContextWorker, so the supervisor's `w.(serverkit.ContextWorker)` assertion sees through the wrapper and uses the ctx-aware lifecycle;
- otherwise → *WorkerInstance, which has no RunContext method, so the supervisor's legacy Start path is untouched.
Types ¶
type ContextWorkerInstance ¶
type ContextWorkerInstance struct {
WorkerInstance
// contains filtered or unexported fields
}
ContextWorkerInstance is the ctx-aware sibling of WorkerInstance: it additionally exposes RunContext, so a value of this type satisfies serverkit.ContextWorker and the serverkit supervisor prefers the ctx-aware lifecycle (per-worker cancel-on-shutdown) over legacy Start. It is a SEPARATE type — not an always-present RunContext on WorkerInstance that sometimes delegates to Start — because the supervisor's preference is a type assertion: a universally-present RunContext would make every worker look ctx-aware and silently change legacy workers' lifecycle.
func NewContextWorkerInstance ¶
func NewContextWorkerInstance(name string, runContext, stop func(ctx context.Context) error) *ContextWorkerInstance
NewContextWorkerInstance builds a ContextWorkerInstance from a worker's name and its RunContext/Stop methods. The embedded WorkerInstance's Start delegates to runContext — semantically identical for a ctx-aware worker (both receive the supervisor's per-worker ctx), and the supervisor never takes the Start path when RunContext is present anyway; Start exists only so the wrapper still satisfies the base serverkit.Worker interface.
func (*ContextWorkerInstance) RunContext ¶
func (w *ContextWorkerInstance) RunContext(ctx context.Context) error
RunContext runs the worker's ctx-aware main loop. See serverkit.ContextWorker for the full shutdown contract.
type Controller ¶
type Controller = operatorkit.Controller
Controller is one generated operator row: the CRD scheme installer and the controller's manager hookup. It is a re-export of operatorkit.Controller so the generated RunOperators references a lifecyclekit type.
type Operator ¶
Operator is the minimal contract serverkit needs to count supervised operators — a re-export of serverkit.Operator so the generated OperatorList returns a lifecyclekit type.
type Options ¶
type Options = operatorkit.Options
Options carries the per-project controller-manager configuration the generated RunOperators supplies — a re-export of operatorkit.Options.
type Worker ¶
Worker is the runtime contract for a long-running background task — a re-export of serverkit.Worker so the generated WorkerList returns a lifecyclekit type and the generated file imports only lifecyclekit.
type WorkerInstance ¶
type WorkerInstance struct {
// contains filtered or unexported fields
}
WorkerInstance wraps a worker with its lifecycle methods (Name / Start / Stop). WrapWorker returns one for legacy Start/Stop workers.
func NewWorkerInstance ¶
func NewWorkerInstance(name string, start, stop func(ctx context.Context) error) *WorkerInstance
NewWorkerInstance builds a WorkerInstance row from a worker's name and Start/Stop methods.
func (*WorkerInstance) Name ¶
func (w *WorkerInstance) Name() string
Name returns the worker's identifier.
type WorkerLifecycle ¶
WorkerLifecycle is the Start/Stop surface every generated worker type exposes — the serverkit.Worker shape minus Name, which the generated table supplies from forge.yaml rather than from the worker itself.
Source Files