feat: add dependency shutdown and configurable service endpoints

lifecycle/controller.go

@@ -0,0 +1,67 @@
+// Package lifecycle coordinates service shutdown without owning project resources.
+package lifecycle
+
+import (
+	"context"
+	"errors"
+	"sync"
+)
+
+// Controller connects dependency failures to the server's graceful shutdown.
+// Construct it with New. RequestShutdown never waits for draining or cleanup.
+type Controller struct {
+	ctx    context.Context
+	cancel context.CancelCauseFunc
+	mu     sync.Mutex
+	cause  error
+}
+
+func New(parent context.Context) *Controller {
+	if parent == nil {
+		parent = context.Background()
+	}
+	ctx, cancel := context.WithCancelCause(parent)
+	return &Controller{ctx: ctx, cancel: cancel}
+}
+
+func (c *Controller) Context() context.Context { return c.ctx }
+
+// RequestShutdown asks the service to stop. nil is a normal stop; a non-nil
+// error is fatal. The first fatal error is retained even if a normal signal
+// already began draining. Concurrent and repeated calls are safe.
+func (c *Controller) RequestShutdown(err error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.cause == nil && err != nil {
+		c.cause = err
+	}
+	c.cancel(err)
+}
+
+// Err is read after resources have stopped reporting failures. It returns the
+// first dependency failure, or an abnormal parent cancellation cause.
+func (c *Controller) Err() error {
+	if c == nil {
+		return nil
+	}
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.cause != nil {
+		return c.cause
+	}
+	return Cause(c.ctx)
+}
+
+// Cause treats cancellation-compatible errors (including signal causes in
+// newer Go versions) as normal stops. Deadlines and other causes are failures.
+// Controller.Err additionally retains every explicitly reported non-nil error.
+func Cause(ctx context.Context) error {
+	if ctx == nil {
+		return nil
+	}
+	cause := context.Cause(ctx)
+	if errors.Is(cause, context.Canceled) {
+		return nil
+	}
+	return cause
+}