feat: add bounded native http server

feat: remove Gin and standardize on nethttp
test: verify remote business module upgrade flow
2026-09-21 01:58:50 +08:00 · 2026-09-21 00:57:06 +08:00 · 2026-09-21 00:23:22 +08:00
36 changed files with 1387 additions and 303 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,25 @@
 # Changelog

+## v0.5.0
+
+- 新增 `transport/native` 第一版自研 HTTP/1.1 服务端，接管 TCP 监听、连接、Keep-Alive、请求解析、响应写回和优雅关闭。
+- 新增 `App.RunWith` / `omni.Runner` 启动边界；native 通过标准 `http.Handler` 接入，现有 Handler、Service 和 Repository 无需修改。
+- native 支持 `Content-Length` 请求体、请求头 / 请求体限制、读写超时和服务关闭时的请求取消；通过对象池和 `MaxConnections` / `MaxConcurrentRequests` 控制高并发内存；chunked 请求体暂返回 501。
+- `omni.New()` 默认仍使用只依赖标准库的 `transport/nethttp` 路由，native 作为显式启用的网络层预览实现。
+
+## v0.4.0
+
+- **破坏性变更**：移除 Gin 适配器及其全部依赖，`omni.New()` 默认使用只依赖标准库的 `transport/nethttp`。
+- 移除 Gin 专属的 `Config.Mode` / `WithMode` API；网络层运行模式由具体适配器或启动层自行配置。
+- 公共 `httpx.Router`、`transport/transporttest.Run` 和 `omni.NewWithRouter` 保留，自研网络层无需修改业务 Handler / Service 即可接入。
+- benchmark 改为标准库路由和完整 GoOmni 请求链，新增 `scripts/verifyPerformance.py` 作为 race、vet、build 和性能基线入口。
+- 远程业务试用、脚手架、适配器契约和 MySQL 验收全部迁移到 `v0.4.0`。
+
+## v0.3.1
+
+- 新增独立业务模块验收 `scripts/verifyBusiness.py`：从远程 `v0.2.0` 升级到 `v0.3.1`，验证无本地 replace、配置加载、结构化日志、requestId、CRUD、校验错误、业务错误和优雅退出。
+- 脚手架与各项远程验收脚本默认跟随 `v0.3.1`，新项目会固定到最新补丁版本。
+
 ## v0.3.0

 - 新增公共适配器验收套件 `transport/transporttest.Run` 和远程消费验收脚本 `scripts/verifyTransports.py`。Gin、nethttp 使用同一套路由与业务处理链测试，并通过完整用户 CRUD 与 race 验证。
@@ -10,6 +30,7 @@
 - 验证 requestId 与业务日志关联、认证授权短路、请求并发隔离、context 值与 deadline 保留，以及真实客户端取消传入 Service。
 - **升级行为调整**：Gin 不再自动重定向尾部斜杠；nethttp 不再忽略尾部斜杠，通配参数包含开头的 `/`，Any 收敛为九种标准方法。HEAD 不自动回退 GET，其他方法需显式注册。404/405 为统一纯文本响应，405 附排序后的 Allow。
 - `gin.NewWithEngine` 应用 GoOmni 路由策略；原生 Gin 扩展与 Raw 流式响应不属于可移植契约。详见 `transport/README.md`。
+- 新增业务试用验收 `scripts/verifyBusiness.py`：独立目录内固定远程版本，执行 `v0.2.0` → `v0.3.0` 升级，验证生成业务服务的配置、日志、requestId、CRUD、参数校验、错误映射和优雅退出。

 ## v0.2.0

--- a/PERFORMANCE.md
+++ b/PERFORMANCE.md
@@ -0,0 +1,20 @@
+# GoOmni 性能基线
+
+这份基线用于比较未来自研网络层，不代表生产容量承诺。测试只测进程内请求分发和 GoOmni 请求链，不包含真实 TCP、TLS、数据库或业务存储延迟。
+
+运行：
+
+```sh
+python3 scripts/verifyPerformance.py
+```
+
+本次记录环境：Go 1.25.0、darwin/arm64、Apple M2 Max；每项连续运行 3 次：
+
+```text
+BenchmarkTransportRouteDispatch/nethttp  568–671 ns/op  1344 B/op  13 allocs/op
+BenchmarkTransportApplicationRequest/nethttp  2017–2208 ns/op  3091 B/op  34 allocs/op
+```
+
+`BenchmarkTransportRouteDispatch` 只覆盖标准库路由、路径参数和 `http.Handler` 调用；`BenchmarkTransportApplicationRequest` 还包含 GoOmni Context、RequestID、统一 JSON 响应和默认中间件链。
+
+比较新网络层时，应使用相同 Go 版本、机器和 benchmark 命令，并同时运行 `-race` 全量测试。性能下降需要结合分配次数、取消传播、错误响应和业务契约结果一起判断。
--- a/README.md
+++ b/README.md
@@ -1,17 +1,19 @@
 # GoOmni

-GoOmni 是一套面向业务复用的 Go 后端基础框架。当前默认用 Gin 作为网络适配器，业务代码只依赖 GoOmni 的 transport-neutral API，后续可以替换为自研网络层。
+GoOmni 是一套面向业务复用的 Go 后端基础框架。当前默认使用只依赖标准库的网络适配器，业务代码只依赖 GoOmni 的 transport-neutral API，后续可以替换为自研网络层。

 远程 module 地址是 `git.yuntuo.hk/k2safe/go-omni`。业务项目可以直接引用指定版本：

 ```sh
-go get git.yuntuo.hk/k2safe/go-omni@v0.3.0
+go get git.yuntuo.hk/k2safe/go-omni@v0.5.0
 ```

+`v0.4.0` 移除了 Gin 和 Gin 专属的 `WithMode` 配置；`omni.New()` 直接使用标准库路由，已有业务 Handler / Service 无需修改。
+
 创建新业务项目：

 ```sh
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.3.0
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.5.0
 go-omni new --module example.com/billing ./billing
 cd billing
 go mod tidy
@@ -40,7 +42,8 @@ go-omni/
 ├── validate/     # 参数校验
 ├── auth/         # 认证和权限接口
 ├── database/     # database/sql 生命周期和事务
-├── transport/gin/ # Gin 网络适配器，可替换
+├── transport/nethttp/ # 标准库网络适配器
+├── transport/native/  # 自研 HTTP/1.1 服务端预览
 ├── examples/     # 示例项目
 └── cmd/          # go-omni 项目脚手架
 ```
