Lifecycle and context ownership

Every Go Elemental web service follows one process lifecycle, hosted by go-core's lifecycle package, and one context-ownership convention. The lifecycle realizes the Elemental Architecture's infrastructure-service contract in Go: startup layer by layer, shutdown in reverse, and named readiness reported to the probes. The page uses the composition terms: graph, node, system, layer, subsystem, and coordinator.

The entrypoint owns the signal context

The application's entrypoint, the minimal binary above the composition root, traps signals, derives the root context, and owns the exit code; a web service's entrypoint also loads the configuration, which its composition root never does. The web service's entrypoint passes the root context to the composition root's run call, which hands it to the lifecycle coordinator's blocking run call, the one call that owns the sequence. go-core's process package holds this pre-infrastructure sequence (the signal-derived root context, failure and usage reporting before a logger exists, and the exit-code convention the reporters return), so it cannot drift between a program's binaries. A web service's composition root describes its subsystems as nodes of one go-core dependency graph, and the coordinator runs the built graph; nothing registers with it. Nothing executes before the run begins, and the coordinator installs no signal handlers of its own.

Not every node of the composition root is a subsystem. A layer of the architecture with no resource and nothing that runs, such as the Elemental Architecture's Domain Service composition, defines nodes whose values have no Start or Shutdown, so they take no part, and imports no part of this package.

A value takes part through single-method interfaces

A node's value takes part in the lifecycle only through the single-method interfaces it implements: a Starter's Start runs at startup, a Stopper's Shutdown runs at shutdown, and a Subsystem embeds both, for a value that does both. A value that implements neither, such as a configuration value, takes no part, and nothing registers a hook beside the value. The coordinator reads each subsystem's part from its value, so the part cannot drift from the value, and a test that substitutes a node's value changes the node's part with it. The method is Shutdown, as http.Server and the standard's libraries name it.

go-core's lifecycle package realizes the rule.

The wiring rule

A defect the composition root wires panics when the composition root's run call builds the graph, not when the graph is described, with the fix named: an unfinalized configuration, a missing pool, a malformed route prefix, a duplicate mount or subsystem, a group modified after its module is built, a lifecycle.Readiness bound to a second coordinator. The graph's own wiring defects panic with a graph: prefix. No runtime condition produces such a defect and no caller can recover from it sensibly, and the composition root is written once and runs at boot, so a loud failure there beats a silent one in production. A defect in configuration content, a reserved connection option or an invalid value, returns an error from the call that reads it, the configuration's finalize step or the provider's constructor, because configuration is input. A constructor's error returns from the graph's build, and the service exits 1.

Cold start, hot start, drain

Cold start constructs every object from configuration with no I/O, so a construction mistake fails before anything runs. Hot start brings the subsystems up layer by layer, each layer's subsystems concurrently and the request edge's layer last, so nothing serves before the infrastructure beneath it is up. A startup failure drains what did start, and readiness never reports a partially started process. The coordinator drives the drain and reverses the layers: the run context is cancelled, the request edge's layer drains first, and every layer runs against a fresh timeout-bounded context, so cleanup is not pre-cancelled and needs no cancellation guard of its own.

A value that can fail while running implements Monitored (Err() <-chan error), and the coordinator watches its channel: the first non-nil error ends the run.

Readiness reflects the live state of the process

The coordinator is ready once startup completes, and not ready again the moment draining begins, so a readiness probe reports a draining process as unavailable before its teardown runs. A subsystem exposes its own readiness through its named readiness check, which the coordinator infers only from a Starter that implements Ready, a lifecycle.ReadyStarter; a value that implements Ready alone joins no probe. That state is live: a subsystem that degrades fails the probe under its own name until it restores, and a process that begins draining stays not ready until it exits. Leaf components take a plain context.Context, keeping them usable without the coordinator.

Keyboard shortcuts

Settings