corestack go
Shared Go building blocks. Includes docs, a checker for architecture decision records (ADRs) and implementation plans, and lifecycle, a service and worker coordinator.
docs
Install:
go install go.auvem.com/corestack/cmd/docs@latest
Use, from a repository root:
docs new adr "Use Example Queue for background jobs" # creates docs/adr/<id>.md
docs new plan "Adopt Example Queue" # creates docs/plans/<id>.md
docs check [--root DIR] # prints path:line: message; exit 1 on problems
The format is specified in docs/docs-format.md; that document is the complete rule set. Exit status is 0 when every record is valid, 1 when problems are reported and 2 for usage errors.
lifecycle
go.auvem.com/corestack/lifecycle sets up modules in registration order, runs
services concurrently, and tears down successful setups in reverse order.
Construct an App with a required *slog.Logger, register Module callbacks,
and call Run(ctx) once. See the two-service example.
Launch background work with app.Go(ctx, name, fn) using the callback's lifecycle
context or a descendant, and handle admission errors. Run waits for every service
and admitted worker; raw goroutines remain your responsibility. First failure or
an injected signal cancels work before teardown. One shared shutdown deadline
(default 30 seconds) covers hooks and callback completion; a second signal
abandons shutdown. Callbacks must cooperate: abandonment cannot kill goroutines,
and the caller owns process exit and any unreleased resources.
During App-initiated shutdown, callback errors containing only the callback's
context cancellation are omitted. Mixed cancellation and independent failures
are retained intact to preserve wrapper types, identity and custom matching;
these errors may still match cancellation through errors.Is.
The caller owns signal subscription, SIGINT/SIGTERM filtering, a channel buffered for at least two signals, and subscription cleanup. Nil signals disable reception. There are no signal subscriptions, process exits, external dependencies or CLI integration in this package.
Status
No support is guaranteed. Breaking changes, including to the format rules, may happen before 1.0 and are listed in the release notes.
License
BSD-3-Clause, see LICENSE.