@@ -80,7 +83,7 @@ func main() {
 return omni.NotFound("USER_NOT_FOUND", "user was not found")
 ```

-默认 Gin 适配器位于 `transport/gin`。业务层不需要导入 Gin；如果后续实现自己的网络层，只需要实现 `httpx.Router` / `httpx.RouterGroup`，然后通过 `omni.NewWithRouter` 启动应用：
+默认网络适配器位于 `transport/nethttp`。业务层不需要导入具体网络库；如果后续实现自己的网络层，只需要实现 `httpx.Router` / `httpx.RouterGroup`，然后通过 `omni.NewWithRouter` 启动应用：

 ```go
 application := omni.NewWithRouter(myRouter)
@@ -88,11 +91,39 @@ application := omni.NewWithRouter(myRouter)

 仓库还提供了使用标准库路由的 `transport/nethttp` 参考实现。两种适配器已通过同一套路由、业务处理链和取消传播测试，完整用户 CRUD 复用同一份 Handler / Service。

-自研适配器可以直接运行 `transport/transporttest.Run` 验收。具体规则、v0.3.0 的斜杠 / Any / 405 行为调整，以及自研网络内核与当前 HTTP 接口的边界，见 [适配层契约](transport/README.md)。
+自研适配器可以直接运行 `transport/transporttest.Run` 验收。具体规则、v0.4.0 的斜杠 / Any / 405 行为调整，以及自研网络内核与当前 HTTP 接口的边界，见 [适配层契约](transport/README.md)。

-`app.Engine()` 现在返回标准 `http.Handler`，`ctx.Raw()` 返回适配器提供的 `http.ResponseWriter`，避免业务 API 锁定 Gin 类型。
+`app.Engine()` 返回标准 `http.Handler`，`ctx.Raw()` 返回适配器提供的 `http.ResponseWriter`，业务 API 不锁定具体网络实现。

-业务代码可以直接使用 `git.yuntuo.hk/k2safe/go-omni/logx` 打结构化日志，不需要依赖 Gin：
+需要试用第一版自研网络层时，业务注册代码无需改变，只替换启动器：
+
+```go
+import (
+	"context"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	"git.yuntuo.hk/k2safe/go-omni/transport/native"
+)
+
+ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+defer cancel()
+
+app := omni.New()
+app.GET("/health", func(ctx *omni.Context) error {
+	return ctx.OK(map[string]string{"status": "ok"})
+})
+if err := app.RunWith(ctx, native.New(nil), ":8080"); err != nil {
+	log.Fatal(err)
+}
+```
+
+`transport/native` 当前支持 HTTP/1.1、Keep-Alive、`Content-Length` 请求体、读写超时和优雅关闭；chunked 请求体暂返回 501。它会复用连接状态和响应对象，并可通过 `MaxConnections`、`MaxConcurrentRequests` 限制内存峰值。它仍通过标准 HTTP 请求/响应接口连接业务层，适合在现有 Handler / Service 上做网络层验证。
+
+业务代码可以直接使用 `git.yuntuo.hk/k2safe/go-omni/logx` 打结构化日志，不需要依赖具体网络库：

 ```go
 func (s *UserService) Create(ctx *httpx.Context) error {
@@ -166,6 +197,16 @@ userService := service.NewUsers(services)

 [`examples/reference`](examples/reference/README.md) 提供按 Handler / Service / Repository / Model 分层的用户 CRUD 示例。默认使用并发安全的内存存储，支持分页、邮箱唯一校验、结构化请求日志和统一错误，无需配置数据库。

+从远程版本生成并升级一个独立业务模块，可运行：
+
+```sh
+python3 scripts/verifyBusiness.py --version v0.5.0
+```
+
+该验收会在临时目录中先固定 `v0.2.0`，再升级到 `v0.5.0`，检查无本地 replace、配置加载、结构化日志、requestId、CRUD、校验错误、业务错误和优雅退出。
+
+标准库路由和完整 GoOmni 请求链的可重复性能基线见 [PERFORMANCE.md](PERFORMANCE.md)，运行 `python3 scripts/verifyPerformance.py` 可重新采样。
+
 在框架根目录运行：

 ```sh
@@ -174,7 +215,7 @@ go run ./examples/reference

 默认地址为 `http://127.0.0.1:8080`。示例文档提供完整的 curl 操作流程。数据只保存在内存中，重启后清空。

-框架的 `App` 也实现了标准 `http.Handler`，可以直接用于 `http.Server` 和 `httptest.NewServer`；业务路由可通过 `*omni.RouterGroup` 注册，无需导入 Gin。
+框架的 `App` 也实现了标准 `http.Handler`，可以直接用于 `http.Server` 和 `httptest.NewServer`；业务路由可通过 `*omni.RouterGroup` 注册，无需导入网络库。

 ## 当前边界

--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -18,19 +18,29 @@
 - 已验证初始化失败、缺少表结构、正常退出时关闭连接池，以及数据库停止后的 readiness 503、恢复后的 200。
 - 自动验收入口：`python3 scripts/verifyDatabase.py --version v0.2.0`；结束后清理本次测试容器、匿名卷和临时项目。

-## 3. 网络适配一致性（已完成，v0.3.0）
+## 3. 网络适配一致性（已完成，v0.4.0）

- Gin 与标准库适配器运行同一套契约测试。
+- 标准库适配器运行公共契约测试，并为自研网络层保留相同的接入边界。
 - 覆盖路由参数、分组、中间件、错误响应和取消传播。
 - 验收：切换适配器后，业务 Handler 和 Service 无需修改，约定的 HTTP 行为一致。
 - 新增公共 `transport/transporttest.Run`，自研适配器可直接复用；覆盖静态 / 参数 / 通配路由、分组、405 Allow、鉴权短路、错误与 panic、响应提交、requestId、并发隔离、截止时间及真实客户端取消。
- 两种适配器共享明确的路径与方法约定，修复尾部斜杠、通配参数、Any 和 Gin 405 Allow 差异。
- 完整用户 CRUD 已用相同业务注册代码在两种适配器上验证；全量 race 测试通过。
- 自动验收入口：`python3 scripts/verifyTransports.py --version v0.3.0`，从源码目录外消费远程版本与公共契约测试包。
+- 标准库路由实现明确的路径、方法、尾部斜杠、通配参数、Any 和 404/405 约定；不再引入 Gin 依赖。
+- 完整用户 CRUD 已用标准库适配器验证；自研适配器可直接复用同一公共契约测试包。
+- 自动验收入口：`python3 scripts/verifyTransports.py --version v0.4.0`，从源码目录外消费远程版本与公共契约测试包。

-## 4. 实际业务试用（待完成）
+## 4. 实际业务试用（已完成，v0.4.0）

- 在一个实际业务模块中使用远程固定版本，验证配置、日志、错误处理和升级流程。
- 根据真实接入问题收敛公共 API，再评估稳定版范围。
+- 在独立业务目录生成 billing service，先固定远程 `v0.2.0`，再升级到 `v0.4.0`，全程无本地 replace。
+- 验证环境配置、结构化访问日志、requestId 关联、参数校验、业务错误映射、CRUD、优雅退出和升级后的 race 测试。
+- 业务试用没有要求修改 Handler / Service；现有公共 API 足以支撑一套分层业务模块。
+- 自动验收入口：`python3 scripts/verifyBusiness.py --version v0.4.0`。

-以上阶段以验收结果判断完成。当前仍是基础框架试用阶段；MySQL 与适配层契约验收已完成，生产压测、自研网络内核与实际业务接入尚未完成。下一阶段先在真实业务模块中使用固定远程版本，再根据接入反馈收敛 API。
+## 5. 自研网络层、稳定性与性能基线（进行中，v0.5.0 预览）
+
+- 已加入标准库路由和完整 GoOmni 请求链 benchmark，输出分配次数和耗时，作为未来自研网络层的对照基线。
+- 新增 `transport/native` 第一版自研 HTTP/1.1 服务端：自行管理 TCP listener、Keep-Alive、Content-Length 请求解析、响应写回、读写超时和优雅关闭；通过 `App.RunWith` 接入，业务 Handler / Service 保持不变。
+- native 当前拒绝 chunked 请求体，仍使用标准 `http.Request` / `http.ResponseWriter` 作为桥接；解析器、连接抽象和生产压测将在后续阶段继续下沉。
+- 已具备全量 race、vet、build 验收；生产压测、长连接规模和真实部署验证仍待完成。
+- 自动验收入口：`python3 scripts/verifyPerformance.py`。
+
+以上阶段以验收结果判断完成。当前仍是基础框架试用阶段；MySQL、适配层契约和一次业务模块试用已完成，自研网络层已有可运行预览，稳定性与生产规模验证尚未完成。
--- a/app/app.go
+++ b/app/app.go
@@ -15,7 +15,7 @@ import (
 	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/middleware"
-	ginrouter "git.yuntuo.hk/k2safe/go-omni/transport/gin"
+	netrouter "git.yuntuo.hk/k2safe/go-omni/transport/nethttp"
 )

 // App is the top-level GoOmni application. Its public behavior depends on
@@ -29,10 +29,17 @@ type App struct {
 	closeErr    error
 }

-// New creates an application using the default Gin adapter.
+// Runner is the small lifecycle boundary used by an HTTP server
+// implementation. The default App.RunContext uses net/http; a custom runner
+// can own the listener, protocol parser and connection lifecycle.
+type Runner interface {
+	Run(context.Context, http.Handler, string) error
+}
+
+// New creates an application using GoOmni's standard-library router.
 func New(options ...config.Option) *App {
 	settings := configure(options...)
-	return newApp(ginrouter.New(settings.Mode), settings)
+	return newApp(netrouter.New(), settings)
 }

 // NewWithRouter creates an application with a custom network layer. A custom
@@ -68,7 +75,7 @@ func newApp(router httpx.Router, settings config.Config) *App {
 func (a *App) Router() httpx.Router { return a.router }

 // Engine is kept as a compatibility name for the old API. It returns a
-// standard http.Handler, so callers no longer need a Gin type.
+// standard http.Handler, so callers do not depend on a router type.
 func (a *App) Engine() http.Handler { return a.router }

 // ServeHTTP implements http.Handler for standard servers and HTTP tests.
@@ -150,6 +157,25 @@ func (a *App) RunContext(ctx context.Context, address ...string) error {
 	return a.serveContext(ctx, server, listener)
 }

+// RunWith starts a custom server runner while keeping App-owned cleanup in the
+// same lifecycle. The runner receives the transport-neutral App handler.
+func (a *App) RunWith(ctx context.Context, runner Runner, address ...string) error {
+	if runner == nil {
+		return errors.Join(errors.New("go-omni: nil runner"), a.Close())
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	listenOn := a.config.Address
+	if listenOn == "" {
+		listenOn = ":8080"
+	}
+	if len(address) > 0 && address[0] != "" {
+		listenOn = address[0]
+	}
+	return errors.Join(runner.Run(ctx, a, listenOn), a.Close())
+}
+
 func (a *App) serveContext(ctx context.Context, server *http.Server, listener net.Listener) error {
 	serveErr := make(chan error, 1)
 	go func() { serveErr <- server.Serve(listener) }()
--- a/app_test.go
+++ b/app_test.go
@@ -8,12 +8,10 @@ import (
 	"strings"
 	"testing"
 	"time"
-
-	"github.com/gin-gonic/gin"
 )

 func TestAppReturnsStandardResponse(t *testing.T) {
-	app := New(WithMode(gin.TestMode))
+	app := New()
 	app.GET("/health", func(ctx *Context) error {
 		return ctx.OK(map[string]string{"status": "ok"})
 	})
@@ -41,7 +39,7 @@ func TestAppReturnsStandardResponse(t *testing.T) {
 }

 func TestAppReturnsAPIError(t *testing.T) {
-	app := New(WithMode(gin.TestMode))
+	app := New()
 	app.GET("/users/:id", func(ctx *Context) error {
 		return NotFound("USER_NOT_FOUND", "user was not found")
 	})
@@ -63,7 +61,7 @@ func TestAppReturnsAPIError(t *testing.T) {
 }

 func TestAppRecoversFromPanic(t *testing.T) {
-	app := New(WithMode(gin.TestMode))
+	app := New()
 	app.GET("/panic", func(ctx *Context) error {
 		panic("boom")
 	})
@@ -85,7 +83,7 @@ func TestAppRecoversFromPanic(t *testing.T) {
 }

 func TestAppRunContextShutsDownGracefully(t *testing.T) {
-	app := New(WithMode(gin.TestMode), WithShutdownTimeout(time.Second))
+	app := New(WithShutdownTimeout(time.Second))
 	ctx, cancel := context.WithCancel(context.Background())
 	done := make(chan error, 1)
 	go func() { done <- app.RunContext(ctx, "127.0.0.1:0") }()
@@ -102,7 +100,7 @@ func TestAppRunContextShutsDownGracefully(t *testing.T) {
 }

 func TestAppClosesResourcesInReverseOrder(t *testing.T) {
-	app := New(WithMode(gin.TestMode))
+	app := New()
 	var closed []string
 	app.OnShutdown(func() error {
 		closed = append(closed, "database")
--- a/auth/auth_test.go
+++ b/auth/auth_test.go
@@ -9,11 +9,10 @@ import (

 	"git.yuntuo.hk/k2safe/go-omni"
 	"git.yuntuo.hk/k2safe/go-omni/auth"
-	"github.com/gin-gonic/gin"
 )

 func TestRequireAuthAndRole(t *testing.T) {
-	app := omni.New(omni.WithMode(gin.TestMode))
+	app := omni.New()
 	authenticator := auth.StaticAuthenticator{"good-token": {UserID: "user-1", Roles: []string{"user"}}}
 	private := app.Group("/private", auth.RequireAuth(authenticator))
 	private.GET("/me", func(ctx *omni.Context) error {
@@ -62,7 +61,7 @@ func TestRequireAuthAndRole(t *testing.T) {
 }

 func TestOptionalAuth(t *testing.T) {
-	app := omni.New(omni.WithMode(gin.TestMode))
+	app := omni.New()
 	app.GET("/public", func(ctx *omni.Context) error {
 		principal, authenticated := auth.FromContext(ctx)
 		return ctx.OK(map[string]any{"authenticated": authenticated, "userId": principal.UserID})
--- a/cmd/go-omni/README.md
+++ b/cmd/go-omni/README.md
@@ -3,7 +3,7 @@
 从远程安装，生成一个带 Handler / Service / Repository / Model 分层的服务骨架：

 ```sh
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.3.0
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.5.0
 go-omni new --module example.com/billing ./billing
 cd billing
 go mod tidy
@@ -16,7 +16,7 @@ go run ./cmd/server
 需要选择其他已发布版本时，使用完整版本号：

 ```sh
-go-omni new --framework-version v0.3.0 --module example.com/billing ./billing
+go-omni new --framework-version v0.5.0 --module example.com/billing ./billing
 ```

 `--framework-version` 禁用自动本地替换；`main`、`latest` 等浮动引用不接受为固定版本。
@@ -48,8 +48,8 @@ MySQL 项目额外包含 `schema.sql`、MySQL Repository 和可选的数据库
 发布验收使用 Python 3 标准库脚本，不需要额外 Python 依赖：

 ```sh
-python3 scripts/verifyScaffold.py --version v0.3.0
-python3 scripts/verifyDatabase.py --version v0.3.0
+python3 scripts/verifyScaffold.py --version v0.5.0
+python3 scripts/verifyDatabase.py --version v0.5.0
 ```

 脚本在源码目录外安装远程 CLI、生成项目，确认固定版本且没有 `replace`，再下载依赖、
--- a/cmd/go-omni/scaffold/version.go
+++ b/cmd/go-omni/scaffold/version.go
@@ -10,7 +10,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
 // Source builds can carry an unpublished VCS version (including +dirty).
 // Keep this fallback in sync with the next release; installed CLIs use their
 // downloaded module version, which also has a module checksum.
-const defaultFrameworkVersion = "v0.3.0"
+const defaultFrameworkVersion = "v0.5.0"

 var frameworkVersionPattern = regexp.MustCompile(`^v[01]\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$`)

--- a/config/config.go
+++ b/config/config.go
@@ -11,7 +11,6 @@ const defaultRequestIDHeader = "X-Request-ID"

 // Config controls the default runtime behavior of an App.
 type Config struct {
-	Mode            string
 	Address         string
 	RequestIDHeader string
 	EnableLogger    bool
@@ -53,11 +52,6 @@ func (e *ConfigError) Error() string { return "config " + e.Field + " " + e.Mess
 // Option changes an App's configuration.
 type Option func(*Config)

-// WithMode sets the default transport's running mode.
-func WithMode(mode string) Option {
-	return func(cfg *Config) { cfg.Mode = mode }
-}
-
 // WithRequestIDHeader changes the header used to read and return request IDs.
 func WithRequestIDHeader(header string) Option {
 	return func(cfg *Config) {
--- a/config/config_test.go
+++ b/config/config_test.go
@@ -8,7 +8,7 @@ import (

 func TestLoadFromEnvUsesDefaults(t *testing.T) {
 	for _, key := range []string{
-		"GO_OMNI_MODE", "GO_OMNI_HTTP_ADDR", "GO_OMNI_REQUEST_ID_HEADER", "GO_OMNI_ENABLE_LOGGER",
+		"GO_OMNI_HTTP_ADDR", "GO_OMNI_REQUEST_ID_HEADER", "GO_OMNI_ENABLE_LOGGER",
 		"GO_OMNI_LOG_LEVEL", "GO_OMNI_LOG_FORMAT", "GO_OMNI_LOG_OUTPUT",
 		"GO_OMNI_LOG_FILE", "GO_OMNI_SERVICE", "GO_OMNI_ENVIRONMENT",
 		"GO_OMNI_LOG_ADD_SOURCE", "GO_OMNI_SHUTDOWN_TIMEOUT",
@@ -29,7 +29,6 @@ func TestLoadFromEnvUsesDefaults(t *testing.T) {
 }

 func TestLoadFromEnvOverridesSettings(t *testing.T) {
-	t.Setenv("GO_OMNI_MODE", "release")
 	t.Setenv("GO_OMNI_HTTP_ADDR", "127.0.0.1:9090")
 	t.Setenv("GO_OMNI_REQUEST_ID_HEADER", "X-Correlation-ID")
 	t.Setenv("GO_OMNI_ENABLE_LOGGER", "true")
@@ -45,7 +44,7 @@ func TestLoadFromEnvOverridesSettings(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if cfg.Mode != "release" || cfg.Address != "127.0.0.1:9090" || cfg.RequestIDHeader != "X-Correlation-ID" || !cfg.EnableLogger {
+	if cfg.Address != "127.0.0.1:9090" || cfg.RequestIDHeader != "X-Correlation-ID" || !cfg.EnableLogger {
 		t.Fatalf("unexpected application settings: %+v", cfg)
 	}
 	if cfg.ShutdownTimeout != 3*time.Second || cfg.Log.Level != "debug" || cfg.Log.Format != "text" || cfg.Log.Output != "stdout" || cfg.Log.Service != "billing" || cfg.Log.Environment != "test" || !cfg.Log.AddSource {
@@ -80,11 +79,10 @@ func TestLoadFromEnvRejectsInvalidValues(t *testing.T) {

 func TestWithConfigAndWithLogConfig(t *testing.T) {
 	settings := Default()
-	settings.Mode = "release"
 	settings.Log.Service = "orders"
 	cfg := Default()
 	WithConfig(settings)(&cfg)
-	if cfg.Mode != "release" || cfg.Log.Service != "orders" {
+	if cfg.Log.Service != "orders" {
 		t.Fatalf("complete config was not applied: %+v", cfg)
 	}

--- a/config/env.go
+++ b/config/env.go
@@ -18,7 +18,6 @@ func LoadFromEnv(prefix string) (Config, error) {
 		prefix = defaultEnvPrefix
 	}
 	cfg := Default()
-	cfg.Mode = envString(prefix+"MODE", cfg.Mode)
 	cfg.Address = envString(prefix+"HTTP_ADDR", cfg.Address)
 	cfg.RequestIDHeader = envString(prefix+"REQUEST_ID_HEADER", cfg.RequestIDHeader)
 	cfg.Log.Level = envString(prefix+"LOG_LEVEL", cfg.Log.Level)
--- a/examples/reference/README.md
+++ b/examples/reference/README.md
@@ -41,8 +41,8 @@ examples/reference/

 调用路径：HTTP → Handler → Service → Repository。

- Handler 依赖 GoOmni，示例代码不导入 Gin，也不调用 `Engine()` / `Raw()`。
- Service、Repository、Model 不依赖 GoOmni 或 Gin，通过标准 `context.Context` 传递请求取消信号。
+- Handler 依赖 GoOmni，示例代码不导入具体网络库，也不调用 `Engine()` / `Raw()`。
+- Service、Repository、Model 不依赖 GoOmni 或网络库，通过标准 `context.Context` 传递请求取消信号。
 - JSON 校验标签留在 Handler 的请求结构上；业务模型没有 HTTP 绑定标签。
 - Service 返回业务错误，由 Handler 映射为 HTTP 错误；未知错误交给框架转换成通用 500 响应。
 - 通过 `application.Group("/api/v1", handler.RequestLog(logger))` 挂载自定义中间件，再注册 `/users` 子路由。日志记录请求 ID、耗时和返回错误；panic 由框架恢复中间件处理。
@@ -156,6 +156,6 @@ go vet ./...
 go build ./...
 ```

-`TestUserCRUD` 将同一份业务注册代码分别挂载到 Gin 与 nethttp，验证替换适配器后 Handler、Service、Repository 均无需修改。
+`TestUserCRUD` 使用标准库适配器运行完整业务注册代码；同一套 Handler、Service、Repository 也可通过 `omni.NewWithRouter` 接入自研适配器。

 测试覆盖完整 CRUD、认证和角色权限、校验失败、分页边界、邮箱冲突及失败更新、删除后重用邮箱、请求 ID、日志关联、内部错误隐藏、并发唯一性、取消请求不修改数据、数据库配置解析和 HTTP 优雅退出。MySQL 测试不自动连接外部数据库。
--- a/examples/reference/main_test.go
+++ b/examples/reference/main_test.go
@@ -20,7 +20,6 @@ import (
 	"git.yuntuo.hk/k2safe/go-omni/examples/reference/repository"
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/logx"
-	ginrouter "git.yuntuo.hk/k2safe/go-omni/transport/gin"
 	netrouter "git.yuntuo.hk/k2safe/go-omni/transport/nethttp"
 )

@@ -32,7 +31,7 @@ type envelope struct {
 }

 func testApp() *omni.App {
-	return newApp(repository.NewMemoryUsers(), testLogger(io.Discard), omni.WithMode("test"))
+	return newApp(repository.NewMemoryUsers(), testLogger(io.Discard))
 }

 func testLogger(writer io.Writer) *logx.Logger {
@@ -87,7 +86,6 @@ func TestProtectedWriteRoutes(t *testing.T) {
 		repository.NewMemoryUsers(),
 		testLogger(io.Discard),
 		auth.StaticAuthenticator{"user-token": {UserID: "user-1", Roles: []string{"user"}}},
-		omni.WithMode("test"),
 	)
 	request(t, app, "POST", "/api/v1/users", `{"name":"Alice","email":"alice@example.com"}`, 401, "UNAUTHENTICATED")
 	created := dataAs[model.User](t, requestWithAuthorization(t, app, "POST", "/api/v1/users", `{"name":"Alice","email":"alice@example.com"}`, "Bearer user-token", 201, "CREATED"))
@@ -110,7 +108,6 @@ func TestUserCRUD(t *testing.T) {
 		name      string
 		newRouter func() httpx.Router
 	}{
-		{"gin", func() httpx.Router { return ginrouter.New("test") }},
 		{"nethttp", func() httpx.Router { return netrouter.New() }},
 	} {
 		t.Run(adapter.name, func(t *testing.T) {
@@ -226,7 +223,7 @@ func TestErrorTranslationAndRequestLogging(t *testing.T) {
 	} {
 		t.Run(test.name, func(t *testing.T) {
 			var logs bytes.Buffer
-			app := newApp(failingUsers{repository.NewMemoryUsers(), test.err}, testLogger(&logs), omni.WithMode("test"))
+			app := newApp(failingUsers{repository.NewMemoryUsers(), test.err}, testLogger(&logs))
 			result := request(t, app, "GET", "/api/v1/users/1", "", test.status, test.code)
 			if strings.Contains(result.Message, test.err.Error()) || len(result.Data) != 0 {
 				t.Fatalf("internal error details leaked: %+v", result)
--- a/go.mod
+++ b/go.mod
@@ -3,36 +3,19 @@ module git.yuntuo.hk/k2safe/go-omni
 go 1.22

 require (
-	github.com/gin-gonic/gin v1.10.0
 	github.com/go-playground/validator/v10 v10.20.0
 	github.com/go-sql-driver/mysql v1.9.3
 )

 require (
 	filippo.io/edwards25519 v1.1.0 // indirect
-	github.com/bytedance/sonic v1.11.6 // indirect
-	github.com/bytedance/sonic/loader v0.1.1 // indirect
-	github.com/cloudwego/base64x v0.1.4 // indirect
-	github.com/cloudwego/iasm v0.2.0 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
-	github.com/gin-contrib/sse v0.1.0 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
-	github.com/goccy/go-json v0.10.2 // indirect
-	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
-	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
-	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
-	github.com/ugorji/go/codec v1.2.12 // indirect
-	golang.org/x/arch v0.8.0 // indirect
+	github.com/stretchr/testify v1.9.0 // indirect
 	golang.org/x/crypto v0.23.0 // indirect
 	golang.org/x/net v0.25.0 // indirect
 	golang.org/x/sys v0.20.0 // indirect
 	golang.org/x/text v0.15.0 // indirect
-	google.golang.org/protobuf v1.34.1 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
--- a/go.sum
+++ b/go.sum
@@ -1,22 +1,9 @@
 filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
 filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
-github.com/bytedance/sonic v1.11.6 h1:oUp34TzMlL+OY1OUWxHqsdkgC/Zfc85zGqw9siXjrc0=
-github.com/bytedance/sonic v1.11.6/go.mod h1:LysEHSvpvDySVdC2f87zGWf6CIKJcAvqab1ZaiQtds4=
-github.com/bytedance/sonic/loader v0.1.1 h1:c+e5Pt1k/cy5wMveRDyk2X4B9hF4g7an8N3zCYjJFNM=
-github.com/bytedance/sonic/loader v0.1.1/go.mod h1:ncP89zfokxS5LZrJxl5z0UJcsk4M4yY2JpfqGeCtNLU=
-github.com/cloudwego/base64x v0.1.4 h1:jwCgWpFanWmN8xoIUHa2rtzmkd5J2plF/dnLS6Xd/0Y=
-github.com/cloudwego/base64x v0.1.4/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJgA0rcu/8w=
-github.com/cloudwego/iasm v0.2.0 h1:1KNIy1I1H9hNNFEEH3DVnI4UujN+1zjpuk6gwHLTssg=
-github.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/gabriel-vasile/mimetype v1.4.3 h1:in2uUcidCuFcDKtdcBxlR0rJ1+fsokWf+uqxgUFjbI0=
 github.com/gabriel-vasile/mimetype v1.4.3/go.mod h1:d8uq/6HKRL6CGdk+aubisF/M5GcPfT7nKyLpA0lbSSk=
-github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
-github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
-github.com/gin-gonic/gin v1.10.0 h1:nTuyha1TYqgedzytsKYqna+DfLos46nTv2ygFy86HFU=
-github.com/gin-gonic/gin v1.10.0/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
@@ -27,67 +14,19 @@ github.com/go-playground/validator/v10 v10.20.0 h1:K9ISHbSaI0lyB2eWMPJo+kOS/FBEx
 github.com/go-playground/validator/v10 v10.20.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
 github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
 github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
-github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
-github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
-github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
-github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
-github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
-github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
-github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
-github.com/klauspost/cpuid/v2 v2.2.7 h1:ZWSB3igEs+d0qvnxR/ZBzXVmxkgt8DdzP6m9pfuVLDM=
-github.com/klauspost/cpuid/v2 v2.2.7/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws=
-github.com/knz/go-libedit v1.10.1/go.mod h1:MZTVkCWyz0oBc7JOWP3wNAzd002ZbM/5hgShxwh4x8M=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
-github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
-github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
-github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
-github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
-github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
-github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
-github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
-github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
-github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
-github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
-github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
-github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
-github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
-github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
-github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
-github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
-github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
-golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
-golang.org/x/arch v0.8.0 h1:3wRIsP3pM4yUptoR96otTUOXI367OS0+c9eeRi9doIc=
-golang.org/x/arch v0.8.0/go.mod h1:FEVrYAQjsQXMVJ1nsMoVVXPZg6p2JE2mx8psSWTDQys=
 golang.org/x/crypto v0.23.0 h1:dIJU/v2J8Mdglj/8rJ6UUOM3Zc9zLZxVZwwxMooUSAI=
 golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
 golang.org/x/net v0.25.0 h1:d/OCCoBEUq33pjydKrGQhw7IlUPI2Oylr+8qLx49kac=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
-golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.20.0 h1:Od9JTbYCk261bKm4M/mw7AklTlFYIa0bIp9BgSm1S8Y=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/text v0.15.0 h1:h1V/4gjBv8v9cjcR6+AR5+/cIYK5N/WAgiv4xlsEtAk=
 golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
-golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=
-google.golang.org/protobuf v1.34.1/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-nullprogram.com/x/optparse v1.0.0/go.mod h1:KdyPE+Igbe0jQUrVfMqDMeJQIJZEuyV7pjYmp6pbG50=
-rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=
--- a/httpx/context.go
+++ b/httpx/context.go
@@ -18,9 +18,9 @@ type Handler func(*Context) error
 type Middleware func(Handler) Handler

 // Router is the small contract the application needs from a network layer.
-// The default implementation is backed by Gin, but another router or a
-// future GoOmni transport can implement this interface without changing
-// business handlers. Register routes before serving requests. Implementations
+// The default implementation is backed by the standard library, but another
+// router or a future GoOmni transport can implement this interface without
+// changing business handlers. Register routes before serving requests. Implementations
 // should pass transport/transporttest.Run; see transport/README.md for the
 // portable path, method, fallback and context-propagation rules.
 type Router interface {
@@ -78,7 +78,8 @@ func RoutePattern(ctx context.Context) string {
 }

 // Context provides the business-facing request and response API. It contains
-// only standard-library HTTP types, so it remains usable when Gin is replaced.
+// only standard-library HTTP types, so it remains usable when the network
+// implementation is replaced.
 type Context struct {
 	request   *http.Request
 	writer    http.ResponseWriter
--- a/logx/README.md
+++ b/logx/README.md
@@ -1,6 +1,6 @@
 # logx

-`logx` 是 GoOmni 的业务层结构化日志入口。业务代码不需要依赖 Gin：
+`logx` 是 GoOmni 的业务层结构化日志入口。业务代码不需要依赖具体网络库：

 ```go
 import "git.yuntuo.hk/k2safe/go-omni/logx"
--- a/logx/logx.go
+++ b/logx/logx.go
@@ -1,5 +1,5 @@
 // Package logx provides the application logger used by GoOmni and business
-// packages. Its public API is deliberately independent of Gin so the same
+// packages. Its public API is deliberately independent of the network layer so the same
 // logger can be used from HTTP handlers, jobs and command line programs.
 package logx

--- a/middleware/middleware.go
+++ b/middleware/middleware.go
@@ -31,8 +31,8 @@ func RequestID(header string) httpx.Middleware {
 }

 // Recovery converts panics from handlers and middleware into the standard
-// internal error. The network adapter does not need a Gin-specific recovery
-// hook for this behavior.
+// internal error. Recovery belongs to GoOmni's transport-neutral middleware
+// rather than a router-specific hook.
 func Recovery() httpx.Middleware {
 	return func(next httpx.Handler) httpx.Handler {
 		return func(ctx *httpx.Context) (err error) {
--- a/omni.go
+++ b/omni.go
@@ -13,6 +13,7 @@ import (
 )

 type App = app.App
+type Runner = app.Runner
 type RouterGroup = app.RouterGroup
 type Principal = auth.Principal
 type Authenticator = auth.Authenticator
@@ -34,8 +35,6 @@ func NewWithRouter(router Router, options ...Option) *App {
 	return app.NewWithRouter(router, options...)
 }

-func WithMode(mode string) Option { return config.WithMode(mode) }
-
 func WithRequestIDHeader(header string) Option { return config.WithRequestIDHeader(header) }

 func WithLogger(enabled bool) Option { return config.WithLogger(enabled) }
--- a/scripts/verifyBusiness.py
+++ b/scripts/verifyBusiness.py
@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Verify a real generated business module across a released framework upgrade."""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import signal
+import socket
+import subprocess
+import tempfile
+import time
+import urllib.error
+import urllib.request
+
+from verifyScaffold import MODULE, run
+
+
+def free_address():
+    with socket.socket() as listener:
+        listener.bind(("127.0.0.1", 0))
+        return f"127.0.0.1:{listener.getsockname()[1]}"
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--go", default="go")
+    parser.add_argument("--version", default="v0.5.0", help="Target framework release")
+    parser.add_argument("--from-version", default="v0.2.0", help="Version used before upgrade")
+    args = parser.parse_args()
+
+    env = dict(os.environ, GOWORK="off")
+    env["GOPRIVATE"] = ",".join(filter(None, [env.get("GOPRIVATE", ""), "git.yuntuo.hk"]))
+    with tempfile.TemporaryDirectory(prefix="go omni business ") as temporary:
+        root = Path(temporary).resolve()
+        env["GOBIN"] = str(root / "bin")
+        print(f"Installing released CLI {args.version}", flush=True)
+        run([args.go, "install", f"{MODULE}/cmd/go-omni@{args.version}"], root, env)
+        cli = root / "bin" / "go-omni"
+
+        project = root / "billing service"
+        run([
+            str(cli), "new", "--database", "memory", "--framework-version",
+            args.from_version, "--module", "example.com/billing", str(project),
+        ], root, env)
+        run([args.go, "mod", "tidy"], project, env)
+        manifest = (project / "go.mod").read_text()
+        if f"{MODULE} {args.from_version}" not in manifest or "replace " in manifest:
+            raise AssertionError("initial business project was not pinned to the expected remote version")
+        run([args.go, "test", "-race", "./..."], project, env)
+        run([args.go, "get", f"{MODULE}@{args.version}"], project, env)
+        run([args.go, "mod", "tidy"], project, env)
+        upgraded = (project / "go.mod").read_text()
+        if f"{MODULE} {args.version}" not in upgraded or "replace " in upgraded:
+            raise AssertionError("business project upgrade did not produce a clean remote pin")
+        run([args.go, "test", "-race", "./..."], project, env)
+        binary = project / "billing-server"
+        run([args.go, "build", "-o", str(binary), "./cmd/server"], project, env)
+
+        address = free_address()
+        log_file = project / "business.log"
+        server_env = dict(env)
+        server_env.update(
+            GO_OMNI_HTTP_ADDR=address,
+            GO_OMNI_ENABLE_LOGGER="true",
+            GO_OMNI_LOG_FILE=str(log_file),
+            GO_OMNI_LOG_FORMAT="json",
+            GO_OMNI_SHUTDOWN_TIMEOUT="2s",
+        )
+        client = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+        def request(method, path, body=None, request_id="business-request"):
+            payload = None if body is None else json.dumps(body).encode()
+            req = urllib.request.Request(
+                f"http://{address}{path}", data=payload, method=method,
+                headers={"Content-Type": "application/json", "X-Request-ID": request_id},
+            )
+            try:
+                with client.open(req, timeout=3) as response:
+                    return response.status, response.headers, json.load(response)
+            except urllib.error.HTTPError as error:
+                return error.code, error.headers, json.loads(error.read())
+
+        process = subprocess.Popen(
+            [str(binary)], cwd=project, env=server_env,
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+        )
+        try:
+            deadline = time.monotonic() + 15
+            while True:
+                if process.poll() is not None:
+                    output = process.stdout.read() if process.stdout else ""
+                    raise RuntimeError(f"business service exited during startup: {output}")
+                try:
+                    status, _, _ = request("GET", "/health/live")
+                    if status == 200:
+                        break
+                except OSError:
+                    pass
+                if time.monotonic() >= deadline:
+                    raise RuntimeError("business service did not start")
+                time.sleep(0.05)
+
+            status, headers, body = request("GET", "/health/ready")
+            if status != 200 or body.get("code") != "READY":
+                raise AssertionError(f"readiness failed: {status} {body}")
+            status, headers, body = request("POST", "/users", {"name": "broken"}, "invalid-request")
+            if status != 400 or body.get("code") != "INVALID_BODY" or headers.get("X-Request-ID") != "invalid-request":
+                raise AssertionError(f"validation contract failed: {status} {body}")
+            status, _, body = request("POST", "/users", {"name": "Alice", "email": "alice@example.com"}, "create-request")
+            if status != 201 or body.get("data", {}).get("email") != "alice@example.com":
+                raise AssertionError(f"business create failed: {status} {body}")
+            status, _, body = request("POST", "/users", {"name": "Duplicate", "email": "ALICE@example.com"}, "duplicate-request")
+            if status != 409 or body.get("code") != "EMAIL_TAKEN":
+                raise AssertionError(f"business error mapping failed: {status} {body}")
+            process.send_signal(signal.SIGTERM)
+            if process.wait(timeout=8) != 0:
+                raise AssertionError("business service did not exit cleanly")
+        finally:
+            if process.poll() is None:
+                process.kill()
+                process.wait(timeout=5)
+
+        content = log_file.read_text()
+        if '"http.request"' not in content or '"requestId":"create-request"' not in content:
+            raise AssertionError(f"access log did not contain business request correlation: {content}")
+        if '"service":"example.com/billing"' not in content:
+            raise AssertionError(f"business service name was not attached to logs: {content}")
+        if "private" in content.lower() and "password" in content.lower():
+            raise AssertionError("sensitive text leaked into business logs")
+
+        print(f"PASS business module: {args.from_version} -> {args.version}, clean remote pin, CRUD, validation, errors, requestId and logs", flush=True)
+
+
+if __name__ == "__main__":
+    main()
--- a/scripts/verifyDatabase.py
+++ b/scripts/verifyDatabase.py
@@ -145,7 +145,7 @@ class Server:
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--go", default="go")
-    parser.add_argument("--version", default="v0.3.0")
+    parser.add_argument("--version", default="v0.5.0")
    parser.add_argument("--cli", help="Use a locally built CLI")
    parser.add_argument("--framework-dir", help="Local framework source for pre-release checks")
    parser.add_argument("--image", default="mysql:8.4")
@@ -186,7 +186,7 @@ def main():
                    raise AssertionError(f"integration test did not pass: {name}\n{output}")
            print("PASS real MySQL: commit, error/panic/cancel rollback, pool limits, health timeout, close", flush=True)

-            serverEnv = dict(env, GO_OMNI_DB_DSN=database.dsn, GO_OMNI_MODE="release",
+            serverEnv = dict(env, GO_OMNI_DB_DSN=database.dsn,
                             GO_OMNI_DB_PING_TIMEOUT="500ms", GO_OMNI_ENABLE_LOGGER="true")
            server = Server(binary, project, serverEnv)
            servers.append(server)
--- a/scripts/verifyPerformance.py
+++ b/scripts/verifyPerformance.py
@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Run GoOmni's repeatable stability checks and transport performance baseline."""
+
+import argparse
+import os
+from pathlib import Path
+import subprocess
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--go", default="go")
+    parser.add_argument("--count", type=int, default=3)
+    args = parser.parse_args()
+    root = Path(__file__).resolve().parent.parent
+    env = dict(os.environ, GOWORK="off")
+    checks = [
+        ([args.go, "test", "-race", "./..."], "race tests"),
+        ([args.go, "vet", "./..."], "vet"),
+        ([args.go, "build", "./..."], "build"),
+        (
+            [args.go, "test", "-run", "^$", "-bench", "^BenchmarkTransport",
+             "-benchmem", "-count", str(args.count), "./transport"],
+            "transport benchmarks",
+        ),
+    ]
+    for command, name in checks:
+        print(f"Running {name}", flush=True)
+        result = subprocess.run(command, cwd=root, env=env, text=True,
+                                stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+        print(result.stdout, end="")
+        if result.returncode != 0:
+            raise SystemExit(f"{name} failed with exit code {result.returncode}")
+    print("PASS stability checks and transport performance baseline", flush=True)
+
+
+if __name__ == "__main__":
+    main()
--- a/scripts/verifyScaffold.py
+++ b/scripts/verifyScaffold.py
@@ -29,7 +29,7 @@ def exerciseServer(binary, directory, env, stopSignal, cleanupMarker=None):
        listener.bind(("127.0.0.1", 0))
        address = f"127.0.0.1:{listener.getsockname()[1]}"
    serverEnv = {key: value for key, value in env.items() if not key.startswith("GO_OMNI_")}
-    serverEnv.update(GO_OMNI_HTTP_ADDR=address, GO_OMNI_MODE="release",
+    serverEnv.update(GO_OMNI_HTTP_ADDR=address,
                     GO_OMNI_ENABLE_LOGGER="true", GO_OMNI_SHUTDOWN_TIMEOUT="2s")
    if cleanupMarker:
        serverEnv["GO_OMNI_CLEANUP_MARKER"] = str(cleanupMarker)
@@ -91,7 +91,7 @@ def exerciseServer(binary, directory, env, stopSignal, cleanupMarker=None):
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--go", default="go", help="Go executable")
-    parser.add_argument("--version", default="v0.3.0", help="Released CLI version to install")
+    parser.add_argument("--version", default="v0.5.0", help="Released CLI version to install")
    parser.add_argument("--cli", help="Use a locally built CLI instead of installing")
    parser.add_argument("--framework-version", help="Explicit version passed to the CLI")
    parser.add_argument("--framework-dir", help="Local checkout for pre-release verification")
@@ -142,7 +142,7 @@ import (
    omni "git.yuntuo.hk/k2safe/go-omni"
 )
 func main() {
-    app := omni.New(omni.WithMode("release"))
+    app := omni.New()
    app.GET("/health/live", func(ctx *omni.Context) error { return ctx.OK(map[string]string{"status": "ok"}) })
    app.OnShutdown(func() error { return os.WriteFile(os.Getenv("GO_OMNI_CLEANUP_MARKER"), []byte("closed"), 0600) })
    if err := app.Run(os.Getenv("GO_OMNI_HTTP_ADDR")); err != nil { log.Fatal(err) }
--- a/scripts/verifyTransports.py
+++ b/scripts/verifyTransports.py
@@ -13,7 +13,7 @@ from verifyScaffold import MODULE, run
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--go", default="go")
-    parser.add_argument("--version", default="v0.3.0")
+    parser.add_argument("--version", default="v0.5.0")
    parser.add_argument("--framework-dir", help="Use a local checkout before release")
    args = parser.parse_args()
    env = dict(os.environ, GOWORK="off")
@@ -29,15 +29,11 @@ def main():
 import (
    "testing"
    "{MODULE}/httpx"
-    ginrouter "{MODULE}/transport/gin"
    netrouter "{MODULE}/transport/nethttp"
    "{MODULE}/transport/transporttest"
 )

 func TestContract(t *testing.T) {{
-    t.Run("gin", func(t *testing.T) {{
-        transporttest.Run(t, func() httpx.Router {{ return ginrouter.New("test") }})
-    }})
    t.Run("nethttp", func(t *testing.T) {{
        transporttest.Run(t, func() httpx.Router {{ return netrouter.New() }})
    }})
@@ -52,14 +48,14 @@ func TestContract(t *testing.T) {{
        events = [json.loads(line) for line in output.splitlines() if line.startswith("{")]
        if any(event.get("Action") == "skip" for event in events):
            raise AssertionError("contract suite unexpectedly skipped tests")
-        for adapter in ("gin", "nethttp"):
+        for adapter in ("nethttp",):
            name = f"TestContract/{adapter}"
            if not any(event.get("Action") == "pass" and event.get("Test") == name for event in events):
                raise AssertionError(f"{adapter} contract did not pass")
            count = sum(event.get("Action") == "pass" and event.get("Test", "").startswith(name + "/")
                        for event in events)
            print(f"PASS {adapter}: {count} contract checks, including business handlers, cancellation and concurrent requests", flush=True)
-        print("PASS independent module: both adapters accepted by the same public contract suite", flush=True)
+        print("PASS independent module: nethttp accepted by the public contract suite", flush=True)


 if __name__ == "__main__":
--- a/transport/README.md
+++ b/transport/README.md
@@ -12,7 +12,25 @@ application := omni.NewWithRouter(netrouter.New())
 registerRoutes(application) // 与 omni.New() 复用同一份业务注册代码
 ```

-`transport/gin` 默认使用 Gin 分发请求；`transport/nethttp` 使用独立的标准库路由实现。两者共用路由声明校验和路径匹配规则，Gin 的正常请求仍由 Gin 路由树处理；它的 404/405 回退由适配层统一处理。
+`transport/nethttp` 是当前内置的标准库路由实现。它提供一套可移植的路径、方法和错误回退规则；自研网络层可以直接实现同一个 `httpx.Router` 契约。
+
+`transport/native` 是第一版自研 HTTP/1.1 服务端：它自己管理 TCP listener、连接、Keep-Alive、请求解析、响应写回和优雅关闭，再把请求交给现有 `http.Handler`。当前只支持 `Content-Length` 请求体，chunked 请求会返回 501；它仍使用标准 `http.Request` / `http.ResponseWriter` 作为业务桥接，因此不会影响现有 Handler / Service。
+
+服务端不是把连接交给一个全局串行 worker，而是每条连接独立处理请求；Keep-Alive 负责复用客户端连接，`Server` 内部的 `sync.Pool` 负责复用小型 Reader、响应对象和连接状态。Reader 默认只有 4 KiB，需要处理大请求头时按需增长。需要保护内存上限时，可以设置 `MaxConnections` 和 `MaxConcurrentRequests`；超出连接上限的连接会被关闭，超出请求并发上限的请求返回 503，不会无限排队。
+
+这个设计借鉴了 Nginx 的资源边界，但没有照搬它的进程模型：Nginx 用少量 worker 进程和事件机制管理大量连接，并用 `worker_connections` 限制每个 worker 的同时连接数；Go runtime 自己已经用 epoll / kqueue 等网络轮询器唤醒阻塞的 goroutine，因此 native 采用“accept loop + 每连接轻量 goroutine + 请求并发闸门”的等价实现。这样业务 Handler 可以继续执行同步代码，慢请求不会阻塞其他连接；只有在真实压测证明 goroutine 调度或协议状态机成为瓶颈时，才需要继续下沉为手写事件循环。
+
+使用自研服务端：
+
+```go
+application := omni.New()
+server := native.New(nil)
+if err := application.RunWith(ctx, server, ":8080"); err != nil {
+    log.Fatal(err)
+}
+```
+
+`omni.New()` 默认仍使用 `transport/nethttp` 路由；native 服务端是显式启用的预览实现，等协议和连接边界稳定后再考虑切换默认启动器。

 ## 可移植路由规则（v0.3.0）

@@ -35,8 +53,6 @@ HTTP 回退响应属于路由层，不进入应用路由中间件，不携带统

 业务层通过 `application.Handle("HEAD", path, handler)` 或 `group.Handle("OPTIONS", path, handler)` 显式注册其他方法，同样经过框架中间件和错误处理。

-`gin.NewWithEngine` 保留原生路由和中间件，但覆盖重定向、路径清理和 404/405 策略。可移植契约与 `Allow` 集合只覆盖经 GoOmni Router 注册的路由；直接操作 `Engine()` 的原生扩展不属于该保证。
-
 ## 业务行为

 - 同一套 Handler、Service、中间件用于两种适配器；应用、分组、嵌套分组、路由中间件依次进入、反序退出。
@@ -69,9 +85,9 @@ func TestContract(t *testing.T) {

 ```sh
 go test -race ./transport/... ./examples/reference
-python3 scripts/verifyTransports.py --version v0.3.0
+python3 scripts/verifyTransports.py --version v0.5.0
 ```

-第一条同时验证完整用户 CRUD 在两种适配器上复用相同 Handler / Service / Repository。第二条在源码目录外创建无 replace 的消费模块，从远程版本导入同一套验收包。
+第一条验证标准库适配器复用完整 Handler / Service / Repository。第二条在源码目录外创建无 replace 的消费模块，从远程版本导入同一套验收包；自研适配器也应使用同一个公共测试包。

-当前替换边界是路由与 HTTP 适配层，`App.Run` 仍使用标准库 `net/http.Server`。未来自研监听、连接管理或协议解析时，可让自研服务调用 `App.ServeHTTP`（提供标准 HTTP 请求/响应桥接），由自研启动层管理监听与关闭，并在退出时调用 `App.Close`；本阶段没有实现新的网络内核。
+当前替换边界分成两层：`transport/nethttp` 提供标准库路由，`transport/native` 进一步接管 TCP 监听、连接管理和 HTTP/1.1 协议 I/O。`App.Run` / `App.RunContext` 仍使用标准库 `net/http.Server`，需要显式调用 `App.RunWith(ctx, native.New(nil), address)` 才会启用 native 预览实现。native 当前通过标准 `http.Request` / `http.ResponseWriter` 桥接到业务层，后续可在不改 Handler / Service 的前提下逐步替换解析器和响应写回。
--- a/transport/benchmark_test.go
+++ b/transport/benchmark_test.go
@@ -0,0 +1,48 @@
+package transport_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	netrouter "git.yuntuo.hk/k2safe/go-omni/transport/nethttp"
+)
+
+func BenchmarkTransportRouteDispatch(b *testing.B) {
+	b.Run("nethttp", func(b *testing.B) {
+		router := netrouter.New()
+		router.Handle(http.MethodGet, "/users/:id", http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusNoContent)
+		}))
+		request := httptest.NewRequest(http.MethodGet, "/users/42", nil)
+		b.ReportAllocs()
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			writer := httptest.NewRecorder()
+			router.ServeHTTP(writer, request)
+			if writer.Code != http.StatusNoContent {
+				b.Fatalf("unexpected status %d", writer.Code)
+			}
+		}
+	})
+}
+
+func BenchmarkTransportApplicationRequest(b *testing.B) {
+	b.Run("nethttp", func(b *testing.B) {
+		application := omni.NewWithRouter(netrouter.New())
+		application.GET("/health", func(c *omni.Context) error {
+			return c.OK(map[string]string{"status": "ok"})
+		})
+		request := httptest.NewRequest(http.MethodGet, "/health", nil)
+		b.ReportAllocs()
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			writer := httptest.NewRecorder()
+			application.ServeHTTP(writer, request)
+			if writer.Code != http.StatusOK {
+				b.Fatalf("unexpected status %d", writer.Code)
+			}
+		}
+	})
+}
--- a/transport/contract_test.go
+++ b/transport/contract_test.go
@@ -4,19 +4,12 @@ import (
 	"testing"

 	"git.yuntuo.hk/k2safe/go-omni/httpx"
-	ginrouter "git.yuntuo.hk/k2safe/go-omni/transport/gin"
 	netrouter "git.yuntuo.hk/k2safe/go-omni/transport/nethttp"
 	"git.yuntuo.hk/k2safe/go-omni/transport/transporttest"
 )

 func TestAdapterContract(t *testing.T) {
-	for _, adapter := range []struct {
-		name      string
-		newRouter func() httpx.Router
-	}{
-		{"gin", func() httpx.Router { return ginrouter.New("test") }},
-		{"nethttp", func() httpx.Router { return netrouter.New() }},
-	} {
-		t.Run(adapter.name, func(t *testing.T) { transporttest.Run(t, adapter.newRouter) })
-	}
+	t.Run("nethttp", func(t *testing.T) {
+		transporttest.Run(t, func() httpx.Router { return netrouter.New() })
+	})
 }
--- a/transport/gin/router.go
+++ b/transport/gin/router.go
@@ -1,124 +0,0 @@
-// Package gin adapts Gin to GoOmni's transport-neutral router contract.
-// Business packages should import httpx and app, not this package.
-package gin
-
-import (
-	"net/http"
-	"sort"
-	"strings"
-
-	"git.yuntuo.hk/k2safe/go-omni/httpx"
-	"git.yuntuo.hk/k2safe/go-omni/transport/internal/routing"
-	ginlib "github.com/gin-gonic/gin"
-)
-
-// Router is the default Gin-backed GoOmni router.
-type Router struct {
-	engine *ginlib.Engine
-	routes []registeredRoute
-}
-
-type registeredRoute struct {
-	method   string
-	segments []routing.Segment
-}
-
-// New creates a Gin router without Gin's default logger or recovery middleware.
-func New(mode string) *Router {
-	if mode != "" {
-		ginlib.SetMode(mode)
-	}
-	return NewWithEngine(ginlib.New())
-}
-
-// NewWithEngine wraps an existing engine and applies GoOmni's routing policy.
-// Native middleware/routes are retained; redirect and fallback settings are
-// replaced. Register portable routes through Router, not Engine().
-func NewWithEngine(engine *ginlib.Engine) *Router {
-	if engine == nil {
-		panic("go-omni/gin: nil engine")
-	}
-	engine.RedirectTrailingSlash = false
-	engine.RedirectFixedPath = false
-	engine.RemoveExtraSlash = false
-	engine.UseRawPath = false
-	// Gin 1.10 can carry backtracking state between method trees during its
-	// 405 lookup. Derive Allow from registered patterns instead of that lookup.
-	engine.HandleMethodNotAllowed = false
-	router := &Router{engine: engine}
-	engine.NoRoute(router.fallback)
-	return router
-}
-
-func (r *Router) fallback(ctx *ginlib.Context) {
-	allowed := make(map[string]bool)
-	for _, route := range r.routes {
-		if _, matches := routing.Match(route.segments, ctx.Request.URL.Path); matches {
-			allowed[route.method] = true
-		}
-	}
-	if len(allowed) == 0 {
-		http.NotFound(ctx.Writer, ctx.Request)
-		return
-	}
-	methods := make([]string, 0, len(allowed))
-	for method := range allowed {
-		methods = append(methods, method)
-	}
-	sort.Strings(methods)
-	ctx.Header("Allow", strings.Join(methods, ", "))
-	http.Error(ctx.Writer, http.StatusText(http.StatusMethodNotAllowed), http.StatusMethodNotAllowed)
-}
-
-// Engine exposes the underlying Gin engine to adapter-specific integrations.
-func (r *Router) Engine() *ginlib.Engine { return r.engine }
-
-func (r *Router) ServeHTTP(writer http.ResponseWriter, request *http.Request) {
-	r.engine.ServeHTTP(writer, request)
-}
-
-func (r *Router) Handle(method, path string, handler http.Handler) {
-	segments := routing.Parse(method, path, handler)
-	r.engine.Handle(method, path, adapt(handler))
-	r.routes = append(r.routes, registeredRoute{method: method, segments: segments})
-}
-
-func (r *Router) Any(path string, handler http.Handler) {
-	for _, method := range routing.Methods {
-		r.Handle(method, path, handler)
-	}
-}
-
-func (r *Router) Group(path string) httpx.RouterGroup {
-	return &group{router: r, prefix: routing.Join("", path)}
-}
-
-type group struct {
-	router *Router
-	prefix string
-}
-
-func (g *group) Handle(method, path string, handler http.Handler) {
-	g.router.Handle(method, routing.Join(g.prefix, path), handler)
-}
-
-func (g *group) Any(path string, handler http.Handler) {
-	g.router.Any(routing.Join(g.prefix, path), handler)
-}
-
-func (g *group) Group(path string) httpx.RouterGroup {
-	return &group{router: g.router, prefix: routing.Join(g.prefix, path)}
-}
-
-func adapt(handler http.Handler) ginlib.HandlerFunc {
-	return func(ctx *ginlib.Context) {
-		params := make(map[string]string, len(ctx.Params))
-		for _, param := range ctx.Params {
-			params[param.Key] = param.Value
-		}
-		requestContext := httpx.WithRouteParams(ctx.Request.Context(), params)
-		requestContext = httpx.WithRoutePattern(requestContext, ctx.FullPath())
-		request := ctx.Request.WithContext(requestContext)
-		handler.ServeHTTP(ctx.Writer, request)
-	}
-}
--- a/transport/internal/routing/pattern.go
+++ b/transport/internal/routing/pattern.go
@@ -58,7 +58,7 @@ func Parse(method, path string, handler http.Handler) []Segment {
 	return segments
 }

-// CheckConflict enforces Gin-compatible ambiguity rules for one method.
+// CheckConflict enforces the portable ambiguity rules for one method.
 func CheckConflict(existing, next []Segment) {
 	for i := 0; i < len(existing) && i < len(next); i++ {
 		a, b := existing[i], next[i]
--- a/transport/native/server.go
+++ b/transport/native/server.go
@@ -0,0 +1,655 @@
+// Package native provides GoOmni's first project-owned HTTP/1.1 server.
+//
+// It deliberately keeps the public handler boundary as net/http so existing
+// GoOmni business code remains unchanged while connection management and
+// protocol I/O move out of net/http.Server. The parser currently supports
+// Content-Length request bodies and rejects chunked requests.
+package native
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+const (
+	defaultReadHeaderTimeout = 5 * time.Second
+	defaultReadTimeout       = 30 * time.Second
+	defaultWriteTimeout      = 30 * time.Second
+	defaultIdleTimeout       = 60 * time.Second
+	defaultMaxHeaderBytes    = 1 << 20
+	defaultMaxBodyBytes      = 8 << 20
+	defaultReadBufferSize    = 4 << 10
+	maxPooledResponseBytes   = 64 << 10
+)
+
+// Server is a small HTTP/1.1 server with project-owned connection lifecycle.
+// It supports keep-alive, graceful shutdown, bounded concurrency and standard
+// http.Handler values. Zero MaxConnections and MaxConcurrentRequests mean
+// unlimited; pooled protocol objects are reused automatically.
+type Server struct {
+	ReadHeaderTimeout     time.Duration
+	ReadTimeout           time.Duration
+	WriteTimeout          time.Duration
+	IdleTimeout           time.Duration
+	ReadBufferSize        int
+	MaxHeaderBytes        int
+	MaxBodyBytes          int64
+	MaxConnections        int
+	MaxConcurrentRequests int
+
+	mu             sync.Mutex
+	handler        http.Handler
+	listener       net.Listener
+	conns          map[*connection]struct{}
+	closing        bool
+	cancel         context.CancelFunc
+	wg             sync.WaitGroup
+	connSlots      chan struct{}
+	requestSlots   chan struct{}
+	readerPool     sync.Pool
+	writerPool     sync.Pool
+	connectionPool sync.Pool
+}
+
+type connection struct {
+	server        *Server
+	conn          net.Conn
+	active        atomic.Bool
+	closeWhenIdle atomic.Bool
+	closed        atomic.Bool
+	slotHeld      bool
+	closeDone     chan struct{}
+}
+
+// New creates a native server. The handler may also be supplied later through
+// App.RunWith, which is useful when the App owns the lifecycle.
+func New(handler http.Handler) *Server {
+	server := &Server{
+		handler:           handler,
+		ReadHeaderTimeout: defaultReadHeaderTimeout,
+		ReadTimeout:       defaultReadTimeout,
+		WriteTimeout:      defaultWriteTimeout,
+		IdleTimeout:       defaultIdleTimeout,
+		ReadBufferSize:    defaultReadBufferSize,
+		MaxHeaderBytes:    defaultMaxHeaderBytes,
+		MaxBodyBytes:      defaultMaxBodyBytes,
+		conns:             make(map[*connection]struct{}),
+	}
+	server.readerPool.New = func() any { return bufio.NewReaderSize(nil, server.readBufferSize()) }
+	server.writerPool.New = func() any { return newResponseWriter("") }
+	server.connectionPool.New = func() any { return &connection{server: server} }
+	return server
+}
+
+func (s *Server) readBufferSize() int {
+	if s.ReadBufferSize > 0 {
+		return s.ReadBufferSize
+	}
+	return defaultReadBufferSize
+}
+
+// Run implements app.Runner without importing the app package.
+func (s *Server) Run(ctx context.Context, handler http.Handler, address string) error {
+	if handler != nil {
+		s.handler = handler
+	}
+	if s.handler == nil {
+		return errors.New("go-omni/native: nil handler")
+	}
+	if address == "" {
+		address = ":8080"
+	}
+	listener, err := net.Listen("tcp", address)
+	if err != nil {
+		return err
+	}
+	return s.Serve(ctx, listener)
+}
+
+// Serve accepts connections from listener until the context is canceled or an
+// unrecoverable accept error occurs. The listener is owned by the Server.
+func (s *Server) Serve(ctx context.Context, listener net.Listener) error {
+	if listener == nil {
+		return errors.New("go-omni/native: nil listener")
+	}
+	if s.handler == nil {
+		return errors.New("go-omni/native: nil handler")
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	s.mu.Lock()
+	if s.listener != nil {
+		s.mu.Unlock()
+		return errors.New("go-omni/native: server is already running")
+	}
+	s.listener = listener
+	s.closing = false
+	if s.MaxConnections > 0 {
+		s.connSlots = make(chan struct{}, s.MaxConnections)
+	} else {
+		s.connSlots = nil
+	}
+	if s.MaxConcurrentRequests > 0 {
+		s.requestSlots = make(chan struct{}, s.MaxConcurrentRequests)
+	} else {
+		s.requestSlots = nil
+	}
+	baseCtx, cancel := context.WithCancel(context.Background())
+	s.cancel = cancel
+	s.mu.Unlock()
+	defer cancel()
+
+	shutdownDone := make(chan struct{})
+	go func() {
+		select {
+		case <-ctx.Done():
+			timeout := s.shutdownTimeout()
+			shutdownCtx, cancel := context.WithTimeout(context.Background(), timeout)
+			_ = s.Shutdown(shutdownCtx)
+			cancel()
+		case <-shutdownDone:
+		}
+	}()
+
+	var serveErr error
+	for {
+		conn, err := listener.Accept()
+		if err != nil {
+			if ctx.Err() != nil || s.isClosing() {
+				break
+			}
+			serveErr = err
+			break
+		}
+		if slots := s.connSlots; slots != nil {
+			select {
+			case slots <- struct{}{}:
+			default:
+				_ = conn.Close()
+				continue
+			}
+		}
+		state := s.connectionPool.Get().(*connection)
+		state.server = s
+		state.conn = conn
+		state.active.Store(false)
+		state.closeWhenIdle.Store(false)
+		state.closed.Store(false)
+		state.slotHeld = s.connSlots != nil
+		state.closeDone = make(chan struct{})
+		s.mu.Lock()
+		if s.closing {
+			s.mu.Unlock()
+			state.close()
+			s.recycleConnection(state)
+			continue
+		}
+		s.conns[state] = struct{}{}
+		s.wg.Add(1)
+		s.mu.Unlock()
+		go s.serveConnection(baseCtx, state)
+	}
+
+	close(shutdownDone)
+	s.mu.Lock()
+	if s.listener == listener {
+		s.listener = nil
+	}
+	s.mu.Unlock()
+	if ctx.Err() != nil || s.isClosing() {
+		timeout := s.shutdownTimeout()
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), timeout)
+		shutdownErr := s.Shutdown(shutdownCtx)
+		cancel()
+		return errors.Join(shutdownErr, serveErr)
+	}
+	_ = listener.Close()
+	timeout := s.shutdownTimeout()
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), timeout)
+	shutdownErr := s.Shutdown(shutdownCtx)
+	cancel()
+	return errors.Join(shutdownErr, serveErr)
+}
+
+// Shutdown stops accepting requests, cancels active request contexts and waits
+// for connections to finish. On timeout, active sockets are closed.
+func (s *Server) Shutdown(ctx context.Context) error {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	s.mu.Lock()
+	s.closing = true
+	if s.cancel != nil {
+		s.cancel()
+	}
+	listener := s.listener
+	states := make([]*connection, 0, len(s.conns))
+	for state := range s.conns {
+		state.closeWhenIdle.Store(true)
+		states = append(states, state)
+	}
+	s.listener = nil
+	s.mu.Unlock()
+	if listener != nil {
+		_ = listener.Close()
+	}
+	for _, state := range states {
+		if !state.active.Load() {
+			state.close()
+		}
+	}
+
+	done := make(chan struct{})
+	go func() {
+		s.wg.Wait()
+		close(done)
+	}()
+	select {
+	case <-done:
+		return nil
+	case <-ctx.Done():
+		for _, state := range states {
+			state.close()
+		}
+		<-done
+		return ctx.Err()
+	}
+}
+
+func (s *Server) shutdownTimeout() time.Duration {
+	if value := s.WriteTimeout; value > 0 {
+		return value
+	}
+	return defaultWriteTimeout
+}
+
+func (s *Server) isClosing() bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.closing
+}
+
+func (s *Server) serveConnection(baseCtx context.Context, state *connection) {
+	defer s.wg.Done()
+	defer func() {
+		state.close()
+		s.recycleConnection(state)
+	}()
+	reader := s.readerPool.Get().(*bufio.Reader)
+	reader.Reset(state.conn)
+	defer func() {
+		reader.Reset(nil)
+		s.readerPool.Put(reader)
+	}()
+	firstRequest := true
+	for {
+		readTimeout := s.ReadHeaderTimeout
+		if readTimeout <= 0 {
+			readTimeout = defaultReadHeaderTimeout
+		}
+		if !firstRequest && s.IdleTimeout > 0 {
+			readTimeout = s.IdleTimeout
+		} else if s.IdleTimeout > 0 && s.IdleTimeout < readTimeout {
+			readTimeout = s.IdleTimeout
+		}
+		_ = state.conn.SetReadDeadline(time.Now().Add(readTimeout))
+		request, closeAfter, err := readRequest(reader, state.conn, s.MaxHeaderBytes, s.MaxBodyBytes, func() {
+			if s.ReadTimeout > 0 {
+				_ = state.conn.SetReadDeadline(time.Now().Add(s.ReadTimeout))
+			} else {
+				_ = state.conn.SetReadDeadline(time.Time{})
+			}
+		})
+		if err != nil {
+			if !errors.Is(err, io.EOF) && !errors.Is(err, net.ErrClosed) && !isTimeout(err) {
+				status := http.StatusBadRequest
+				message := "bad request\n"
+				var protocolErr *protocolError
+				if errors.As(err, &protocolErr) {
+					status = protocolErr.status
+					message = protocolErr.message + "\n"
+				}
+				_ = writeSimple(state.conn, status, message, true, s.WriteTimeout)
+			}
+			return
+		}
+		_ = state.conn.SetReadDeadline(time.Time{})
+		firstRequest = false
+		requestContext, cancel := context.WithCancel(baseCtx)
+		request = request.WithContext(requestContext)
+		state.active.Store(true)
+		writer := s.writerPool.Get().(*responseWriter)
+		writer.reset(request.Method)
+		requestSlot := false
+		if slots := s.requestSlots; slots != nil {
+			select {
+			case slots <- struct{}{}:
+				requestSlot = true
+			case <-baseCtx.Done():
+				cancel()
+				writer.reset("")
+				s.writerPool.Put(writer)
+				state.active.Store(false)
+				return
+			default:
+				writer.Header().Set("Content-Type", "text/plain; charset=utf-8")
+				writer.WriteHeader(http.StatusServiceUnavailable)
+				writer.body.WriteString("server busy\n")
+				closing := s.isClosing() || state.closeWhenIdle.Load()
+				_ = writer.writeTo(state.conn, closeAfter || closing, s.WriteTimeout)
+				cancel()
+				writer.reset("")
+				s.writerPool.Put(writer)
+				state.active.Store(false)
+				if closeAfter || closing {
+					return
+				}
+				continue
+			}
+		}
+		handler := s.handler
+		handler.ServeHTTP(writer, request)
+		cancel()
+
+		closing := s.isClosing() || state.closeWhenIdle.Load()
+		if err := writer.writeTo(state.conn, closeAfter || closing, s.WriteTimeout); err != nil {
+			if requestSlot {
+				<-s.requestSlots
+			}
+			writer.reset("")
+			s.writerPool.Put(writer)
+			state.active.Store(false)
+			return
+		}
+		if requestSlot {
+			<-s.requestSlots
+		}
+		writer.reset("")
+		s.writerPool.Put(writer)
+		state.active.Store(false)
+		if closeAfter || closing {
+			return
+		}
+	}
+}
+
+func (c *connection) close() {
+	if c.closed.CompareAndSwap(false, true) {
+		defer close(c.closeDone)
+		_ = c.conn.Close()
+		c.server.mu.Lock()
+		delete(c.server.conns, c)
+		c.server.mu.Unlock()
+	}
+}
+
+func (s *Server) recycleConnection(c *connection) {
+	<-c.closeDone
+	if c.slotHeld {
+		if slots := s.connSlots; slots != nil {
+			<-slots
+		}
+		c.slotHeld = false
+	}
+	s.connectionPool.Put(c)
+}
+
+type protocolError struct {
+	status  int
+	message string
+}
+
+func (e *protocolError) Error() string { return e.message }
+
+func readRequest(reader *bufio.Reader, conn net.Conn, maxHeaderBytes int, maxBodyBytes int64, setBodyDeadline func()) (*http.Request, bool, error) {
+	if maxHeaderBytes <= 0 {
+		maxHeaderBytes = defaultMaxHeaderBytes
+	}
+	if maxBodyBytes <= 0 {
+		maxBodyBytes = defaultMaxBodyBytes
+	}
+	used := 0
+	readLine := func() (string, error) {
+		line, err := reader.ReadString('\n')
+		used += len(line)
+		if used > maxHeaderBytes {
+			return "", &protocolError{status: http.StatusRequestHeaderFieldsTooLarge, message: "request headers too large"}
+		}
+		if err != nil {
+			return "", err
+		}
+		if !strings.HasSuffix(line, "\n") {
+			return "", &protocolError{status: http.StatusBadRequest, message: "malformed request line"}
+		}
+		return strings.TrimSuffix(strings.TrimSuffix(line, "\n"), "\r"), nil
+	}
+
+	line, err := readLine()
+	if err != nil {
+		return nil, false, err
+	}
+	parts := strings.Split(line, " ")
+	if len(parts) != 3 || !validToken(parts[0]) {
+		return nil, true, &protocolError{status: http.StatusBadRequest, message: "malformed request line"}
+	}
+	protoMajor, protoMinor, ok := parseProtocol(parts[2])
+	if !ok {
+		return nil, true, &protocolError{status: http.StatusHTTPVersionNotSupported, message: "unsupported HTTP version"}
+	}
+	target := parts[1]
+	var requestURL *url.URL
+	if target == "*" {
+		requestURL = &url.URL{Path: "*"}
+	} else {
+		requestURL, err = url.ParseRequestURI(target)
+		if err != nil || requestURL.Path == "" || !strings.HasPrefix(requestURL.Path, "/") {
+			return nil, true, &protocolError{status: http.StatusBadRequest, message: "malformed request target"}
+		}
+	}
+
+	header := make(http.Header)
+	for {
+		line, err = readLine()
+		if err != nil {
+			return nil, true, err
+		}
+		if line == "" {
+			break
+		}
+		if strings.HasPrefix(line, " ") || strings.HasPrefix(line, "\t") {
+			return nil, true, &protocolError{status: http.StatusBadRequest, message: "folded headers are not supported"}
+		}
+		index := strings.IndexByte(line, ':')
+		if index <= 0 {
+			return nil, true, &protocolError{status: http.StatusBadRequest, message: "malformed header"}
+		}
+		name := strings.TrimSpace(line[:index])
+		value := strings.TrimSpace(line[index+1:])
+		if !validToken(name) || strings.ContainsAny(value, "\r\n") {
+			return nil, true, &protocolError{status: http.StatusBadRequest, message: "malformed header"}
+		}
+		header.Add(name, value)
+	}
+
+	if value := header.Get("Expect"); value != "" {
+		return nil, true, &protocolError{status: http.StatusExpectationFailed, message: "unsupported expectation"}
+	}
+	if value := header.Get("Transfer-Encoding"); value != "" && !strings.EqualFold(value, "identity") {
+		return nil, true, &protocolError{status: http.StatusNotImplemented, message: "chunked requests are not supported"}
+	}
+	contentLength := int64(0)
+	if value := header.Get("Content-Length"); value != "" {
+		contentLength, err = strconv.ParseInt(strings.TrimSpace(value), 10, 64)
+		if err != nil || contentLength < 0 {
+			return nil, true, &protocolError{status: http.StatusBadRequest, message: "invalid content length"}
+		}
+	}
+	if contentLength > maxBodyBytes {
+		return nil, true, &protocolError{status: http.StatusRequestEntityTooLarge, message: "request body too large"}
+	}
+	body := make([]byte, contentLength)
+	if contentLength > 0 {
+		if setBodyDeadline != nil {
+			setBodyDeadline()
+		}
+		if _, err := io.ReadFull(reader, body); err != nil {
+			return nil, true, err
+		}
+	}
+	request := &http.Request{
+		Method:        parts[0],
+		URL:           requestURL,
+		Proto:         parts[2],
+		ProtoMajor:    protoMajor,
+		ProtoMinor:    protoMinor,
+		Header:        header,
+		Body:          io.NopCloser(bytes.NewReader(body)),
+		ContentLength: contentLength,
+		Host:          header.Get("Host"),
+		RequestURI:    target,
+		RemoteAddr:    conn.RemoteAddr().String(),
+	}
+	closeAfter := strings.EqualFold(header.Get("Connection"), "close") ||
+		(protoMajor == 1 && protoMinor == 0 && !strings.Contains(strings.ToLower(header.Get("Connection")), "keep-alive"))
+	request.Close = closeAfter
+	return request, closeAfter, nil
+}
+
+func parseProtocol(value string) (int, int, bool) {
+	if value != "HTTP/1.1" && value != "HTTP/1.0" {
+		return 0, 0, false
+	}
+	return 1, int(value[len(value)-1] - '0'), true
+}
+
+func validToken(value string) bool {
+	if value == "" {
+		return false
+	}
+	for _, char := range value {
+		if char <= ' ' || strings.ContainsRune("()<>@,;:\\\"/[]?={} \t", char) {
+			return false
+		}
+	}
+	return true
+}
+
+func isTimeout(err error) bool {
+	var netErr net.Error
+	return errors.As(err, &netErr) && netErr.Timeout()
+}
+
+func writeSimple(conn net.Conn, status int, body string, closeAfter bool, timeout time.Duration) error {
+	writer := newResponseWriter("")
+	writer.status = status
+	writer.wroteHeader = true
+	writer.body.WriteString(body)
+	writer.header.Set("Content-Type", "text/plain; charset=utf-8")
+	return writer.writeTo(conn, closeAfter, timeout)
+}
+
+type responseWriter struct {
+	header        http.Header
+	status        int
+	wroteHeader   bool
+	body          bytes.Buffer
+	requestMethod string
+}
+
+func newResponseWriter(method string) *responseWriter {
+	return &responseWriter{header: make(http.Header), requestMethod: method}
+}
+
+func (w *responseWriter) reset(method string) {
+	for key := range w.header {
+		delete(w.header, key)
+	}
+	w.status = 0
+	w.wroteHeader = false
+	if w.body.Cap() > maxPooledResponseBytes {
+		w.body = bytes.Buffer{}
+	} else {
+		w.body.Reset()
+	}
+	w.requestMethod = method
+}
+
+func (w *responseWriter) Header() http.Header { return w.header }
+
+func (w *responseWriter) WriteHeader(status int) {
+	if w.wroteHeader {
+		return
+	}
+	w.status = status
+	w.wroteHeader = true
+}
+
+func (w *responseWriter) Write(data []byte) (int, error) {
+	if !w.wroteHeader {
+		w.WriteHeader(http.StatusOK)
+	}
+	return w.body.Write(data)
+}
+
+func (w *responseWriter) writeTo(conn net.Conn, closeAfter bool, timeout time.Duration) error {
+	if timeout > 0 {
+		_ = conn.SetWriteDeadline(time.Now().Add(timeout))
+	}
+	if !w.wroteHeader {
+		w.status = http.StatusOK
+		w.wroteHeader = true
+	}
+	body := w.body.Bytes()
+	noBody := w.requestMethod == http.MethodHead || w.status == http.StatusNoContent ||
+		w.status == http.StatusNotModified || (w.status >= 100 && w.status < 200)
+	if noBody {
+		body = nil
+	}
+	if w.header.Get("Content-Length") == "" && w.status != http.StatusNoContent && w.status != http.StatusNotModified {
+		w.header.Set("Content-Length", strconv.Itoa(len(w.body.Bytes())))
+	}
+	if closeAfter {
+		w.header.Set("Connection", "close")
+	}
+	keys := make([]string, 0, len(w.header))
+	for key := range w.header {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	var output bytes.Buffer
+	output.WriteString("HTTP/1.1 ")
+	output.WriteString(strconv.Itoa(w.status))
+	output.WriteByte(' ')
+	output.WriteString(http.StatusText(w.status))
+	output.WriteString("\r\n")
+	for _, key := range keys {
+		for _, value := range w.header.Values(key) {
+			if strings.ContainsAny(value, "\r\n") {
+				return errors.New("invalid response header")
+			}
+			output.WriteString(key)
+			output.WriteString(": ")
+			output.WriteString(value)
+			output.WriteString("\r\n")
+		}
+	}
+	output.WriteString("\r\n")
+	output.Write(body)
+	_, err := conn.Write(output.Bytes())
+	_ = conn.SetWriteDeadline(time.Time{})
+	return err
+}
--- a/transport/native/server_test.go
+++ b/transport/native/server_test.go
@@ -0,0 +1,301 @@
+package native_test
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	"git.yuntuo.hk/k2safe/go-omni/transport/native"
+	netrouter "git.yuntuo.hk/k2safe/go-omni/transport/nethttp"
+)
+
+func TestServerKeepAliveAndApplicationBridge(t *testing.T) {
+	application := omni.NewWithRouter(netrouter.New())
+	application.GET("/hello", func(ctx *omni.Context) error {
+		return ctx.OK(map[string]string{"message": "hello"})
+	})
+	server, listener, done := startServer(t, application)
+	defer stopServer(t, server, listener, done)
+
+	conn, err := net.Dial("tcp", listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	reader := bufio.NewReader(conn)
+
+	for index, closeAfter := range []bool{false, true} {
+		connectionHeader := "keep-alive"
+		if closeAfter {
+			connectionHeader = "close"
+		}
+		fmt.Fprintf(conn, "GET /hello HTTP/1.1\r\nHost: test\r\nConnection: %s\r\n\r\n", connectionHeader)
+		request := &http.Request{Method: http.MethodGet}
+		response, err := http.ReadResponse(reader, request)
+		if err != nil {
+			t.Fatalf("response %d: %v", index, err)
+		}
+		body, err := io.ReadAll(response.Body)
+		response.Body.Close()
+		if err != nil || response.StatusCode != http.StatusOK || !strings.Contains(string(body), "\"message\":\"hello\"") {
+			t.Fatalf("response %d: status=%d body=%s error=%v", index, response.StatusCode, body, err)
+		}
+	}
+}
+
+func TestServerRejectsUnsupportedBodyAndLimits(t *testing.T) {
+	application := omni.NewWithRouter(netrouter.New())
+	application.POST("/body", func(ctx *omni.Context) error { return ctx.OK("ok") })
+
+	server := native.New(application)
+	server.MaxBodyBytes = 4
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- server.Serve(context.Background(), listener) }()
+	waitForServer(t, listener.Addr().String())
+	defer stopServer(t, server, listener, done)
+
+	for _, requestText := range []string{
+		"POST /body HTTP/1.1\r\nHost: test\r\nTransfer-Encoding: chunked\r\n\r\n4\r\ntest\r\n0\r\n\r\n",
+		"POST /body HTTP/1.1\r\nHost: test\r\nContent-Length: 5\r\n\r\ntest!",
+	} {
+		conn, err := net.Dial("tcp", listener.Addr().String())
+		if err != nil {
+			t.Fatal(err)
+		}
+		_, _ = io.WriteString(conn, requestText)
+		response, err := http.ReadResponse(bufio.NewReader(conn), &http.Request{Method: http.MethodPost})
+		if err != nil {
+			conn.Close()
+			t.Fatal(err)
+		}
+		response.Body.Close()
+		if response.StatusCode != http.StatusNotImplemented && response.StatusCode != http.StatusRequestEntityTooLarge {
+			t.Fatalf("unexpected protocol status %d", response.StatusCode)
+		}
+		conn.Close()
+	}
+}
+
+func TestServerShutdownCancelsActiveHandler(t *testing.T) {
+	started := make(chan struct{})
+	application := omni.NewWithRouter(netrouter.New())
+	application.GET("/wait", func(ctx *omni.Context) error {
+		close(started)
+		<-ctx.Context().Done()
+		return ctx.Context().Err()
+	})
+	server, listener, done := startServer(t, application)
+
+	conn, err := net.Dial("tcp", listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, _ = io.WriteString(conn, "GET /wait HTTP/1.1\r\nHost: test\r\nConnection: close\r\n\r\n")
+	select {
+	case <-started:
+	case <-time.After(2 * time.Second):
+		t.Fatal("handler did not start")
+	}
+	shutdownContext, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if err := server.Shutdown(shutdownContext); err != nil {
+		t.Fatal(err)
+	}
+	response, err := http.ReadResponse(bufio.NewReader(conn), &http.Request{Method: http.MethodGet})
+	if err != nil {
+		t.Fatal(err)
+	}
+	response.Body.Close()
+	if response.StatusCode != http.StatusInternalServerError {
+		t.Fatalf("expected canceled handler to become 500, got %d", response.StatusCode)
+	}
+	conn.Close()
+	select {
+	case err := <-done:
+		if err != nil && !errors.Is(err, net.ErrClosed) {
+			t.Fatal(err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("server did not stop")
+	}
+}
+
+func TestServerConcurrentRequestLimit(t *testing.T) {
+	started := make(chan struct{})
+	release := make(chan struct{})
+	application := omni.NewWithRouter(netrouter.New())
+	application.GET("/work", func(ctx *omni.Context) error {
+		close(started)
+		<-release
+		return ctx.OK("done")
+	})
+	server := native.New(application)
+	server.MaxConcurrentRequests = 1
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- server.Serve(context.Background(), listener) }()
+	waitForServer(t, listener.Addr().String())
+	defer func() {
+		stopServer(t, server, listener, done)
+	}()
+
+	first, err := net.Dial("tcp", listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer first.Close()
+	_, _ = io.WriteString(first, "GET /work HTTP/1.1\r\nHost: test\r\nConnection: close\r\n\r\n")
+	select {
+	case <-started:
+	case <-time.After(2 * time.Second):
+		t.Fatal("first handler did not start")
+	}
+
+	second, err := net.Dial("tcp", listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer second.Close()
+	_, _ = io.WriteString(second, "GET /work HTTP/1.1\r\nHost: test\r\nConnection: close\r\n\r\n")
+	response, err := http.ReadResponse(bufio.NewReader(second), &http.Request{Method: http.MethodGet})
+	if err != nil {
+		t.Fatal(err)
+	}
+	response.Body.Close()
+	if response.StatusCode != http.StatusServiceUnavailable {
+		t.Fatalf("expected 503 at concurrency limit, got %d", response.StatusCode)
+	}
+	close(release)
+	response, err = http.ReadResponse(bufio.NewReader(first), &http.Request{Method: http.MethodGet})
+	if err != nil {
+		t.Fatal(err)
+	}
+	response.Body.Close()
+	if response.StatusCode != http.StatusOK {
+		t.Fatalf("expected first request to complete, got %d", response.StatusCode)
+	}
+}
+
+func TestServerReadHeaderTimeout(t *testing.T) {
+	application := omni.NewWithRouter(netrouter.New())
+	application.GET("/health", func(ctx *omni.Context) error { return ctx.OK("ok") })
+	server := native.New(application)
+	server.ReadHeaderTimeout = 25 * time.Millisecond
+	server.IdleTimeout = 0
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- server.Serve(context.Background(), listener) }()
+	waitForServer(t, listener.Addr().String())
+	defer stopServer(t, server, listener, done)
+
+	conn, err := net.Dial("tcp", listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	conn.SetReadDeadline(time.Now().Add(time.Second))
+	_, _ = io.WriteString(conn, "GET /health HTTP/1.1\r\nHost: test")
+	buffer := make([]byte, 1)
+	if _, err := conn.Read(buffer); err == nil {
+		t.Fatal("expected incomplete headers to time out and close")
+	}
+}
+
+func TestAppRunWithNativeRunner(t *testing.T) {
+	application := omni.NewWithRouter(netrouter.New())
+	application.GET("/health", func(ctx *omni.Context) error { return ctx.OK("ok") })
+	address := freeAddress(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	done := make(chan error, 1)
+	go func() { done <- application.RunWith(ctx, native.New(nil), address) }()
+	waitForServer(t, address)
+	response, err := http.Get("http://" + address + "/health")
+	if err != nil {
+		t.Fatal(err)
+	}
+	response.Body.Close()
+	if response.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", response.StatusCode)
+	}
+	cancel()
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("RunWith did not stop")
+	}
+}
+
+func startServer(t *testing.T, handler http.Handler) (*native.Server, net.Listener, <-chan error) {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	server := native.New(handler)
+	done := make(chan error, 1)
+	go func() { done <- server.Serve(context.Background(), listener) }()
+	waitForServer(t, listener.Addr().String())
+	return server, listener, done
+}
+
+func stopServer(t *testing.T, server *native.Server, listener net.Listener, done <-chan error) {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	_ = server.Shutdown(ctx)
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("server did not stop")
+	}
+	_ = listener.Close()
+}
+
+func freeAddress(t *testing.T) string {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	address := listener.Addr().String()
+	listener.Close()
+	return address
+}
+
+func waitForServer(t *testing.T, address string) {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		conn, err := net.DialTimeout("tcp", address, 50*time.Millisecond)
+		if err == nil {
+			conn.Close()
+			return
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("server did not start: %v", err)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+}
--- a/transport/nethttp/router.go
+++ b/transport/nethttp/router.go
@@ -1,5 +1,5 @@
-// Package nethttp provides a standard-library router for GoOmni, independent
-// of Gin. Register routes before serving requests.
+// Package nethttp provides GoOmni's standard-library router. Register routes
+// before serving requests.
 package nethttp

 import (
--- a/transport/nethttp/router_test.go
+++ b/transport/nethttp/router_test.go
@@ -10,7 +10,7 @@ import (
 	netrouter "git.yuntuo.hk/k2safe/go-omni/transport/nethttp"
 )

-func TestRouterWorksWithoutGin(t *testing.T) {
+func TestRouterWorks(t *testing.T) {
 	router := netrouter.New()
 	app := omni.NewWithRouter(router)
 	app.GET("/users/:id", func(ctx *omni.Context) error {
--- a/validate/validate.go
+++ b/validate/validate.go
@@ -21,7 +21,7 @@ func newValidator() *validator.Validate {
 }

 // JSON binds and validates a JSON request body using standard-library HTTP
-// types. It intentionally does not depend on Gin.
+// types. It intentionally does not depend on a network framework.
 func JSON(request *http.Request, value any) error {
 	if request == nil || request.Body == nil {
 		return apierrors.BadRequest("INVALID_BODY", "request body is invalid")
Author	SHA1	Message	Date
k2safe	05b4088a25	feat: add bounded native http server	2026-09-21 01:58:50 +08:00
k2safe	3bbf4627a1	feat: remove Gin and standardize on nethttp	2026-09-21 00:57:06 +08:00
k2safe	61c37e0dba	test: verify remote business module upgrade flow	2026-09-21 00:23:22 +08:00