feat: add generic phased background shutdown to managed services

cmd/go-omni/apigen/templates.go

@@ -13,6 +13,7 @@ import (
  "os/signal"
  "syscall"
  "git.yuntuo.hk/k2safe/go-omni/logx"
+ "git.yuntuo.hk/k2safe/go-omni/lifecycle"
  "MODULE/internal/config"
  "MODULE/internal/handler"
  "MODULE/internal/svc"
@@ -27,7 +28,9 @@ func main(){
 func run(ctx context.Context,path string)(runErr error){
  cfg,err:=config.Load(path);if err!=nil{return err}
  logger,err:=logx.New(cfg.Server.Log);if err!=nil{return err}
- defer func(){runErr=errors.Join(runErr,logger.Close())}()
+ // Unjoined background work may still log. The owning process exits on this
+ // error; do not close its borrowed logger before that work has finished.
+ defer func(){if !errors.Is(runErr,lifecycle.ErrResourcesRetained){runErr=errors.Join(runErr,logger.Close())}}()
  deps,err:=svc.New(ctx,logger,cfg);if err!=nil{return err}
  // RunContext drains HTTP requests before returning. This scope owns dependencies
  // and closes them exactly once, before closing the borrowed logger.
@@ -182,7 +185,16 @@ then immediately register each cleanup with OnClose. A later initialization fail
 runs registered cleanups in reverse order. Close is idempotent. GlobalMiddleware
 provides global hooks; Middlewares supplies named API hooks. AppOptions is evaluated
 once before route registration; logging is configured earlier through Config.
-The generated main runs HTTP draining before closing svc resources, then the logger.
+The generated main runs HTTP draining, all OnStop hooks, all OnDrain hooks, resource
+OnClose callbacks, then logger close. Stop/drain hooks within a phase run concurrently;
+combine components with ordering dependencies into one pair. Pair OnStop/OnDrain
+with the same name. OnDrain returns nil only after final work and acknowledgements
+have finished. Use WorkContext for accepted background work; Context is an early
+shutdown notification. server.lifecycle configures stopTimeout (5s), drainTimeout
+(10s), and cancelTimeout (5s grace per timed-out phase). Zero uses defaults.
+Timeout/failure cancels WorkContext. If hooks cannot prove completion, resources
+and the borrowed logger are retained and the generated process exits unsuccessfully.
+Errors retain their causes. No automatic retry of close or force killing of goroutines.
 Do not close borrowed resources or attach duplicate cleanup hooks to App. The startup
 context cancels on signals; long-lived clients/workers that requests depend on need
 their own lifetime, canceled by OnClose after HTTP draining.