人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载libwebsocketslws为 HTTP/2 提供了一种名为 immortal stream不朽流的长轮询能力让服务器可以向已半关闭的客户端流持续单向推送数据且不受常规空闲超时约束。本文以 third_party/libwebsockets/READMEs/README.h2-long-poll.md 为核心结合仓库内的源码实现与配套示例完整讲解服务端如何开启 h2 long poll、客户端如何切换为只读长轮询模式以及底层超时豁免机制的工作原理读完即可在 lws 服务端/客户端中落地这一单向实时推送方案。h2 long poll 与 immortal stream核心概念在标准 HTTP/2 语义中流由客户端发起任意一方发送带有END_STREAM标志的帧后该方向即进入 half-closed 状态最终流会关闭并释放资源。而 lws 的 h2 long poll 通过引入immortal stream概念让部分流超脱常规超时管理服务端和客户端都可以承载 immortal 流这些流不受常规超时约束可以长时间存活这些流对客户端而言是只读的read-only to the client即数据方向固定为 server - client服务端可随时向流内写入数据客户端只需持续接收只要某条网络连接上至少存在一条 immortal 流整条连接本身也不受超时影响直到它所承载的最后一条 immortal 流关闭为止。需要注意的是正因为连接与流都不会因空闲而被超时回收文档特别建议应当有另外的机制来确认客户端仍然存活例如应用层心跳、客户端定时重连或业务层面的活动上报否则可能出现服务端长期维持一条早已无人的僵尸连接。这一机制与仓库中另一处面向 SSE 的lws_http_mark_sse()见 lws-http.h共享同一套底层 immortal 标记逻辑可见 lws 将连接上存在需要长期存活的流统一抽象为不朽流来管理超时。服务端开启 h2 long poll允许客户端接入 immortal 流的服务端 vhost必须在vhost 创建时设置选项标志LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL。该标志定义于 lws-context-vhost.h#define LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL (1ll 32)在lws_context_creation_info的info.options中直接置位即可例如仓库示例 minimal-http-server-h2-long-poll/minimal-http-server.c 的做法info.options LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT | LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL | LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE;JSON 配置等价写法如果通过 JSON 配置文件创建 vhostlws 的 lejp-conf 解析路径等价配置是在对应 vhost 上设置h2-half-closed-long-poll: 1该 JSON 键vhosts[].h2-half-closed-long-poll被注册在 lejp-conf.c 的配置路径表中解析时经LEJPVP_FLAG_H2_HALF_CLOSED_LONG_POLL分支lejp-conf.c调用set_reset_flag置位LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL。因此对纯 JSON 配置驱动的部署只需这一行即可无需改动代码。服务端底层行为开启该选项后当服务端 vhost 收到客户端发来的 HEADERS 帧时h2 解析器会在 http2.c 中检查该选项if (lws_check_opt(h2n-swsi-a.vhost-options, LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL)) { /* * We dont directly timeout streams that enter the * half-closed remote state, allowing immortal long * poll */ lws_mux_mark_immortal(h2n-swsi); lwsl_info(%s: %s: h2 stream entering long poll\n, __func__, lws_wsi_tag(h2n-swsi)); } else { h2n-swsi-h2.END_STREAM !!(h2n-flags LWS_H2_FLAG_END_STREAM); ... }也就是说开启选项后凡是进入 half-closed remote 状态的 h2 流都会被直接标记为 immortal不再按常规 END_STREAM 语义关闭与超时。这正是服务端只需要设置一个选项其余全部交给 lws的根本原因。客户端流切换为 long poll 模式客户端侧通过一个专用 API 让已建立的 h2 客户端流转入 immortal 只读模式int lws_h2_client_stream_long_poll_rxonly(struct lws *wsi);该 API 的完整契约声明见 lws-http.h它会向服务端发送一个带END_STREAM标志的零长度 DATA 帧将本地流置为 half-closed (local)、对端置为 half-closed (remote)同时把客户端流标记为 immortal不受超时约束从而进入可以无限期等待接收数据的只读状态。返回 0 表示异步切换流程已启动若当前 wsi 不是 h2 流则返回非零。底层实现路径调用入口在 http2.cint lws_h2_client_stream_long_poll_rxonly(struct lws *wsi) { if (!wsi-mux_substream) return 1; /* * Elect to send an empty DATA with END_STREAM, to force the stream * into HALF_CLOSED LOCAL */ wsi-h2.long_poll 1; wsi-h2.send_END_STREAM 1; lws_callback_on_writable(wsi); return 0; }它并不立即发送数据而是设置h2.long_poll与h2.send_END_STREAM两个标志字段定义见 private-lib-roles-h2.h并请求可写回调。真正发送发生在 ops-h2.c 的 POLLOUT 处理中if (w-h2.send_END_STREAM w-h2.long_poll) { uint8_t buf[LWS_PRE 1]; enum lws_write_protocol wp 0; if (!rops_write_role_protocol_h2(w, buf LWS_PRE, 0, wp)) { lwsl_info(%s: %s: entering ro long poll\n, __func__, lws_wsi_tag(w)); lws_mux_mark_immortal(w); } else lwsl_err(%s: %s: failed to set long poll\n, __func__, lws_wsi_tag(w)); goto next_child; }注意这里以零长度载荷调用 h2 写角色协议实际产出即文档所述的零长度 DATA END_STREAM帧成功后随即调用lws_mux_mark_immortal()。此外在 ops-h2.c 的写角色入口中immortal 流mux_stream_immortal为真被豁免于普通写状态检查保证半关闭后的流仍可继续写数据。超时豁免的底层机制lws_mux_mark_immortalimmortal 状态的核心实现在 wsi.cvoid lws_mux_mark_immortal(struct lws *wsi) { struct lws *nwsi; lws_set_timeout(wsi, NO_PENDING_TIMEOUT, 0); if (!wsi-mux_substream !wsi-client_mux_substream) { lwsl_wsi_err(wsi, not mux substream); return; } if (wsi-mux_stream_immortal) /* only need to handle it once per child wsi */ return; nwsi lws_get_network_wsi(wsi); if (!nwsi) return; wsi-mux_stream_immortal 1; assert(nwsi-immortal_substream_count 255); nwsi-immortal_substream_count; if (nwsi-immortal_substream_count 1) lws_set_timeout(nwsi, NO_PENDING_TIMEOUT, 0); }要点拆解流自身豁免lws_set_timeout(wsi, NO_PENDING_TIMEOUT, 0)直接取消子流上的待处理超时连接级豁免网络连接 wsi 上维护immortal_substream_count计数上限 255标记某条流 immortal 时计数加一当计数从 0 变为 1 时连接本身的超时也被取消。因此连接包含至少一条 immortal 流时不超时这一规则由该计数精确实现幂等保护mux_stream_immortal标志保证同一子流只处理一次避免重复计数常规超时恢复在 http2.c 中网络 wsi 的 keepalive 超时仅在immortal_substream_count 0时才会被设置if (!wsi-immortal_substream_count) lws_set_timeout(wsi, PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE, wsi-a.vhost-keepalive_timeout ? wsi-a.vhost-keepalive_timeout : 31);即默认空闲连接约 31 秒或 vhost 配置的keepalive_timeout就会被关闭但只要存在不朽流连接就一直存活——示例程序中每 60 秒推送一次时间戳、连接却永不超时正是靠这条逻辑成立的。实战验证示例应用跑通 long poll仓库内置了配套的完整示例可直接验证整个流程。服务端minimal-http-server-h2-long-poll示例位于 third_party/libwebsockets/minimal-examples/http-server/minimal-http-server-h2-long-poll其构建与运行方式见该目录下的 README.md$ cmake . make $ ./lws-minimal-http-server运行后服务端监听7681 端口TLS 构建时使用目录内自带的localhost-100y.cert/localhost-100y.key自签名证书。其核心逻辑在 minimal-http-server.cLWS_CALLBACK_HTTP中先输出 HTTP 200 响应头LWS_ILLEGAL_HTTP_CONTENT_LEN即不带 Content-Length 的流式响应随后立即调度定时器通过lws_sul_schedule每60 秒60 * LWS_US_PER_SEC见第 49-50 行触发一次sul_cb置位pss-pending并调用lws_callback_on_writable在LWS_CALLBACK_HTTP_WRITEABLE中把当前时间戳lws_now_usecs()写入流第 85-95 行。60 秒远大于默认的约 30 秒空闲回收阈值因此连接能持续存活本身就是 immortal 生效的直接证据示例同时提供了-v参数将默认的 5m/5m10s 有效性检查收紧为 5s/10s见第 141-144 行与retry结构用于更激进地验证超时豁免。客户端minimal-http-client在另一个终端构建常规客户端示例并带参运行$ cmake . make # 在 minimal-examples/http-client/minimal-http-client 目录 $ ./lws-minimal-http-client -l --long-poll参数含义见 minimal-http-client.c-l连接本地localhost:7681并允许自签名证书LCCSCF_ALLOW_SELFSIGNED第 245-248 行--long-poll置位long_poll标志第 238-241 行要求使用 h2连接建立时 ALPN 为h2,http/1.1第 261 行并设置LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM等 h2 兼容选项第 257-259 行。客户端在LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP回调中执行切换第 100-105 行if (long_poll) { lwsl_user(%s: Client entering long poll mode\n, __func__); lws_h2_client_stream_long_poll_rxonly(wsi); }随后在LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ中打印收到的长轮询数据第 144-151 行long poll rx: ...。运行后即可观察到客户端连上服务端、进入 immortal 模式之后服务端每分钟推送一次时间戳连接在远超常规超时时间的情况下持续保持在线。验证要点服务端日志出现h2 stream entering long pollhttp2.c客户端日志出现Client entering long poll mode与周期性的long poll rx: 长度 时间戳等待超过默认的 30 秒空闲超时窗口以及使用-v收紧后的 5s/10s 窗口连接仍不断开——这是 immortal 生效的最直接验证。使用注意事项活性确认immortal 流与所在连接都不再受超时约束必须自备应用层心跳或客户端活动上报避免僵尸连接长期占用资源单向语义long poll 流对客户端只读客户端若要再发数据需另行建立流或连接不能复用该半关闭流服务端必须显式开启只有 vhost 设置了LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL或 JSON 的h2-half-closed-long-poll: 1客户端发起的半关闭流才会被服务端标记为 immortal否则按标准 h2 语义处理流可能很快关闭非 h2 流保护lws_h2_client_stream_long_poll_rxonly()会检查mux_substream对非 h2 子流直接返回非零不会误操作计数上限单条网络连接的immortal_substream_count上限为 255wsi.c设计长期轮询规模时应留意连接聚合策略。综上lws 的 h2 long poll 用一个服务端选项 一个客户端 API即完成了对 HTTP/2 半关闭流的超时豁免与单向推送改造配合lws_mux_mark_immortal的流级/连接级两级计数管理非常适合在 h2 之上实现类似服务端每分钟或按事件推送一次状态、客户端长期挂机等待的轻量实时场景。相关源码均可在本仓库的 third_party/libwebsockets/lib/roles/h2 与 third_party/libwebsockets/lib/core-net/wsi.c 中继续深入研读。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐JavaScript教程深入理解长轮询(Long Polling)技术JavaScript教程深入理解长轮询 Long Polling 技术 什么是长轮询 长轮询 Long Polling 是一种简单而有效的服务器 客户端通信技PicoClaw VK 渠道实战指南基于 VK 社区 Bots Long Poll 的机器人接入与配置PicoClaw VK 渠道实战指南基于 VK 社区 Bots Long Poll 的机器人接入与配置 PicoClaw 的 VK 渠道通过 VK 的 Bot人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆libuv FS Poll 句柄uv_fs_poll_t完全指南基于 stat 轮询的跨平台文件变更监控libuv FS Poll 句柄uv_fs_poll_t完全指南基于 stat 轮询的跨平台文件变更监控 uv_fs_poll_t 是 libuv 提供的网络通信异步编程上一篇如何彻底卸载Vantage拯救者工具箱终极指南下一篇OBS动态缩放与鼠标跟踪终极指南让你的直播细节更出众创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考