feat(core): initial implementation — launcher, logz, xerrors, valid
Introduces `code.nochebuena.dev/einherjar/core` — the foundational implementation module of the Einherjar framework. Provides four sub-packages that together cover every service's baseline needs: lifecycle management, structured logging, typed errors, and struct validation. - launcher: Launcher interface — three-phase managed lifecycle (OnInit → BeforeStart hooks → OnStart → OS signal wait → OnStop in reverse). Accepts lifecycle.Component and logging.Logger from contracts. Prints an ASCII art banner at startup (EINHERJAR_BANNER=off to suppress). Banner includes core version via runtime/debug.ReadBuildInfo() and a loaded-module list for every registered component that implements observability.Identifiable. Config struct with EINHERJAR_COMPONENT_STOP_TIMEOUT env tag (caarlos0/env syntax, default 15s). - logz: Logger implementation backed by log/slog. Returns contracts/logging.Logger. Detects errs.CodedError and errs.ContextualError (from contracts/errs) to enrich log records automatically — replaces the private duck-typed bridge from micro-lib. Context helpers: WithRequestID, WithField, WithFields, GetRequestID. Config struct with EINHERJAR_LOG_LEVEL (default INFO) and EINHERJAR_LOG_JSON (default false) env tags (caarlos0/env syntax); programmatic-only fields StaticArgs and Writer carry no tags. - xerrors: Typed error codes with context enrichment. Complete gRPC canonical set (16 codes) plus HTTP 410 ErrGone. Adds ErrOutOfRange, ErrAborted, ErrDataLoss over micro-lib. One convenience constructor per code. *Err declares compile-time satisfaction of errs.CodedError and errs.ContextualError. - valid: Struct validation wrapping go-playground/validator/v10. Validator interface + MessageProvider interface with full built-in tag coverage (~150 tags) in both DefaultMessages (English) and SpanishMessages (Spanish). Backend fully hidden; returns *xerrors.Err with ErrInvalidInput or ErrInternal. FieldLevel interface abstracts the backend's field-level access for custom validators. WithCustomValidator registers custom validation tags at construction time; OverrideProvider chains a tag→handler map with a fallback MessageProvider for custom tag messages without re-implementing built-ins. Compliance test enforces CT-6 (at most one exported TypeSpec per file via AST) and verifies behavioural correctness of all four sub-packages, including custom validator registration and OverrideProvider composition. Compile-time var _ assertions prove interface satisfaction. docs: ADR-001 (core module composition), ADR-002 (logz contracts/errs adoption), ADR-003 (Config naming convention and caarlos0/env tag standard)
This commit is contained in:
162
launcher/launcher.go
Normal file
162
launcher/launcher.go
Normal file
@@ -0,0 +1,162 @@
|
||||
package launcher
|
||||
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
"os/signal"
|
||||
"sync"
|
||||
"syscall"
|
||||
"time"
|
||||
|
||||
"code.nochebuena.dev/einherjar/contracts/lifecycle"
|
||||
"code.nochebuena.dev/einherjar/contracts/logging"
|
||||
"code.nochebuena.dev/einherjar/contracts/observability"
|
||||
)
|
||||
|
||||
// Launcher manages the application lifecycle: init → assemble → start → wait → shutdown.
|
||||
type Launcher interface {
|
||||
// Append adds one or more components. Registered in the order they are appended;
|
||||
// shutdown runs in reverse order.
|
||||
Append(components ...lifecycle.Component)
|
||||
// BeforeStart registers hooks that run after all OnInit calls and before all OnStart
|
||||
// calls. Use for dependency injection wiring.
|
||||
BeforeStart(hooks ...Hook)
|
||||
// Run executes the full application lifecycle. Blocks until an OS shutdown signal is
|
||||
// received or Shutdown is called. Returns an error if any lifecycle step fails.
|
||||
// The caller is responsible for calling os.Exit(1) when needed.
|
||||
Run() error
|
||||
// Shutdown triggers a graceful shutdown and waits for Run to return.
|
||||
// ctx controls the caller-side wait timeout — it does NOT override
|
||||
// Config.ComponentStopTimeout for individual components.
|
||||
// Safe to call multiple times (idempotent).
|
||||
Shutdown(ctx context.Context) error
|
||||
}
|
||||
|
||||
var _ Launcher = (*launcher)(nil)
|
||||
|
||||
// New returns a Launcher configured by opts. The zero value of Config is valid.
|
||||
func New(logger logging.Logger, opts ...Config) Launcher {
|
||||
o := Config{ComponentStopTimeout: defaultComponentStopTimeout}
|
||||
if len(opts) > 0 {
|
||||
if opts[0].ComponentStopTimeout > 0 {
|
||||
o.ComponentStopTimeout = opts[0].ComponentStopTimeout
|
||||
}
|
||||
}
|
||||
return &launcher{
|
||||
logger: logger,
|
||||
opts: o,
|
||||
components: make([]lifecycle.Component, 0),
|
||||
shutdownCh: make(chan struct{}),
|
||||
doneCh: make(chan struct{}),
|
||||
}
|
||||
}
|
||||
|
||||
type launcher struct {
|
||||
logger logging.Logger
|
||||
opts Config
|
||||
components []lifecycle.Component
|
||||
beforeStart []Hook
|
||||
shutdownCh chan struct{}
|
||||
doneCh chan struct{}
|
||||
shutdownOnce sync.Once
|
||||
}
|
||||
|
||||
func (l *launcher) Append(components ...lifecycle.Component) {
|
||||
l.components = append(l.components, components...)
|
||||
}
|
||||
|
||||
func (l *launcher) BeforeStart(hooks ...Hook) {
|
||||
l.beforeStart = append(l.beforeStart, hooks...)
|
||||
}
|
||||
|
||||
// Run executes the full application lifecycle:
|
||||
// 1. Prints the startup banner (unless EINHERJAR_BANNER=off).
|
||||
// 2. OnInit for all components (in registration order).
|
||||
// 3. BeforeStart hooks (in registration order).
|
||||
// 4. OnStart for all components (in registration order).
|
||||
// 5. Blocks until an OS signal or Shutdown() is called.
|
||||
// 6. stopAll — OnStop for all components (in reverse order).
|
||||
func (l *launcher) Run() error {
|
||||
var ids []observability.Identifiable
|
||||
for _, c := range l.components {
|
||||
if id, ok := c.(observability.Identifiable); ok {
|
||||
ids = append(ids, id)
|
||||
}
|
||||
}
|
||||
printBanner(ids)
|
||||
defer close(l.doneCh)
|
||||
|
||||
l.logger.Info("launcher: starting init phase (OnInit)")
|
||||
for _, c := range l.components {
|
||||
if err := c.OnInit(); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
l.logger.Info("launcher: running assembly hooks (BeforeStart)")
|
||||
for _, hook := range l.beforeStart {
|
||||
if err := hook(); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
l.logger.Info("launcher: starting components (OnStart)")
|
||||
for _, c := range l.components {
|
||||
if err := c.OnStart(); err != nil {
|
||||
l.logger.Error("launcher: OnStart failed, triggering shutdown", err)
|
||||
l.stopAll()
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
l.logger.Info("launcher: application ready")
|
||||
|
||||
quit := make(chan os.Signal, 1)
|
||||
signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
|
||||
defer signal.Stop(quit)
|
||||
|
||||
select {
|
||||
case s := <-quit:
|
||||
l.logger.Info("launcher: termination signal received", "signal", s.String())
|
||||
case <-l.shutdownCh:
|
||||
l.logger.Info("launcher: programmatic shutdown requested")
|
||||
}
|
||||
|
||||
l.stopAll()
|
||||
return nil
|
||||
}
|
||||
|
||||
func (l *launcher) Shutdown(ctx context.Context) error {
|
||||
l.shutdownOnce.Do(func() {
|
||||
close(l.shutdownCh)
|
||||
})
|
||||
|
||||
select {
|
||||
case <-l.doneCh:
|
||||
return nil
|
||||
case <-ctx.Done():
|
||||
return ctx.Err()
|
||||
}
|
||||
}
|
||||
|
||||
func (l *launcher) stopAll() {
|
||||
l.logger.Info("launcher: stopping all components")
|
||||
|
||||
for i := len(l.components) - 1; i >= 0; i-- {
|
||||
done := make(chan struct{})
|
||||
go func(c lifecycle.Component) {
|
||||
if err := c.OnStop(); err != nil {
|
||||
l.logger.Error("launcher: error during OnStop", err)
|
||||
}
|
||||
close(done)
|
||||
}(l.components[i])
|
||||
|
||||
select {
|
||||
case <-done:
|
||||
case <-time.After(l.opts.ComponentStopTimeout):
|
||||
l.logger.Error("launcher: component OnStop timed out", nil)
|
||||
}
|
||||
}
|
||||
|
||||
l.logger.Info("launcher: all components stopped")
|
||||
}
|
||||
Reference in New Issue
Block a user