44 lines
3.7 KiB
Markdown
44 lines
3.7 KiB
Markdown
# HTTP 限额与停机安全验收（2026-09-29）
|
||
|
||
对应 v0.27.0-preview；历史 v0.26.0-preview 标签保持。框架不包含业务文件规格、数据库实现或应用专属错误码。
|
||
|
||
## 行为验收
|
||
|
||
| 场景 | 结果 |
|
||
| --- | --- |
|
||
| nethttp/native/HTTP2：16 MiB 路由接收 9 MiB | 固定长度与未知长度均成功 |
|
||
| 默认、路由覆盖、服务硬上限 | 边界值成功，超限进入 BODY_TOO_LARGE；读取中间件也受 reader 限额约束 |
|
||
| 路由超过服务硬上限 | 启动前拒绝，诊断包含嵌套分组完整路径及两级字节数；外部宿主可调用 ValidateHTTP |
|
||
| native 提前拒绝上传 | 先发出响应再有界半关闭，避免即时关闭触发 TCP reset；10 轮上传相关 race 回归通过 |
|
||
| 错误目录将超限映射为 HTTP 200 | 业务码/HTTP 策略保持，不再继续读取被拒绝的请求体；客户端不发送 body 也能及时收到响应 |
|
||
| 正常停机与取消后收尾 | 处理链和 defer 完成后才运行资源清理；收尾成功仍保留原排空超时错误 |
|
||
| 不响应取消的处理器 | 有界返回 ErrResourcesRetained，跳过 App 清理；重复 Close、晚到返回不触发清理 |
|
||
| App/Engine/NewServer/RunWith | 统一跟踪请求；停止后拒绝新请求，不执行依赖项目资源的处理链 |
|
||
| HTTP/2 客户端断开 | Shutdown 同时等待连接和独立 handler，不把连接结束当成业务结束 |
|
||
| 真实生成项目 | HTTP 未结束时 Runtime.Finish 仍停止后台工作，但保留客户端与日志；重复 deps.Close 不能绕过保护 |
|
||
| 可运行示例 | 9 MiB 上传返回 9437184 字节；SIGTERM 后先请求收尾、再关闭资源；排空超时退出码为 1 |
|
||
|
||
## 检查
|
||
|
||
- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -count=1 ./...`：54 个测试包通过，包含真实生成消费者的 race/build。
|
||
- `GOTOOLCHAIN=go1.22.12 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -count=1 ./...`：54 个测试包通过。随后 native 拒绝连接收尾补充修复，在最终代码上重新执行 `GOTOOLCHAIN=go1.22.12 go test -count=1 ./app ./config ./lifecycle ./httpx ./transport/...`，8 个测试包通过。
|
||
- `go test -race ./app ./transport/native -run 'Test(UploadPolicy|ConfiguredBody|ApplicationRejectsUnreadBody)' -count=10`：通过。
|
||
- `go vet ./...`、`go build ./...`、`git diff --check`：通过。
|
||
- 编译并实跑 `examples/httpSafety`，使用随机本机端口与实际 SIGTERM 验证上传和关闭顺序，无外部服务。
|
||
|
||
## 兼容边界
|
||
|
||
旧 nethttp 手写普通路由新增默认 8 MiB 限额，大请求应显式配置；生成契约默认 1 MiB 保持。取消后的等待默认 5s，需计入服务停机预算。手写资源拥有者须将运行错误传给 Runtime.Finish，并在资源保留信号下跳过自己的额外关闭操作。自建 goroutine、Hijack 后的工作仍须登记后台生命周期。
|
||
|
||
自定义 Runner、独立 native/http2.Server、反向代理的额外限额由各自拥有者配置；使用 WithTransport 获取统一装配。请求体、multipart 单文件和幂等缓存限额保持各自用途。已发送的流式响应无法撤回，先完成有界读取再执行业务。
|
||
|
||
## 远程发布验收
|
||
|
||
空模块缓存安装远程固定版本后，10 组生成消费者和 98 项发布检查通过，耗时 107.57 秒，无本地 replace；覆盖上传限额、取消收尾、HTTP/2 断连、生成项目依赖与日志保留。标签固定在 `3b00bb55d189cbe480c7d15c8d14bcd09d3f2d52`，见 [远程验收记录](httpSafetyRemote.json)。
|
||
|
||
模块校验和：`h1:IYc1zEBQX6GTPvORAC9Q7ezlzKlGn1nVnK8T68L/DGA=`。运行命令：
|
||
|
||
```sh
|
||
npm exec --yes --package=typescript@5.6.3 -- python3 scripts/verifyManagedRelease.py --version v0.27.0-preview --report reports/httpSafetyRemote.json
|
||
```
|