feat: add dependency shutdown and configurable service endpoints

lifecycle/README.md

@@ -0,0 +1,20 @@
+# lifecycle
+
+Controller 是服务退出通知入口，不管理具体数据库、租约或后台任务。生成项目已经将它接入 svc 与 main，业务在 svc 调用 `c.RequestShutdown(err)` 即可，见 [项目指南](../PROJECT.md#依赖主动申请退出)。
+
+手写服务也可组合现有 App：
+
+```go
+control := lifecycle.New(ctx)
+defer control.RequestShutdown(nil)
+
+// 在依赖的故障回调中调用，不阻塞等待排空。
+control.RequestShutdown(cause)
+
+// RunContext 会观察到已发生的退出通知，不必等监听成功才能通知。
+err := app.RunContext(control.Context())
+```
+
+实际使用时 App 和依赖通常先初始化，再由并发监控回调请求退出。资源在 HTTP 排空完成后由调用方关闭，并读取 `control.Err()` 合并清理期间报告的首个故障。通知本身不会关闭资源、执行 os.Exit 或发送操作系统信号。
+
+`RequestShutdown(nil)` 表示正常停止，非空 error 表示故障。Controller 保留首个非空故障，重复调用和并发调用安全。`Cause(ctx)` 将符合 errors.Is(err, context.Canceled) 的取消原因视为正常停止（包含新版 Go 的信号原因），保留其他取消原因和 DeadlineExceeded。显式 RequestShutdown(err) 上报的非空错误始终由 Controller.Err 保留，包括包装 context.Canceled 的错误。App.RunContext、ServeContext、RunWith 均保留这些异常原因，与网络适配器无关。

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
+}

lifecycle/controller_test.go

@@ -0,0 +1,67 @@
+package lifecycle
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+)
+
+func TestShutdownRetainsFirstFailure(t *testing.T) {
+	parent, signal := context.WithCancel(context.Background())
+	c := New(parent)
+	signal()
+	if c.Err() != nil {
+		t.Fatal("signal treated as failure")
+	}
+	first := errors.New("dependency stopped")
+	c.RequestShutdown(first)
+	var wg sync.WaitGroup
+	for i := 0; i < 100; i++ {
+		wg.Add(1)
+		go func() { defer wg.Done(); c.RequestShutdown(errors.New("later")); c.RequestShutdown(nil); _ = c.Err() }()
+	}
+	wg.Wait()
+	if !errors.Is(c.Err(), first) || c.Context().Err() == nil {
+		t.Fatal(c.Err())
+	}
+}
+
+func TestShutdownBeforeServingAndParentCauses(t *testing.T) {
+	fatal := errors.New("initialization fault")
+	c := New(nil)
+	c.RequestShutdown(fatal)
+	if c.Context().Err() == nil || !errors.Is(Cause(c.Context()), fatal) || !errors.Is(c.Err(), fatal) {
+		t.Fatal("lost early shutdown")
+	}
+	c.RequestShutdown(nil)
+	if !errors.Is(c.Err(), fatal) {
+		t.Fatal("cleanup erased failure")
+	}
+	parent, cancel := context.WithCancelCause(context.Background())
+	child := New(parent)
+	cancel(fatal)
+	if !errors.Is(child.Err(), fatal) {
+		t.Fatal("lost parent failure")
+	}
+	normal := New(nil)
+	normal.RequestShutdown(nil)
+	if normal.Err() != nil {
+		t.Fatal(normal.Err())
+	}
+}
+
+func TestCancellationCompatibleCauseAndExplicitFailure(t *testing.T) {
+	cause := fmt.Errorf("stop: %w", context.Canceled)
+	ctx, cancel := context.WithCancelCause(context.Background())
+	cancel(cause)
+	if Cause(ctx) != nil {
+		t.Fatal("cancellation-compatible stop treated as a fault")
+	}
+	c := New(nil)
+	c.RequestShutdown(cause)
+	if !errors.Is(c.Err(), cause) {
+		t.Fatal("explicit dependency failure suppressed")
+	}
+}