feat: release v0.27 unified HTTP limits and safe request shutdown

examples/httpSafety/README.md

@@ -0,0 +1,15 @@
+# HTTP 限额与停机
+
+从仓库根目录运行 `go run ./examples/httpSafety`，可用 `-addr 127.0.0.1:18080` 指定端口。仅使用本机 HTTP 和模拟收尾，不连接数据库或其他服务。
+
+上传验证：
+
+```sh
+dd if=/dev/zero bs=1048576 count=9 2>/dev/null | curl --data-binary @- http://127.0.0.1:8080/upload
+```
+
+普通路由默认 1 MiB，上传路由允许 16 MiB，服务硬上限 20 MiB；以上请求返回已读取的 9437184 字节。将上传路由改为 21 MiB 后，启动会报告该路由与服务硬上限冲突。实际文件上传须额外预留 multipart 字段/边界开销，并配置文件大小限制。
+
+停机验证：另一个终端执行 `curl http://127.0.0.1:8080/work`，随后在服务终端按 Ctrl-C。先等待 1s 排空，再取消请求，处理器模拟 100ms 收尾；日志中先出现 `request cleanup completed`，再出现资源关闭记录。因为用尽排空预算，本次退出仍返回超时错误。
+
+若处理器不在取消收尾窗口内退出，App 和 `deps.Finish(runErr)` 返回 `lifecycle.ErrResourcesRetained` 并跳过资源关闭。真实项目拥有的日志也必须在该错误下保留，生成入口已处理。进程应非零退出；库不自行退出进程，也不强杀 goroutine。

examples/httpSafety/main.go

@@ -0,0 +1,62 @@
+// This example uses only local HTTP and simulated work; no external services.
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"io"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+)
+
+func main() {
+	address := flag.String("addr", "127.0.0.1:8080", "local listen address")
+	flag.Parse()
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	if err := run(ctx, *address); err != nil {
+		log.Print(err)
+		os.Exit(1)
+	}
+}
+
+func run(ctx context.Context, address string) (runErr error) {
+	deps := lifecycle.NewRuntime(ctx)
+	deps.OnClose(func() error { log.Print("shared resource closed after requests completed"); return nil })
+	defer func() { runErr = deps.Finish(runErr) }()
+	app := omni.New(omni.WithHTTPConfig(omni.HTTPConfig{
+		DefaultMaxBodyBytes:   1 << 20,
+		MaxBodyBytes:          20 << 20,
+		ShutdownCancelTimeout: time.Second,
+	}), omni.WithShutdownTimeout(time.Second))
+	defer func() { runErr = errors.Join(runErr, app.Close()) }()
+	app.HandleWithBodyLimit("POST", "/upload", 16<<20, nil, func(c *omni.Context) error {
+		n, err := io.Copy(io.Discard, c.Request().Body)
+		if err != nil {
+			return err
+		}
+		return c.OK(map[string]int64{"bytes": n})
+	})
+	app.GET("/work", func(c *omni.Context) error {
+		log.Print("request accepted")
+		select {
+		case <-time.After(10 * time.Second):
+			return c.OK("finished")
+		case <-c.Context().Done():
+			// Simulate bounded rollback/cleanup after cancellation. Dependencies
+			// remain available until this handler and its defers have returned.
+			time.Sleep(100 * time.Millisecond)
+			log.Print("request cleanup completed")
+			return c.Context().Err()
+		}
+	})
+	log.Printf("listening on %s; POST /upload or GET /work, then Ctrl-C", address)
+	return app.RunContext(deps.Context(), address)
+}

examples/managedService/.goOmni/apiManifest.json

@@ -22,7 +22,7 @@
     "internal/svc/runtimeGen.go": "29f6afb6614881935099c1845ecb3f7902ee773caa077940f566cb8dfdbcdbb1",
     "internal/types/dtoManagedd28645a2af1cGen.go": "7586e86fa5d67051283178cc578c890f6c02fd2d5c383170a71a39c2e77ce344",
     "internal/types/typesGen.go": "372d67f23a313b3e77d2a3b7a236315db9721bc63350bf1f71db1293e57570d1",
-    "main.go": "10cb6a84b2eb1b68dc10c2dca949c9dd7c68a9f78a8e6d8f56ce9336d4b2d125"
+    "main.go": "e1cdd80f8ee090f1391cdfa799762c99b10d4e09715e9d4faefb2cb0291f1c05"
   },
   "contract": {
     "routes": {

examples/managedService/go.mod

@@ -2,7 +2,7 @@ module example.com/managed
 
 go 1.22.0
 
-require git.yuntuo.hk/k2safe/go-omni v0.26.0-preview
+require git.yuntuo.hk/k2safe/go-omni v0.27.0-preview
 
 require (
 	github.com/gabriel-vasile/mimetype v1.4.3 // indirect

examples/managedService/main.go

@@ -41,7 +41,7 @@ func run(ctx context.Context, path string) (runErr error) {
 	if err != nil {
 		return err
 	}
-	// Unjoined background work may still log. The owning process exits on this
+	// Unjoined HTTP or 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) {
@@ -52,8 +52,8 @@ func run(ctx context.Context, path string) (runErr error) {
 	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.
+	// Finish propagates incomplete HTTP draining: stop background work but retain
+	// shared dependencies when any handler is still running. Otherwise close once.
 	defer func() { runErr = deps.Finish(runErr) }()
 	app, err := handler.NewApp(deps)
 	if err != nil {

examples/userService/go.mod

@@ -3,7 +3,7 @@ module example.com/userService
 go 1.22.0
 
 require (
-	git.yuntuo.hk/k2safe/go-omni v0.26.0-preview
+	git.yuntuo.hk/k2safe/go-omni v0.27.0-preview
 	github.com/go-sql-driver/mysql v1.9.3
 )