fix(httpx,gormx): unencrypted-HTTP2 via Protocols, resource caps, and three ltefield tags that reject valid configs

[molon]

1. h2c.NewHandler 已废弃 → 改用 http.Server.Protocols

x/net（本仓库依赖的 v0.55.0 起）里的声明：

// Deprecated: Set the [http.Server] Protocols field to use unencrypted HTTP/2 instead.
func NewHandler(h http.Handler, s *http2.Server) http.Handler

同一个文件还有一条我们一直没照做的警告：

The first request on an h2c connection is read entirely into memory before the Handler is called. To limit the memory consumed by this request, wrap the result of NewHandler in an http.MaxBytesHandler.

标准库实现（net/http/server.go 的 maybeServeUnencryptedHTTP2）只 Peek 24 字节比对 PRI * HTTP/2.0 前导，仅支持 prior-knowledge 模式——「首请求全量入内存」正是 Upgrade 模式的实现代价，少支持一种模式反而少了一个内存放大面。

顺带把 HTTP/2 的启用从「由 tls.enabled=false 反推」改成显式声明三个协议位。原来的 if/else 让「TLS 关闭」隐式蕴含「启用 h2c」，而这两件事语义无关。

protocols := new(http.Protocols)
protocols.SetHTTP1(true)
protocols.SetHTTP2(true)              // TLS 经 ALPN
protocols.SetUnencryptedHTTP2(true)   // h2c
srv.Protocols = protocols

⚠️ 行为差异

依赖 Upgrade: h2c 头升级的客户端将静默退回 HTTP/1.1（不报错）。Envoy（配 appProtocol: kubernetes.io/h2c 时）和 gRPC 客户端用的都是 prior-knowledge，不受影响。

2. MaxRequestBodySize（新增，0 = 不限）

经 http.MaxBytesHandler 包在最外层，先于路由与业务 handler 生效。

3. MaxConnections（新增，0 = 不限）

经 netutil.LimitListener 加在 SetupListener 上。

只防 fd 耗尽，不是并发闸门。 HTTP/2 一条连接可承载多个 stream，全局并发 = 连接数 × 每连接 stream 数。真正的并发上限应由上游（网关 circuit breaker）或 in-flight middleware 控制——注释和 usage 里都写明了，避免被当成限流开关误用。

另注：超出限制时 Accept 阻塞（连接停在内核 accept queue），不是拒绝。

未做：maxConcurrentStreams

它是 per-connection 的，调小只会让客户端多开连接绕过去，管不住总并发；在网关后面收紧它更是有害无益（把请求挤成网关侧排队或更多连接，零额外保护）。Go 默认 250 保持不动。

若将来确实要加，建议沿用标准库的名字 maxConcurrentStreams，不要叫 maxParallelRequests——Envoy 的同名字段是全局在途请求数，语义完全不同，同名会让人误以为设了它就有全局上限。

测试

新增 httpx/server_test.go——NewServer 此前没有测试文件。覆盖迁移后最需要守住的行为：

• TestNewServer_H2C：prior-knowledge h2c 仍可用（用 http2.Transport{AllowHTTP: true} 验证 r.Proto == "HTTP/2.0"）
• TestNewServer_HTTP1StillWorks：同一 server 上 HTTP/1.1 仍可用
• TestNewServer_MaxRequestBodySize：低于上限、超过上限、0 = 不限 三种情形

go test ./httpx/... ./healthz/... ./netx/... 全绿。

背景

来自一次 pod 稳定性审查。相关的两个 P0 修复已分别提在 theplant/mcd-freewifi#98 和 theplant/mad-provisioning#123。

---

gormx：maxOpenConns 默认 200 → 0，以及三处 ltefield 的同一个坑

1. 默认值 200 从来没有真正生效过

单个 pod 不可能有 200 个并发查询，所以 200 不是上限，只是一个看起来像经过考量、实际从不 binding 的数字——而消费方会照着它做容量规划（「200 × 5 副本 = 1000 条，超了 RDS 的 475」），基于一个从未发生的前提。

改成 0（unlimited），与 database/sql 自身的默认一致。

要不要设上限是消费方的取舍，本 PR 不替使用者做这个决定 —— 库的注释只陈述机制：超过上限时调用方阻塞在 sql.DB 内部，而这个等待只能通过 DBStats.WaitCount 看到。需要上限的部署自己设一个即可。

maxIdleConns 保持 20。顺带把它的注释说准了：它是 pool 里保留的空闲连接数（超出的在归还时关闭），不限制能开多少连接。

2. 连带必须改：三处 ltefield 拿「0 = 不限制」当上界

