268 lines
6.8 KiB
Go
268 lines
6.8 KiB
Go
// Package lifecycle is the registration and start/health/stop machinery
|
|
// shared by engine families such as curators and memory engines.
|
|
package lifecycle
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"log/slog"
|
|
"maps"
|
|
"reflect"
|
|
"slices"
|
|
"sync"
|
|
)
|
|
|
|
// HealthStatus is an engine's point-in-time health.
|
|
type HealthStatus string
|
|
|
|
const (
|
|
HealthHealthy HealthStatus = "healthy"
|
|
HealthDegraded HealthStatus = "degraded"
|
|
HealthUnhealthy HealthStatus = "unhealthy"
|
|
)
|
|
|
|
// Health is a point-in-time engine health report.
|
|
type Health struct {
|
|
Status HealthStatus
|
|
Message string
|
|
}
|
|
|
|
// Registry errors.
|
|
var (
|
|
// ErrDuplicate is returned when an engine name is already registered.
|
|
ErrDuplicate = errors.New("duplicate engine")
|
|
// ErrStarted is returned when a running registry is started again.
|
|
ErrStarted = errors.New("registry already started")
|
|
)
|
|
|
|
// Engine is a named, host-bound component with a lifecycle.
|
|
type Engine[H any] interface {
|
|
Name() string
|
|
Bind(host H)
|
|
Start(ctx context.Context) error
|
|
Health(ctx context.Context) Health
|
|
Stop(ctx context.Context) error
|
|
}
|
|
|
|
type state uint8
|
|
|
|
const (
|
|
stateIdle state = iota
|
|
stateRunning
|
|
stateStopped
|
|
)
|
|
|
|
type status struct {
|
|
started bool
|
|
startErr error
|
|
}
|
|
|
|
// Registry owns registration and lifecycle for one engine family. An
|
|
// engine's failure, including a panic, affects only that engine.
|
|
type Registry[E Engine[H], H any] struct {
|
|
kind string
|
|
log *slog.Logger
|
|
mu sync.Mutex
|
|
engines map[string]E
|
|
status map[string]status
|
|
order []string
|
|
state state
|
|
}
|
|
|
|
// New builds an empty registry. kind prefixes errors and log lines; a nil
|
|
// log disables lifecycle logging.
|
|
func New[E Engine[H], H any](kind string, log *slog.Logger) *Registry[E, H] {
|
|
return &Registry[E, H]{
|
|
kind: kind,
|
|
log: log,
|
|
engines: make(map[string]E),
|
|
status: make(map[string]status),
|
|
}
|
|
}
|
|
|
|
// IsNil reports whether v is nil or an interface holding a nil value.
|
|
func IsNil(v any) bool {
|
|
rv := reflect.ValueOf(v)
|
|
switch rv.Kind() {
|
|
case reflect.Invalid:
|
|
return true
|
|
case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
|
|
return rv.IsNil()
|
|
}
|
|
return false
|
|
}
|
|
|
|
// Add binds e to host and registers it, unstarted. A panicking Bind refuses
|
|
// the engine. Adding to a running registry is allowed; StartOne starts it.
|
|
func (r *Registry[E, H]) Add(e E, host H) error {
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
name := e.Name()
|
|
if _, dup := r.engines[name]; dup {
|
|
return fmt.Errorf("%w: %s %s", ErrDuplicate, r.kind, name)
|
|
}
|
|
if err := guard(func() error { e.Bind(host); return nil }); err != nil {
|
|
return fmt.Errorf("%s %s: bind %w", r.kind, name, err)
|
|
}
|
|
r.engines[name] = e
|
|
r.order = append(r.order, name)
|
|
return nil
|
|
}
|
|
|
|
// StartOne starts the named engine when the registry is running and the
|
|
// engine has not started; otherwise it does nothing. A failed Start marks the
|
|
// engine unhealthy, as Start does.
|
|
func (r *Registry[E, H]) StartOne(ctx context.Context, name string) error {
|
|
r.mu.Lock()
|
|
e, ok := r.engines[name]
|
|
if !ok || r.state != stateRunning || r.status[name].started {
|
|
r.mu.Unlock()
|
|
return nil
|
|
}
|
|
r.mu.Unlock()
|
|
|
|
err := guard(func() error { return e.Start(ctx) })
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
if err != nil {
|
|
r.status[name] = status{startErr: err}
|
|
return r.fail(name, "start", err)
|
|
}
|
|
r.status[name] = status{started: true}
|
|
return nil
|
|
}
|
|
|
|
// Unregister removes the named engine, stopping it first when it started.
|
|
// The engine is removed even when its Stop fails; the failure is returned.
|
|
func (r *Registry[E, H]) Unregister(ctx context.Context, name string) error {
|
|
r.mu.Lock()
|
|
e, ok := r.engines[name]
|
|
st := r.status[name]
|
|
delete(r.engines, name)
|
|
delete(r.status, name)
|
|
r.order = slices.DeleteFunc(r.order, func(n string) bool { return n == name })
|
|
r.mu.Unlock()
|
|
if !ok || !st.started {
|
|
return nil
|
|
}
|
|
if err := guard(func() error { return e.Stop(ctx) }); err != nil {
|
|
return r.fail(name, "stop", err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Get returns the registered engine by name.
|
|
func (r *Registry[E, H]) Get(name string) (E, bool) {
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
e, ok := r.engines[name]
|
|
return e, ok
|
|
}
|
|
|
|
// Names returns the registered engine names in sorted order.
|
|
func (r *Registry[E, H]) Names() []string {
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
return slices.Sorted(maps.Keys(r.engines))
|
|
}
|
|
|
|
// Start starts every engine in registration order. An engine whose Start
|
|
// fails is marked unhealthy and skipped; the rest start regardless, and all
|
|
// failures are joined into the returned error. A stopped registry may be
|
|
// started again.
|
|
func (r *Registry[E, H]) Start(ctx context.Context) error {
|
|
r.mu.Lock()
|
|
if r.state == stateRunning {
|
|
r.mu.Unlock()
|
|
return fmt.Errorf("%s: %w", r.kind, ErrStarted)
|
|
}
|
|
r.state = stateRunning
|
|
order := slices.Clone(r.order)
|
|
r.mu.Unlock()
|
|
|
|
var errs []error
|
|
for _, name := range order {
|
|
e, _ := r.Get(name)
|
|
err := guard(func() error { return e.Start(ctx) })
|
|
r.mu.Lock()
|
|
if err != nil {
|
|
r.status[name] = status{startErr: err}
|
|
errs = append(errs, r.fail(name, "start", err))
|
|
} else {
|
|
r.status[name] = status{started: true}
|
|
}
|
|
r.mu.Unlock()
|
|
}
|
|
return errors.Join(errs...)
|
|
}
|
|
|
|
// Health reports every engine's health. An engine whose Start failed, or
|
|
// whose Health panics, is reported unhealthy.
|
|
func (r *Registry[E, H]) Health(ctx context.Context) map[string]Health {
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
out := make(map[string]Health, len(r.engines))
|
|
for name, e := range r.engines {
|
|
if st := r.status[name]; st.startErr != nil {
|
|
out[name] = Health{Status: HealthUnhealthy, Message: st.startErr.Error()}
|
|
continue
|
|
}
|
|
out[name] = healthSafely(ctx, e)
|
|
}
|
|
return out
|
|
}
|
|
|
|
// Stop stops started engines in reverse order, bounded by ctx, and joins
|
|
// their errors.
|
|
func (r *Registry[E, H]) Stop(ctx context.Context) error {
|
|
r.mu.Lock()
|
|
if r.state != stateRunning {
|
|
r.mu.Unlock()
|
|
return nil
|
|
}
|
|
r.state = stateStopped
|
|
order := slices.Clone(r.order)
|
|
r.mu.Unlock()
|
|
|
|
var errs []error
|
|
for _, name := range slices.Backward(order) {
|
|
r.mu.Lock()
|
|
e, st := r.engines[name], r.status[name]
|
|
r.mu.Unlock()
|
|
if !st.started {
|
|
continue
|
|
}
|
|
if err := guard(func() error { return e.Stop(ctx) }); err != nil {
|
|
errs = append(errs, r.fail(name, "stop", err))
|
|
}
|
|
}
|
|
return errors.Join(errs...)
|
|
}
|
|
|
|
func (r *Registry[E, H]) fail(name, phase string, err error) error {
|
|
if r.log != nil {
|
|
r.log.Error(r.kind+" lifecycle failed", "name", name, "phase", phase, "err", err)
|
|
}
|
|
return fmt.Errorf("%s %s: %w", r.kind, name, err)
|
|
}
|
|
|
|
// guard runs fn, converting a panic into an error.
|
|
func guard(fn func() error) (err error) {
|
|
defer func() {
|
|
if p := recover(); p != nil {
|
|
err = fmt.Errorf("panic: %v", p)
|
|
}
|
|
}()
|
|
return fn()
|
|
}
|
|
|
|
func healthSafely[E Engine[H], H any](ctx context.Context, e E) (h Health) {
|
|
defer func() {
|
|
if p := recover(); p != nil {
|
|
h = Health{Status: HealthUnhealthy, Message: fmt.Sprintf("health panic: %v", p)}
|
|
}
|
|
}()
|
|
return e.Health(ctx)
|
|
}
|