响应管理

相关源文件

• caddytest/integration/stream_test.go
• modules/caddyhttp/responsewriter.go
• modules/caddyhttp/reverseproxy/ascii.go
• modules/caddyhttp/reverseproxy/ascii_test.go
• modules/caddyhttp/reverseproxy/streaming.go
• modules/caddyhttp/reverseproxy/streaming_test.go

本文档涵盖 Caddy 的 HTTP 响应管理系统，包括响应记录、流式传输、缓冲、协议升级和连接劫持。该系统提供灵活的响应处理策略，针对不同内容类型和协议进行了优化。

有关请求处理和路由的信息，请参阅请求路由。有关 TLS 连接管理的信息，请参阅连接策略。

响应写入策略

Caddy 通过包装器类型实现了复杂的响应管理，这些类型可以将响应直接流式传输到客户端，或将其缓冲以进行处理。核心抽象是 ResponseWriterWrapper，它扩展了标准 http.ResponseWriter 接口。

响应写入器包装器

ResponseWriterWrapper 提供了比标准 HTTP 响应写入器更强大的功能

该包装器通过 Push 方法实现 HTTP/2 服务器推送，通过 ReadFrom 优化 I/O，并为 http.ResponseController 兼容性进行适当的解包。

来源：modules/caddyhttp/responsewriter.go26-63

响应记录与缓冲

responseRecorder 类型根据 ShouldBufferFunc 回调提供条件缓冲

记录系统支持流式传输和缓冲模式

模式	行为	用例
流式传输	直接写入底层写入器	实时响应、大文件
缓冲	写入内存缓冲区	响应转换、错误处理

来源：modules/caddyhttp/responsewriter.go65-187

协议升级与连接劫持

Caddy 通过专门的劫持和流式传输机制处理协议升级，特别是 WebSocket 连接。

WebSocket 升级流程

handleUpgradeResponse 函数管理协议升级，支持 HTTP/1.1 和 HTTP/2

系统通过不同的代码路径处理标准 HTTP/1.1 WebSocket 升级和 HTTP/2 WebSocket 实现。

来源：modules/caddyhttp/reverseproxy/streaming.go60-231

连接管理

被劫持的连接需要特殊的生命周期管理，因为它们绕过了正常的 HTTP 服务器清理

连接跟踪系统确保服务器关闭期间的正确清理，并可选择延迟关闭以实现优雅的 WebSocket 终止。

来源：modules/caddyhttp/reverseproxy/streaming.go370-448

流式传输优化

Caddy 实施了智能刷新策略，根据内容类型和协议特性优化响应流式传输。

刷新间隔管理

flushInterval 方法确定最佳刷新行为

特殊刷新规则适用于

• 服务器发送事件：对于 text/event-stream 立即刷新
• 流式响应：当 Content-Length 未设置时立即刷新
• HTTP/2 双向流：立即刷新以实现实时通信

来源：modules/caddyhttp/reverseproxy/streaming.go235-256

最大延迟写入器

maxLatencyWriter 实现了可配置延迟限制的受控刷新

这提供了平衡延迟和效率的自适应刷新，对于流媒体应用程序和实时数据传输尤为重要。

来源：modules/caddyhttp/reverseproxy/streaming.go569-629

双向流检测

isBidirectionalStream 函数识别需要立即刷新的场景

条件	要求
请求协议	HTTP/2
响应协议	HTTP/2
内容长度	-1 (未知/流式传输)
Accept-Encoding	"identity" 或为空

此检测可优化 HTTP/2 流式传输场景的处理，同时避免与内容编码中间件冲突。

来源：modules/caddyhttp/reverseproxy/streaming.go258-273