Python curl stream 1 was not closed cleanly

Question

在使用 Python 的 `pycurl` 库进行 HTTP 流式下载或上传时，常出现“curl: (90) stream 1 was not closed cleanly”错误。该问题通常发生在客户端提前终止连接、服务器未正确关闭 HTTP/2 流，或网络中断导致流未按协议规范完成。尤其在使用 HTTP/2 协议复用多个流时，若未妥善处理响应结束或未读取完整响应体，便可能触发此错误。尽管程序功能正常，但该警告会影响日志清晰度与错误判断。如何在保持高性能流式传输的同时，确保流被干净关闭，成为常见技术挑战。

Answer 1

一、问题背景与现象分析

在使用 Python 的 pycurl 库进行 HTTP 流式下载或上传时，开发者常遇到如下错误信息：

curl: (90) stream 1 was not closed cleanly

该错误属于 libcurl 在 HTTP/2 协议下对流状态管理的警告，表示某个 HTTP/2 流（stream）未按规范完成关闭流程。尽管程序可能已成功获取所需数据，但此警告会污染日志系统，影响错误监控系统的准确性，尤其在高并发、长时间运行的服务中尤为突出。

HTTP/2 支持多路复用（multiplexing），多个请求共享一个 TCP 连接，并通过独立的“流”进行通信。每个流需遵循严格的生命周期：创建 → 数据传输 → 正常关闭（发送 END_STREAM 标志）。若客户端提前中断读取、未消费完响应体或服务器异常终止流，则会触发此错误。

二、常见触发场景分类

• 客户端主动中断：调用方在接收完关键数据后立即退出回调函数，未等待完整响应结束。
• 未读取完整响应体：仅读取部分数据即停止处理，libcurl 认为流未完成。
• 服务器端行为异常：服务端未正确发送 GOAWAY 或 RST_STREAM 帧，或提前关闭连接。
• 网络不稳定：中间代理、防火墙或 TLS 层中断导致流状态不一致。
• 超时设置不合理：过短的超时时间强制断开仍在传输的流。
• 异步模式资源释放顺序错误：CURL handle 被提前销毁而底层流仍处于活动状态。
• 重定向与连接复用冲突：跨域名重定向后旧连接上的流未妥善清理。
• 缓冲区满导致写阻塞：write function 返回值处理不当引发流停滞。
• HEAD 请求误用流控制：无响应体但仍需正确处理流终结信号。
• 并发流数量超过限制：服务器设置 MAX_CONCURRENT_STREAMS，超出后拒绝新流并重置旧流。

三、底层机制解析：HTTP/2 流状态机

理解 HTTP/2 流的状态迁移是解决问题的关键。以下是基于 RFC 7540 定义的核心状态流转图：

graph TD A[Idle] -->|Headers sent/received| B[Open] B -->|RST_STREAM or EOS sent&recv| C[Closed] A -->|Locally Reserved| D[Reserved (Local)] A -->|Remotely Reserved| E[Reserved (Remote)] D -->|Headers sent| B E -->|Headers received| B B -->|Half-Closed (Local)| F[HCL] B -->|Half-Closed (Remote)| G[HCR] F -->|RST_STREAM or EOS recv| C G -->|RST_STREAM or EOS sent| C F -->|RST_STREAM sent| C G -->|RST_STREAM recv| C C --> C

当客户端未显式读取到 END_STREAM 标志（即 EOS），或收到 RST_STREAM 帧而非正常关闭，libcurl 就会报告“not closed cleanly”。

四、诊断方法与工具链支持

