go/README.md

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.

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.