libcurl 的 CURLOPT_TCP_FASTOPEN 详解:用 TCP Fast Open(RFC 7413)省掉一个 RTT
libcurl 的 CURLOPT_TCP_FASTOPEN 详解:用 TCP Fast Open(RFC 7413)省掉一个 RTT
本指南以 curl 仓库中 CURLOPT_TCP_FASTOPEN.md 为骨架,系统讲解 libcurl 中 TCP Fast Open(TFO)选项的语义、启用方式、底层实现与适用边界。读完本文,你将掌握如何在 C 程序中通过 CURLOPT_TCP_FASTOPEN 开启 TFO、如何使用命令行工具 --tcp-fastopen,并理解为什么它会与 TLS 会话缓存冲突、哪些平台才真正支持它。
选项总览
CURLOPT_TCP_FASTOPEN 是 libcurl 提供的一个布尔型传输选项,用于控制在建立 TCP 连接时是否启用 TCP Fast Open(RFC 7413)。该选项自 curl 7.49.0 起加入,官方文档将其归入 TCP 协议类别,仅对基于 TCP 的传输(HTTP/HTTPS、FTP、IMAP、SMTP、MQTT 等)有意义。
在 include/curl/curl.h 中,它被声明为:
CURLOPT(CURLOPT_TCP_FASTOPEN, CURLOPTTYPE_LONG, 244),
即它是一个类型为 CURLOPTTYPE_LONG 的选项,数值编号为 244。在 lib/easyoptions.c 中同样登记为 CURLOT_LONG 类型,并在 docs/libcurl/symbols-in-versions 中记录其引入版本。
NAME 与 SYNOPSIS
函数原型:
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_FASTOPEN, long enable);
handle:由curl_easy_init()返回的 easy handle;enable:传入1L表示启用,传入0表示关闭。
DESCRIPTION:TFO 是什么,能带来什么
文档对选项语义的权威描述如下:
Pass a long as parameter set to 1L to enable or 0 to disable. TCP Fast Open (RFC 7413) is a mechanism that allows data to be carried in the SYN and SYN-ACK packets and consumed by the receiving end during the initial connection handshake, saving up to one full round-trip time (RTT).
即:TCP Fast Open(RFC 7413)允许将数据携带在 SYN 与 SYN-ACK 报文里,并在初始握手阶段就被对端消费,从而最多节省一个完整的往返时间(RTT)。
传统 TCP 三次握手(SYN → SYN-ACK → ACK)中,应用数据必须等第三次握手完成后才能发送。而 TFO 允许客户端在首个 SYN 报文里就携带应用数据(前提是此前已与该服务器建立过连接并取得 TFO Cookie,或使用无 Cookie 的"快速打开"尝试),服务器可在收到 SYN 时就把数据交给应用层处理,数据通道被提前打通。对于 RTT 较大的跨国、跨网连接,或需要频繁建立短连接(如 API 调用、健康检查)的场景,这一个 RTT 的节省对首字节延迟(TTFB)改善明显。
使用条件与警告
文档明确给出两条重要提醒:
- TLS 会话缓存失效:当 TFO 启用时,TLS 会话缓存不再工作(Beware: the TLS session cache does not work when TCP Fast Open is enabled)。
- 跨网络兼容性问题:TFO 在某些网络或跨越某些网络时已知存在问题(TCP Fast Open is also known to be problematic on or across certain networks),例如部分中间设备、防火墙或 NAT 网关可能不支持或干扰 TFO,导致连接异常。
因此,TFO 是一个"以兼容性换取延迟"的权衡选项,适合在可控网络环境、且服务端明确支持 TFO 时开启,不宜作为全局默认策略。
DEFAULT:默认关闭
该选项的默认值为 0(关闭)。对应源码层面,连接位标志 tcp_fastopen 默认清零——在 lib/urldata.h(连接数据结构)与 lib/urldata.h(传输结构)中均有 BIT(tcp_fastopen); /* use TCP Fast Open */ 的位域声明,未显式开启时即保持关闭。
命令行动手:--tcp-fastopen
除 C 接口外,curl 命令行工具同样暴露了该能力。在 src/tool_getparam.c 中注册了参数:
{"tcp-fastopen", ARG_BOOL, ' ', C_TCP_FASTOPEN},
命令行帮助信息(docs/cmdline-opts/tcp-fastopen.md)为:
Enable use of TCP Fast Open (RFC 7413). TCP Fast Open is a TCP extension that allows data to be sent earlier over the connection (before the final handshake ACK) if the client and server have been connected previously.
实际使用:
# 对任意 URL 启用 TFO
curl --tcp-fastopen https://example.com
# 等价写法:使用布尔参数
curl --tcp-fastopen=true https://example.com
curl --tcp-fastopen=false https://example.com
命令行选项在解析后写入 config->tcp_fastopen(见 src/tool_getparam.c),随后在工具层映射为 CURLOPT_TCP_FASTOPEN 传给 libcurl。
EXAMPLE:C 语言最小示例
文档给出的标准示例:
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode result;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L);
result = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
}
编译方式与普通 libcurl 程序一致:
cc -o tfo-example tfo-example.c -lcurl
要点:
curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L)必须在curl_easy_perform()之前调用,因为选项是在每次传输建立连接时生效的;- 用完后调用
curl_easy_cleanup(curl)释放资源; - 若想观察 TFO 是否真正生效,可结合 curl 的
--trace/-v输出或抓包(如tcpdump)查看 SYN 包中是否携带数据。
平台与内核支持(NOTES)
文档明确指出:
This option is only supported on Linux and macOS 10.11 or later.
即 仅支持 Linux 以及 macOS 10.11 及更高版本。这条约束直接反映在 libcurl 的源码条件编译中。
在 lib/setopt.c 中,CURLOPT_TCP_FASTOPEN 的 setopt 处理被包裹在平台宏判断里:
case CURLOPT_TCP_FASTOPEN:
#if defined(CONNECT_DATA_IDEMPOTENT) || defined(MSG_FASTOPEN) || \
defined(TCP_FASTOPEN_CONNECT)
s->tcp_fastopen = enabled;
break;
#else
return CURLE_NOT_BUILT_IN;
#endif
含义非常直接:
- 在 macOS / iOS / tvOS / watchOS(定义
CONNECT_DATA_IDEMPOTENT)或 Linux(定义MSG_FASTOPEN或新内核的TCP_FASTOPEN_CONNECT)上,选项被接受并生效; - 在其他平台上调用该选项会直接返回
CURLE_NOT_BUILT_IN(即"该功能未编译进当前构建"),而不是静默忽略。这意味着程序可以借此判断当前平台是否支持 TFO。
源码实现:TFO 是如何接入 TCP 连接的
1. 连接位标志的传递
从 lib/urldata.h 可以看到,TFO 状态存放在连接结构的位域 tcp_fastopen 中,它由 setopt 写入的传输状态(lib/urldata.h)在连接建立时同步到连接结构。
2. 套接字层:do_connect() 中的三路分支
TFO 真正落地在 TCP 套接字过滤器的 do_connect() 函数中(lib/cf-socket.c),该函数接收 bool is_tcp_fastopen 参数,并按平台分三条路径处理:
static int do_connect(struct Curl_cfilter *cf, struct Curl_easy *data,
bool is_tcp_fastopen)
{
struct cf_socket_ctx *ctx = cf->ctx;
#ifdef TCP_FASTOPEN_CONNECT
int optval = 1;
#endif
int rc = -1;
(void)data;
if(is_tcp_fastopen) {
#ifdef CONNECT_DATA_IDEMPOTENT /* Darwin */
/* macOS/iOS 路径:使用 connectx() 的 CONNECT_DATA_IDEMPOTENT 标志 */
rc = connectx(ctx->sock, &endpoints, SAE_ASSOCID_ANY,
CONNECT_RESUME_ON_READ_WRITE | CONNECT_DATA_IDEMPOTENT,
NULL, 0, NULL, NULL);
#elif defined(TCP_FASTOPEN_CONNECT) /* Linux >= 4.11 */
/* 新内核路径:setsockopt(TCP_FASTOPEN_CONNECT) + 普通 connect() */
if(setsockopt(ctx->sock, IPPROTO_TCP, TCP_FASTOPEN_CONNECT,
(void *)&optval, sizeof(optval)) < 0)
CURL_TRC_CF(data, cf, "Failed to enable TCP Fast Open on fd %"
FMT_SOCKET_T, ctx->sock);
rc = connect(ctx->sock, &ctx->addr.curl_sa_addr, ctx->addr.addrlen);
#elif defined(MSG_FASTOPEN) /* old Linux */
/* 老内核路径:SSL 连接退化为普通 connect,非 SSL 交由上层处理 */
if(Curl_conn_is_ssl(cf->conn, cf->sockindex))
rc = connect(ctx->sock, &ctx->addr.curl_sa_addr, ctx->addr.addrlen);
else
rc = 0; /* Do nothing */
#endif
}
else {
rc = connect(ctx->sock, &ctx->addr.curl_sa_addr,
(curl_socklen_t)ctx->addr.addrlen);
}
return rc;
}
三条路径的关键差异:
| 平台/内核 | 触发宏 | 实现方式 |
|---|---|---|
| macOS 10.11+ / iOS 9+ | CONNECT_DATA_IDEMPOTENT |
使用 connectx() 并携带 CONNECT_DATA_IDEMPOTENT 标志(且用 __builtin_available 做运行时版本判断,见 lib/cf-socket.c) |
| Linux ≥ 4.11 | TCP_FASTOPEN_CONNECT |
先 setsockopt(IPPROTO_TCP, TCP_FASTOPEN_CONNECT, 1),再普通 connect() |
| 老版本 Linux | MSG_FASTOPEN |
SSL 连接回退为普通 connect();非 SSL 连接返回 0 交由上层特殊处理 |
值得注意的是老 Linux 内核(MSG_FASTOPEN 路径)下,TFO 与 TLS 不能同时使用:源码明确对 SSL 连接直接退化为普通 connect,这与文档"TFO 下 TLS 会话缓存不工作"的警告在实现上相互印证——TFO 下 TLS 握手数据前置发送的机制会破坏会话缓存/会话恢复的语义。
3. 调用链:从过滤器到系统调用
do_connect() 由套接字过滤器的 cf_tcp_connect()(lib/cf-socket.c)调用:
rc = do_connect(cf, data, (bool)cf->conn->bits.tcp_fastopen);
即连接过滤器在建立 TCP 连接时读取连接位标志 bits.tcp_fastopen,若为真则走 TFO 分支。整个调用链可以概括为:
curl_easy_setopt(CURLOPT_TCP_FASTOPEN, 1L)
→ setopt 写入 s->tcp_fastopen (lib/setopt.c)
→ 连接建立时同步到 conn->bits.tcp_fastopen (lib/urldata.h)
→ cf_tcp_connect() 读取该标志 (lib/cf-socket.c)
→ do_connect() 按平台选择 TFO 实现
→ connectx() / setsockopt(TCP_FASTOPEN_CONNECT)+connect()
这种"过滤器(cfilter)"架构是 libcurl 连接层的一种设计模式:TCP 连接作为一个过滤器节点参与连接的组合与复用,TFO 只在最底层的 TCP 过滤器上生效。
RETURN VALUE:返回值语义
该选项与所有 curl_easy_setopt 一致,返回 CURLcode:
CURLE_OK(0):设置成功;- 非零值:发生错误,具体错误码参见
libcurl-errors(3)。
需要特别指出一个非零返回的特例:在不支持 TFO 的平台(既无 CONNECT_DATA_IDEMPOTENT,也无 MSG_FASTOPEN / TCP_FASTOPEN_CONNECT)上,CURLOPT_TCP_FASTOPEN 会返回 CURLE_NOT_BUILT_IN(见 lib/setopt.c)。程序可以据此在运行时检测平台能力,选择优雅降级(例如忽略该错误继续传输,或记录日志)。
与其他选项的关系
该选项的 See-also 指向 CURLOPT_SSL_FALSESTART(命令行对应 --false-start)。两者目标一致——都是通过减少握手等待来降低首字节延迟,但机制不同:
- TFO 优化的是 TCP 层的握手(把数据塞进 SYN/SYN-ACK);
- False Start 优化的是 TLS 层的握手(客户端在收到 ChangeCipherSpec 之前就发送应用数据)。
两者可以视为"传输层 + 安全层"的双层加速组合思路,但同样都依赖服务端支持,且 TFO 会禁用 TLS 会话缓存,叠加使用时需结合实际网络与 TLS 会话复用策略权衡。
小结与最佳实践
| 要点 | 结论 |
|---|---|
| 选项名 | CURLOPT_TCP_FASTOPEN(CURLOPTTYPE_LONG,编号 244) |
| 引入版本 | 7.49.0 |
| 默认值 | 0(关闭) |
| 参数 | 1L 启用,0 关闭 |
| 命令行 | curl --tcp-fastopen <URL> |
| 支持平台 | Linux、macOS 10.11+(其他平台返回 CURLE_NOT_BUILT_IN) |
| 已知副作用 | TLS 会话缓存失效;部分网络环境下存在兼容性问题 |
| 生效前提 | 客户端与服务端此前已建立过连接(TFO Cookie),且网络链路支持 TFO |
最佳实践建议:
- 按需开启:仅在 RTT 较高、连接短命且服务端明确支持 TFO 的场景(如高频 API 调用、内部服务间通信)开启,不建议全局默认;
- 关注 TLS 会话复用:若业务强依赖 TLS 会话缓存/恢复降低握手开销,开启 TFO 反而得不偿失——二者在文档层面被明确标记为互斥;
- 做好降级:利用平台不支持时返回的
CURLE_NOT_BUILT_IN做运行时检测,在 macOS/Linux 之外的环境中平滑忽略该选项; - 实测验证:开启前后对比
curl -w "%{time_connect} %{time_appconnect} %{time_total}"的耗时输出,或在服务端抓包确认 SYN 中是否携带数据,避免在兼容性差的跨网链路上因 TFO 引入连接异常。
延伸阅读
- 选项官方文档:docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md
- 命令行文档:docs/cmdline-opts/tcp-fastopen.md
- 关联选项(TLS False Start):docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md
curl_easy_setopt总览:docs/libcurl/curl_easy_setopt.md- 源码实现:选项登记 lib/easyoptions.c、setopt 处理 lib/setopt.c、TCP 连接实现 lib/cf-socket.c