corestack go
Shared Go building blocks. Includes docs, a checker for architecture decision records (ADRs) and implementation plans; page, Bob keyset pagination; 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.
page
page provides transport-neutral Bob keyset pagination with typed
items, mixed-direction sorts, opaque typed cursors, and a separate opt-in count.
Pass a trusted Sort and a typed row key in the same column order; sort columns
must be non-null and end in a unique column. See the runnable example
and cursor decision.
SQLite runs in-process in the normal test suite (requires CGO). PostgreSQL runs in
CI; locally set PAGE_POSTGRES_DSN to an isolated test database to run the same
flow. Set PAGE_REQUIRE_POSTGRES=1 to fail rather than skip when the DSN is absent.
MySQL mod composition compiles; its runtime behavior has not been verified.
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.