只改默认值会让所有消费方启动即崩。MaxIdleConns 带着 validate:"ltefield=MaxOpenConns"，而 20 <= 0 是 false。

顺着查下去，同一个坑在这个仓库里有三处：

字段	原 tag	触发它的合法配置
gormx.MaxIdleConns	ltefield=MaxOpenConns	(20, 0) — 不限制连接数
gormx.ConnMaxIdleTime	ltefield=ConnMaxLifetime	(10m, 0) — 连接永不回收
httpx.ReadHeaderTimeout	ltefield=ReadTimeout	(10s, 0) — 只设 header 超时

三条都实测复现过。httpx 那条最容易踩：它没有默认值文件，而「只设一个 header 超时」是很自然的最小加固。

解法：stop_if 守住那个 ltefield

MaxIdleConns      `validate:"stop_if=MaxOpenConns 0,ltefield=MaxOpenConns"`
ConnMaxIdleTime   `validate:"stop_if=ConnMaxLifetime 0,ltefield=ConnMaxLifetime"`
ReadHeaderTimeout `validate:"stop_if=ReadTimeout 0,ltefield=ReadTimeout"`

stop_if 命中时让该字段后续的 tag 短路，它自己的错误由 confx 按 tag 名滤掉。

go-playground/validator 里没有能做这件事的内置 tag —— 183 个内置项里 skip_* 家族只有一个 skip_unless，而它 return hasValue(fl)，是个存在性检查，后面的 tag 照跑。所以这个 tag 加在了 qor5/confx#21。

中途试过把配对检查挪进构造函数。能用，但回到 tag 层更好：配置错误在配置校验阶段就暴露（confx.ValidationSuite 抓得到，而不是等到 Open() / NewServer() 才炸），错误是结构化的（path + tag），三处写法也和其余校验一致。

已反证：把 stop_if 从 tag 里去掉，「无上限 + 热池 (20, 0)」与「只设 header 超时 (10s, 0)」两个合法配置立刻被拒。

stop_if 来自 qor5/confx#21，已合入 main，go.mod 指向正式的 pseudo-version。

⚠️ 这次 bump 的影响面比「一个 confx」大。 本仓库的 confx 之前 pin 在 2025-04-26，而 confx 在那之后做过一轮依赖安全升级（qor5/confx#19），所以跟着上来的还有：

• viper 1.19.0 → 1.20.1 及其依赖树变化（mitchellh/mapstructure → go-viper/mapstructure，去掉 hcl / ini.v1 / slog-shim / x/exp）
• 直接依赖 spf13/cast 1.7.1 → 1.9.2、validator 10.25.0 → 10.26.0

这些不是 confx#21 引入的（那个 PR 只改了 validator.go 与其测试，一行依赖都没动），是补上落后一年的 pin 必然带的。全仓 go build ./... 与 go test 通过。

验证

httpx + gormx 全部测试通过。新增：

• TestMaxIdleConnsAgainstCap
• TestConnMaxIdleTimeAgainstLifetime
• TestReadHeaderTimeoutAgainstReadTimeout

各钉三种组合（有上限且合规 / 有上限且越界 / 无上限）。TestConfig 补一条 20 / 0 的用例——它正是改默认值的前提。

关联

• theplant/mcd-freewifi#98、theplant/mad-provisioning#123：消费方同步移除了 maxOpenConns 与网关熔断
• theplant/qortex-suite#170：PROV_DB_POOL_IDLE_EXCEEDS_OPEN 有完全相同的 0 = 不限制 bug，一并修了

[Copilot]

Pull request overview

This PR updates httpx server initialization to remove reliance on deprecated h2c.NewHandler, explicitly enable HTTP/1.1 + HTTP/2 (TLS + h2c prior-knowledge) via http.Server.Protocols, and adds safeguards against oversized request bodies and excessive open connections.

Changes:

• Replace deprecated h2c.NewHandler usage with http.Server.Protocols (enabling h2c prior-knowledge + HTTP/2 over TLS).
• Add MaxRequestBodySize (via http.MaxBytesHandler) and MaxConnections (via netutil.LimitListener) to ServerConfig and server/listener setup.
• Add new tests for h2c prior-knowledge, HTTP/1.1 compatibility, and request-body size limiting; update example config with new knobs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
httpx/server.go	Applies max body size limit at the outer handler layer, adds connection cap via LimitListener, and enables protocols via http.Server.Protocols.
httpx/server_test.go	Adds coverage for h2c prior-knowledge, HTTP/1.1 still working, and MaxRequestBodySize behavior.
httpx/example/config.yaml	Documents and exposes maxRequestBodySize and maxConnections in the example configuration.
httpx/config.go	Extends ServerConfig with MaxRequestBodySize and MaxConnections plus usage/docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.