Skip to content

feat: add App and Readiness for ordered start, staged stop and drain - #2

Merged
patdowney merged 3 commits into
mainfrom
feat/lifecycle-app
Nov 14, 2026
Merged

patdowney merged 3 commits into
mainfrom
feat/lifecycle-app

Conversation

@patdowney

Copy link
Copy Markdown
Contributor

Implements the lifecycle package proposed in #1.

What it adds

  • App
    • Starts services in registration order, and rolls back the ones that had started when a service fails.
    • Stops them in stages: concurrent within a stage, an optional budget per stage, all inside one stop timeout. With no stages they stop in reverse registration order. Errors are joined with errors.Join.
    • Fans the failures of services that implement Failed() <-chan error into one channel, as a *ServiceError naming the service.
    • Run drains before it stops when its context is done, and skips the drain when a failure caused the stop.
  • Readiness
    • A start gate, named checks with an optional cache TTL, a degraded state that keeps the process ready, and a drain.
    • It has the Ready(ctx) (any, error) method that dioad/net's AddHealthSource looks for, so /health/ready reports it without this module importing net.
  • Examples: ExampleApp, ExampleApp_Stop and ExampleReadiness, each with a checked // Output:.
  • Repo setup: module, Makefile verify gate (same as dioad/net, with GOWORK=off), .golangci.yml, and a CI workflow.

Deviations from #1

  • The stop method is Shutdown, not Stop. Shared process lifecycle: ordered start, staged stop, failure fan-in, readiness and drain #1 asks for Stop(ctx) and also for *dch.Server to be a Service with no adapter; dioad/net's http.Server has Shutdown, so the name follows the second goal. Failed, Live and Ready are optional, found by interface assertion.
  • No New(mgmt OperationalConfig, primary *dch.Server, ...) constructor. It would make this module import dioad/net while net's examples import this module, creating a module cycle. A convenience constructor can live in net.

Not in this PR

Migrating the dioad/net examples onto this package (the worker-daemon example, api-server, and the compile-time lifecycle.Service check for *http.Server) needs a tagged release and a go.mod bump in net, so it is a follow-up there. #1 stays open for it.

Verification

make verify passes (fmt, fix, golangci-lint, gosec, vet, go test -race, build). The tests also pass 30 times in a row under -race. They cover start order and rollback, staged and concurrent stop, stage budgets and the overall deadline, failure fan-in (including that watchers do not leak after a clean stop), drain skipped on failure, and the readiness gate, degraded checks and TTL caching.

🤖 Generated with Claude Code

patdowney and others added 3 commits November 14, 2026 21:58
Module github.com/dioad/lifecycle with the same verify gate as dioad/net
(fmt, fix, golangci-lint, gosec, vet, test -race, build). The Makefile sets
GOWORK=off so the module is verified against the versions its go.mod
declares.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SS4MAv4S7Lw7pGWvpgXpcr
App starts services in registration order and rolls back the ones that had
started when a service fails; stops them in stages, each with an optional
budget, concurrently within a stage, all inside one stop timeout; fans the
failures of services that implement Failer into one channel; and drains
before it stops, unless a failure caused the stop.

Readiness is a health source with a start gate, named checks cached for a
TTL, a degraded state that keeps the process ready, and a drain. It has the
Ready method dioad/net's HTTP server looks for, without importing it.

Service uses Shutdown rather than Stop so that dioad/net's http.Server is a
Service with no adapter. Failed, Live and Ready are optional.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SS4MAv4S7Lw7pGWvpgXpcr
@patdowney
patdowney merged commit e3a8da0 into main Nov 14, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant