Repository navigation
Description
Problem
Each Dioad server process starts a set of services (HTTP servers, workers, publishers, a store), fans their failures into one channel, reports readiness, drains, and then stops them in order within a deadline. Four separate implementations exist today:
| Where | Type | What only it has |
|---|---|---|
dioad/connect server |
internal/cmd/server/service.Manager |
rolls back already-started services on a start failure; skips the drain when a failure caused the stop; Service{Start,Stop,Health,Name} plus Failer and Liveness |
dioad/connect agent |
internal/cmd/agent.ServiceRegistry |
stop budget per service; StopStarted |
dioad/connect-control |
internal/lifecycle.Orchestrator (ShutdownStages) + internal/server.Readiness |
staged shutdown; readiness with named, cached, degraded checks and a start gate; Drain(delay) |
dioad/connect-control services |
hand-written Run per service |
the serverErr channel and shutdown copied three times, and already drifting |
connect's two Failer interfaces are identical apart from their doc comments. An operator sees different /health/ready and drain semantics depending on which server type they run, and every new server picks one of these implementations or writes a fifth.
Proposal
Add a lifecycle package next to NewOperationalServer, for example dioad/net/lifecycle or dioad/net/http/app, that combines the best parts:
- Interface:
Service{Start(ctx) error; Stop(ctx) error}, with optionalName,Health,LiveandFailed() <-chan error. These line up with http: add Start/Failed/Live lifecycle to Server so consumers stop re-implementing the serve wrapper net#342's proposeddch.Servermethods, so a*dch.Serveris aServicewith no adapter. - Starting: in registration order, rolling back on failure.
- Stopping: in stages (a stage is a set of services stopped concurrently), each stage with an optional budget, all within one overall deadline. Errors are collected with
errors.Join. - Failures: fanned into one channel; a failure-triggered stop skips the drain.
- Readiness: a gate with named checks, an optional degraded state (the process stays ready but reports the check), result caching with a TTL, and a start gate. It registers as a health source on the operational server, so
/health/readymeans the same thing everywhere. - Drain: a configurable delay that reports not-ready before listeners close.
- Constructor:
New(mgmt OperationalConfig, primary *dch.Server, ...), which also builds the management listener.
Check functions stay in callers. For example, connect-control's nosqlite store check stays in connect-control, so dioad/net gains no storage dependency.
Related
- http: add Start/Failed/Live lifecycle to Server so consumers stop re-implementing the serve wrapper net#342 is the per-server building block (
Start,Failed,Live). connect-control'sinternal/server.Serveis another copy of the wrapper it describes. - Add WithComponent ServerOption for structured log correlation across multiple server instances net#302:
WithComponentserver option.
Source: dioad/connect-control doc/claude-review-dioad-server-platform.md, findings P4 and P5.
Acceptance criteria: documentation by example
func Exampletests:ExampleApp: ordered start, a failing service, rollback, and the stop order printed.ExampleReadiness: a degraded check and drain.
examples/gains a non-HTTP worker daemon that uses the lifecycle with no listener, plus an API server with an operational listener that shows readiness and drain.examples/basic-http-serverand the othernetexamples move off hand-written signal and serve loops onto the lifecycle (see http: add Start/Failed/Live lifecycle to Server so consumers stop re-implementing the serve wrapper net#342).- Examples build in CI. Any
examples/program that runs a long-lived process is started in CI, checked for readiness, sent SIGTERM, and must exit 0. - Once the cross-repo reference server exists, it uses this capability in place of its own copy.
Activity
feat: server options, LogField, and examples that run in CI (#360)
patdowney commentedon Nov 14, 2026
The package from this issue is implemented and released as v0.1.0 (PR #2, merged).
Covered
App: ordered start with rollback; staged stop with per-stage budgets inside one deadline, errors joined witherrors.Join; failure fan-in into one channel; a failure-triggered stop skips the drain; a configurable drain delay.Readiness: start gate, named checks with a cache TTL, a degraded state that keeps the process ready, and a drain. It has theReadymethod that dioad/net'sAddHealthSourcelooks for, so it is a health source without this module importing net.func Exampletests:ExampleApp,ExampleApp_StopandExampleReadiness.Differences from the proposal
Shutdown, notStop, so that dioad/net's*http.Serveris aServicewith no adapter.Failed,LiveandReadyare optional. A service's name is given atAdd.New(mgmt OperationalConfig, primary *dch.Server, ...)constructor: it would make this module import dioad/net while net's examples import this module. A convenience constructor can live in net if wanted.Acceptance criteria in dioad/net
examples/onto the lifecycle, the non-HTTP worker daemon example, and the API server example showing readiness and drain: feat(examples): run the examples under dioad/lifecycle net#362.The "once the cross-repo reference server exists, it uses this capability" item is not done here.
This can be closed once dioad/net#362 is merged.
patdowney commentedon Nov 15, 2026
Delivered in dioad/net#362 (released in v0.72.0), which runs the net examples and Server on dioad/lifecycle.