end
e5298cff37
Add ordered setup, reverse rollback and teardown, concurrent services, and managed background workers using only the standard library. Coordinate context cancellation, injectable signals and joined errors within one configurable shutdown deadline. Include race tests, a two-service example, and the accepted lifecycle ADR. Closes #5
55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
go install go.auvem.com/corestack/cmd/docs@latest
|
|
```
|
|
|
|
Use, from a repository root:
|
|
|
|
```sh
|
|
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](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](lifecycle/example_test.go).
|
|
|
|
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](LICENSE).
|