end
f0439000cb
Add embedded SQL and provider-local Go migrations with slog logging and Postgres session locking, returning Goose's Provider directly. Cover timestamp and sequential versions, failure recovery, and concurrent startup with SQLite and Postgres tests. Reuse page's Postgres CI service. Document authoring conventions and the Go template compatibility gate. Closes #7 Refs #9
73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
# 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.
|
|
|
|
## migrate
|
|
|
|
[`migrate`](migrate/README.md) configures Goose providers for embedded SQL and Go
|
|
migrations, with structured logging and Postgres startup locking.
|
|
|
|
## 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.
|
|
|
|
## page
|
|
|
|
[`page`](page/page.go) 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](page/example_test.go)
|
|
and [cursor decision](docs/adr/20261027T184351001Z-preserve-typed-sort-values-in-versioned-page-cursors.md).
|
|
|
|
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](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).
|