go-core

go-core

go-core is the Core SDK for Standards Lab's Go Elemental standard. It provides layered configuration, a dependency graph and the process lifecycle that runs it, a reactor that joins a source of occurrences to a handler, the CloudEvents envelope a domain raises its events in, and logging.

github.com/standards-lab/go-core is a single Go module with the process-level packages every program in the standard builds on.

Standard

go-core is the Core SDK of Go Elemental, the minimal-dependency Go standard. This README and each package's doc.go document the repository; the standard's principles it enhances are stated below. It enhances the standard's dependency line: where Go Elemental admits packages as idiomatic and stable as the standard library, this repository depends on the standard library alone.

Packages

• config — loads configuration in layers: a base file, an environment overlay, and secrets.
• event — the CloudEvents 1.0 envelope and its binary-content-mode codec, and the types a domain raises its events with: an EventKind declared with Define raises into a Queue, and a Recorder emits the queue through a Sink into the command's own transaction, only when the command succeeds. Permanent marks a handler's error that redelivery cannot fix.
• graph — a typed dependency graph: nodes described inertly, each a name and a constructor, and a Build that constructs what the roots reach into a System of computed layers.
• lifecycle — runs a built graph System: starts its layers in order, tracks and reports readiness, watches for runtime failures, and shuts the layers down in reverse within a timeout. A value takes part through the interfaces it implements. Exec is the one-shot form a CLI command uses; Run is the long-running form a service uses.
• logging — builds an *slog.Logger from a configuration that config loads.
• process — the parts of a binary's main sequence that run before the program's own infrastructure exists: the signal-derived root context, pre-logger failure reporting, and the exit-code convention.
• process/processtest — the integration toolkit: it builds a program once per suite run and runs it as a subprocess. It then waits on what a client observes, interrupts the process and reads its exit code, and relays a backing service's connection so a test can sever it. Run runs the program once and returns its stdout, stderr, and exit code.
• reactor — joins one source of occurrences to one function for the process lifetime: a lifecycle component that drains the handling in flight at shutdown and cancels it once its CancelAfter period passes. Every delivers on an interval, and Wake also delivers on each Waker.Nudge a producer calls. Gate pauses background work while an operation runs exclusively.

Development

Tasks run through mise:

mise run check      # build, vet, format, fix, tidy, test, and lint; writes nothing
mise run currency   # report requirements, Go, tools, and actions behind their latest
mise run upgrade    # upgrade the go directive, requirements, and tools to their latest

License

Apache License 2.0.