工具/方法	用途说明	命令示例或配置方式
tcpdump + Wireshark	抓包分析 HTTP/2 帧类型（HEADERS, DATA, RST_STREAM, GOAWAY）	tcpdump -i any -w http2.pcap host example.com
curl --trace	输出详细协议交互日志	curl --http2 --trace-ascii debug.log https://api.example.com/data
pycurl CURLOPT_VERBOSE	启用 libcurl 内部调试输出	c.setopt(pycurl.VERBOSE, 1)
nghttp	专用 HTTP/2 客户端测试工具	nghttp -v https://api.example.com/stream
日志关键字匹配	搜索 "stream", "RST_STREAM", "error code:"	grep -i stream debug.log
自定义 WRITEFUNCTION 返回值监控	确保回调不意外返回错误码	返回 len(data)，不可返回 None 或负数
strace/ltrace	跟踪系统调用与库函数调用	strace -e trace=network -f python test_pycurl.py
openssl s_client -alpn h2	验证 ALPN 是否协商为 h2	openssl s_client -connect api.example.com:443 -alpn h2
server-side access log	检查是否主动 reset stream	Nginx: $status, $http2_stream_id, $sent_http_content_length
perf tools	性能瓶颈定位	perf record -g python app.py

五、解决方案层级演进

1. 基础层：确保完整消费响应体
   即使不需要全部数据，也应在 WRITEFUNCTION 中持续读取直至连接自然结束。
2. 控制层：合理设置超时与中断逻辑
   避免使用硬性 timeout 中断流，改用应用层标记+优雅退出。
3. 协议层：强制降级至 HTTP/1.1 测试对比
   设置 CURLOPT_HTTP_VERSION = pycurl.CURL_HTTP_VERSION_1_1 排除 HTTP/2 特性干扰。
4. 资源管理：延迟释放 CURL handle
   等待所有流状态归于 CLOSED 后再执行 c.close()。
5. 回调设计：正确处理 HEADERFUNCTION 与 WRITEFUNCTION
   忽略不必要的头字段，避免因 header 解析异常中断流。
6. 连接池优化：复用连接时清理残留状态
   使用 CURLOPT_FORBID_REUSE 或定期重建连接以规避累积错误。
7. 错误容忍策略：捕获并分类 (90) 错误
   结合业务语义判断是否可忽略此类非致命警告。
8. 异步集成：结合 asyncio + curl-aio 或 pycurl multi stack
   利用多句柄接口精细控制事件循环与流生命周期。
9. 服务端协同：推动服务端完善 GOAWAY 发送逻辑
   特别是在连接关闭前应通知客户端准备终止流。
10. 监控增强：建立流健康度指标体系
    统计每千次请求中“(90)”出现频率，作为服务质量参考。

六、代码实践示例

以下是一个健壮的 pycurl 流式下载实现，包含防“(90)”错误的最佳实践：

import pycurl
from io import BytesIO

def safe_stream_download(url):
    buffer = BytesIO()
    c = pycurl.Curl()
    
    # 基础配置
    c.setopt(c.URL, url)
    c.setopt(c.WRITEFUNCTION, buffer.write)
    c.setopt(c.HTTP_VERSION, pycurl.CURL_HTTP_VERSION_2_0)
    
    # 超时控制（避免 abrupt disconnect）
    c.setopt(c.CONNECTTIMEOUT, 30)
    c.setopt(c.TIMEOUT, 300)  # 允许长耗时流
    
    # 可选：开启调试
    # c.setopt(c.VERBOSE, 1)

    try:
        c.perform()
        
        # 检查是否发生流异常
        if c.getinfo(c.RESPONSE_CODE) >= 400:
            print("HTTP Error:", c.getinfo(c.RESPONSE_CODE))
        else:
            body = buffer.getvalue()
            # 可在此处截断处理，但务必让 perform() 完成
            process_data(body)
            
    except pycurl.error as e:
        errno, msg = e.args
        if errno == 90:
            # 可记录但不抛出异常，视业务决定
            print(f"Ignorable stream closure: {msg}")
        else:
            raise
    finally:
        c.close()  # 确保最后才关闭 handle

# 使用示例
safe_stream_download("https://httpbin.org/stream/10")