Tasmota 异步 HTTP/HTTPS 客户端 AsyncHttpClientLight 代码审查深度解析:架构、缺陷与 Berry webclient 集成
Tasmota 异步 HTTP/HTTPS 客户端 AsyncHttpClientLight 代码审查深度解析:架构、缺陷与 Berry webclient 集成
导读
AsyncHttpClientLight 是 Tasmota 仓库中一份由外部贡献者(HexaMaster)提交的、面向 ESP32 的自包含异步 HTTP/HTTPS 客户端实现,通过编译期开关 USE_BERRY_WEBCLIENT_ASYNC 作为 Berry webclient 类现有同步 HTTPClientLight 的替代后端,为遥测上报、RPC 长轮询等场景提供不阻塞 Berry VM 的非阻塞 GET/POST 能力。本文以仓库内代码审查文档 CODE_ANALYSIS.md 为骨架,结合库源码与 Berry 绑定实现,系统讲解该特性的功能定位、FreeRTOS 任务架构、审查中发现的 5 个致命缺陷、多个高/中危问题、代码质量风险,以及配套的使用手册(状态机、错误码、Berry API、最佳实践与完整示例),帮助读者在理解其设计意图的同时,准确评估其生产可用性边界。
一、它是什么:一个默认关闭的异步 webclient 后端
AsyncHttpClientLight 是一套独立的 ESP32 HTTP/HTTPS 客户端实现,位于 lib/libesp32/AsyncHttpClientLight/src/AsyncHttpClientLight.h 与 AsyncHttpClientLight.cpp(约 1600 行)。它与既有 Berry webclient 类集成,作为编译期可选的替代后端:
- 异步扩展 API:
async_get_start()、async_post_start()、async_state()、async_abort(); - TLS 公钥固定(public-key pinning):
tls_pin_pubkey()、tls_clear_pins()、tls_set_rsa_only()。
该特性默认关闭。在 my_user_config.h 中可以看到它被注释掉:
#define USE_BERRY // Enable Berry scripting language
// #define USE_BERRY_WEBCLIENT_ASYNC // Enable ASYNC webclient mode as an additional mode to standary berry webclient.
而绑定层 xdrv_52_3_berry_webclient.ino 通过该宏决定包含哪个头文件:
#ifdef USE_BERRY_WEBCLIENT_ASYNC
#include "AsyncHttpClientLight.h"
#else
#include "HttpClientLight.h"
#endif
审查结论明确指出:鉴于下面将要展开的缺陷状态,默认关闭是正确的决定("off by default... is the right call")。同时,既有同步 Berry 脚本的兼容性是有意保持的——同步 API 保持不变。
与 HTTPClientLight 的关系
文档强调,该实现是"独立实现,未复制任何源码"(源码头文件注释也声明 no source code was copied)。<HTTPClient.h> 仅被包含用于枚举/常量类型(如 followRedirects_t、transferEncoding_t、HTTPC_TE_*),传输层、解析与异步基础设施均为独立实现。
二、核心架构争议:每次请求一个 FreeRTOS 任务
审查文档指出的首要架构问题是:每一次操作——包括同步的 GET/POST/getString/writeToStream——都会派生一个新的 FreeRTOS 任务(WorkerTask),栈大小 12 KB(宏 ASYNCHTTP_WKR_STACK,默认 12288 字节,见 AsyncHttpClientLight.h),然后调用方在信号量上忙等(runJob)。
从源码 AsyncHttpClientLight.cpp 可以看到同步路径的完整流程:
int AsyncHttpClientLight::runJob(Job::Fn fn, void* arg) {
if (_busy) xSemaphoreTake(_busy, portMAX_DELAY);
Job job;
...
job.done = xSemaphoreCreateBinary();
...
BaseType_t ok = xTaskCreate(
&WorkerTask, "AHttpWkr",
ASYNCHTTP_WKR_STACK / sizeof(StackType_t),
&job, tskIDLE_PRIORITY + 1, &th);
...
while (true) {
if (xSemaphoreTake(job.done, pdMS_TO_TICKS(_waitSliceMs)) == pdTRUE) break;
delay(0); // feed WDT
}
...
return job.result;
}
文档对这一设计的评估要点:
- 同步调用是纯开销:主循环本来就要全程阻塞(在
xSemaphoreTake+delay(0)上自旋),却还要为每次请求支付 12 KB 栈 + 任务创建/销毁成本,毫无收益; - 异步调用才是合理的:它确实把阻塞 I/O 卸载到了工作线程;
- 成本模型偏重:每个 job 一个全新 12 KB 栈任务、低优先级(
tskIDLE_PRIORITY+1),对 ESP32 而言代价高昂,且与 Tasmota 惯用的主循环 /fast_loop协作式网络处理方式不符。
这是一项需要在该功能继续推进前进行讨论的中央设计决策。
三、阻断性缺陷(Critical,阻止合并)
审查文档给出 Status: Not mergeable as-is(当前状态不可直接合并),理由即下述 5 个可能导致设备崩溃/挂死的缺陷。
C1. 任务运行中销毁对象导致 Use-after-free(释放后使用)
~AsyncHttpClientLight() 调用 end()(内部执行 _transport->stop() + _transport.reset())并删除 _busy/_asyncDone,但从不中止或 join 正在运行的 worker 任务。
场景:如果 Berry webclient 对象在 async_state() 仍为 RUNNING 时被 GC 回收或 deinit(脚本丢弃引用、或错误地调用 close()/复用),worker 会持续解引用已释放的 self->_transport、self->_asyncBody 以及已删除的信号量——必然崩溃。
对应源码(析构函数):AsyncHttpClientLight.cpp
AsyncHttpClientLight::~AsyncHttpClientLight() {
end();
if (_currentHeaders) { delete[] _currentHeaders; _currentHeaders = nullptr; }
#ifdef ESP32
if (_asyncDone) { vSemaphoreDelete(_asyncDone); _asyncDone = nullptr; }
if (_busy) { vSemaphoreDelete(_busy); _busy = nullptr; }
#endif
}
修复建议:析构函数(以及 end()/deinit)必须首先置位 _asyncAbortReq,等待 worker 退出,再释放资源。
C2. 响应访问器在 RUNNING 期间被调用导致死锁
getString() / writeToStream() 仅在 _asyncState == ASYNC_DONE 时走快速路径;若在 RUNNING 期间调用,会落入 runJob() → xSemaphoreTake(_busy, portMAX_DELAY)。但 _busy 只会在 asyncState() 中、由同一(现已阻塞的)主线程释放——主循环永远挂起 → 看门狗(WDT)复位。
文档点评:"文档说'不要这样做',但一个库不应该因为误用就让设备死锁。"
C3. 同步响应体读取器无超时/无中止 → 死循环
writeToStreamDataBlock()(同步 getString、writeToStream、get_bytes、write_file、write_flash 共用)的循环如下(AsyncHttpClientLight.cpp):
while (_transport && _transport->connected() && (len > 0 || len == -1)) {
int avail = _transport->available();
if (avail <= 0) { delay(1); continue; } // no timeout, no abort check
...
}
在 identity 编码、keep-alive、且无 Content-Length(_size == -1)的响应下,若服务端保持 socket 打开却不再发送数据,循环将无限自旋。readme 虽承认了"identity with no data"风险,但只有异步路径(readBodyToStreamString,带 abort 标志与 16 KB 上限)做了防护;同步路径既无超时也无中止检查。
C4. 302/303 重定向转 GET 后残留过期的 Content-Length
在 Job_SendBuf/Job_SendStr 中,每次重定向迭代不会重置 _headers;Content-Length 仅在存在 payload 时(重新)添加。收到 302/303 时代码将 payload=nullptr/size=0 并切换为 GET,但先前注入的 Content-Length: N 仍留在 _headers 中,随无 body 的 GET 一起发送——服务端等待永远不会到来的 body → 挂起/超时。
相关:beginInternal()(通过 setURL() 处理绝对重定向目标时被调用)从不清除 _headers,与 readme 声称的"重定向后重置 headers"相矛盾。
C5. 后续同步调用返回过期的异步 body
_asyncState 在变为 DONE 后从不重置回 IDLE,同步 GET() 也不触碰它。一次异步任务结束后,在同一实例上执行同步 GET() 会填充 _size/transport,但 getString() 仍看到 _asyncState == ASYNC_DONE,于是返回旧的 _asyncBody。
修复建议:任何新请求(无论同步还是异步)都必须使 DONE 快速路径失效。
四、高/中危问题
H1. 从 bytes 发起的异步 POST 未拷贝 payload
asyncPOSTStart(uint8_t*, size) 只保存原始指针,worker 稍后才读取。Berry 绑定层通过把 bytes 对象藏入 .__async_hold 防止 GC(见 be_webclient_lib.c 的函数声明与绑定注册),但没有任何机制阻止脚本在任务运行期间修改/resize 该 bytes——这可能导致缓冲区重新分配,worker 读取已释放内存。String 重载是拷贝的(安全);缓冲区重载应当同样拷贝,或必须强制约定该契约。
H2. chunked 同步响应的无界内存增长
wc_getstring/wc_getbytes 用 if (sz >= 32767) 基于 getSize() 做防护,但 chunked 响应上报 _size == -1,防护被绕过,Job_GetString 会把整个 body 累积进 StreamString 且无上限 → 大 chunked 下载时 OOM。(异步路径上限 16 KB;同步路径没有。)
H3. 仅支持 IPv4 的 HTTP 传输
AsyncTcpAdapter 使用 sockaddr_in / AF_INET 与 (in_addr_t)ip(见 AsyncHttpClientLight.cpp)。Tasmota 支持 IPv6,此前基于 WiFiClient 的路径也支持;纯 HTTP 异步在 IPv6 下不可用。
M1. TLS 发送缓冲区实际仅约 85 字节
new BearSSL::WiFiClientSecure_light(16384, 0) → setBufferSizes(recv, xmit) 得到 _iobuf_out_size = 0 + MAX_OUT_OVERHEAD(85)。即 16 KB 接收缓冲区(堆占用重、一次性分配)搭配近零发送缓冲区(每条 TLS 记录几乎不带应用数据——POST 吞吐差)。Tasmota 通常使用均衡尺寸(如 1024/1024)。需要调优。
M2. SO_LINGER RST-close 无条件且激进
AsyncTcpAdapter::stop() 总是设置 l_onoff=1, l_linger=0(见 AsyncHttpClientLight.cpp),每次关闭都强制 TCP RST 以削减 TIME_WAIT。这可能丢弃未读数据,在对端表现为连接重置。作为选项尚可,作为无条件默认值则值得商榷。
M3. 默认 HTTPS 不认证
无 pin 时,BearSslAdapter 调用 setPubKeyFingerprint(any, any, allow_all=true)——接受任意服务器密钥(MITM 开放)。这匹配现有 Tasmota _light 行为,因此不算回归;但结合 SHA-1 公钥 pinning,应清楚文档化"安全需要显式 pinning"。
五、代码质量与流程问题
- 许可证不一致:源码头文件声明
GPL-3.0-or-later(见 AsyncHttpClientLight.h),而 library.json 写的是"license": "MIT"。合并前必须调和。 library.json描述失实:description 写 "Async extension for HttpClientLight by Stephan Hadinger" 错误归属了作者;且authors字段是单个对象而非 PlatformIO 期望的数组(见 library.json)。- 非英文注释与拼写错误:全库存在斯洛伐克语/捷克语注释(如 "telo"、 "drž payload, aby ho GC nevyhodil kým beží job"、"za chunkom")及拼写错误("wheen"、"writin"、"succesful"、"contetn-length"、"metho")。Tasmota 上游要求全英文。
- 大量
#ifdef USE_BERRY_WEBCLIENT_ASYNC分叉:在xdrv_52_3中约 20 个重复的wc_getclient块(搜索结果显示该宏在 xdrv_52_3_berry_webclient.ino 中出现 20+ 处)。用单个 typedef/helper 选择客户端类型几乎可以消除全部重复,显著缩小 diff。 asyncState()声明为const却const_cast掉this以修改状态并释放资源——签名具有误导性(见 AsyncHttpClientLight.cpp)。- Worker 任务名为固定字符串(
"AHttpWkr"/"AHttpWkrA"),多个并发客户端会重名(无害,但具象征性)。
六、确实做得好的部分
审查并非全盘否定,文档明确列出了经交叉验证(含 WiFiClientSecureLightBearSSL)后确认的正常部分:
- lwIP 非阻塞 connect +
select()超时(见 AsyncHttpClientLight.cpp); - 与
HTTPClientLight对齐的错误码表(-1..-11); - chunked / identity 解码;
- 带中止感知的异步 body 读取器 + 16 KB 硬上限(
kAsyncBodyLimit,见 AsyncHttpClientLight.h); - 通过
.__async_hold持有 Berry payload 防止 GC; - 跨线程结果交接顺序正确:worker 在
xSemaphoreGive之前写结果,主线程在xSemaphoreTake之后读结果,因此只要遵循文档规定的调用序列,发布的_asyncHttpCode/_asyncRxBytes/_asyncBody不存在数据竞争; - 特性默认关闭,定位恰当。
七、配套使用手册:状态机、错误码与 Berry API
readme(readme.txt)附带完整使用手册,与审查文档配套,构成对该特性的实操认识。
异步状态机(async_state() 返回值)
| 值 | 常量 | 含义 |
|---|---|---|
| 0 | ASYNC_IDLE |
无任务运行(对象创建后、出错后、完成后) |
| 1 | ASYNC_RUNNING |
请求进行中 |
| 2 | ASYNC_DONE |
已完成,body 在内部缓冲区可用 |
| 3 | ASYNC_ERROR |
错误(HTTP 客户端/传输层) |
| 4 | ASYNC_ABORTED |
被用户中止 |
每次调用 async_state() 后,last_code(HTTP 状态码或负错误码)与 last_rx(异步接收字节数)可用。注意:RUNNING 期间不要调用 begin();要打断运行中的任务,先 async_abort(),再至少调用一次 async_state()。对应枚举定义见 AsyncHttpClientLight.h。
错误码(负值,与 HTTPClientLight 对齐)
| 值 | 常量 | 含义 |
|---|---|---|
| -1 | HTTPC_ERROR_CONNECTION_REFUSED |
连接被拒绝 |
| -2 | HTTPC_ERROR_SEND_HEADER_FAILED |
发送请求头失败 |
| -3 | HTTPC_ERROR_SEND_PAYLOAD_FAILED |
发送 payload 失败 |
| -4 | HTTPC_ERROR_NOT_CONNECTED |
未连接 |
| -5 | HTTPC_ERROR_CONNECTION_LOST |
连接丢失 |
| -6 | HTTPC_ERROR_NO_STREAM |
无流 |
| -7 | HTTPC_ERROR_NO_HTTP_SERVER |
无 HTTP 服务器 |
| -8 | HTTPC_ERROR_TOO_LESS_RAM |
RAM 不足 |
| -9 | HTTPC_ERROR_ENCODING |
不支持的传输编码 |
| -10 | HTTPC_ERROR_STREAM_WRITE |
流写入错误 |
| -11 | HTTPC_ERROR_READ_TIMEOUT |
读取超时 |
宏定义与 errorToString() 的文本映射见 AsyncHttpClientLight.h 与 AsyncHttpClientLight.cpp。
Berry webclient API 一览
- 初始化与安全:
d = webclient();d.tls_pin_pubkey(fp1[, fp2])(SHA-1 指纹,格式 "AA:BB:…:FF" 或 40 位十六进制);d.tls_clear_pins();d.tls_set_rsa_only(bool)。 - 参数与连接:
d.set_useragent(ua_str);d.set_timeouts(http_timeout_ms, tcp_connect_timeout_ms);d.set_follow_redirects(bool)(true = 严格模式);d.begin(url)(重置 headers、设置 URL、可选重建 transport);d.add_header(name, value[, first=false[, replace=true]])(别名d.addheader(...));d.close();d.connected()。 - 同步 HTTP(阻塞):
GET()、POST(str|bytes)、PUT、PATCH、DELETE→ 返回 int http_code。 - 异步 HTTP(非阻塞核心):
async_get_start()(1=已启动,0=忙,<0=错误);async_post_start(str|bytes);async_state()(返回 0..4 并填充 last_code/last_rx);async_abort()(向 worker 发信号,完成通过async_state()观察)。 - 访问响应:
get_string()、get_bytes()、get_size()、write_file(path)、write_flash(addr)(仅 ESP-IDF<5/Tasmota)。 - Headers 生命周期:
begin()删除全部自定义 headers;init、改 URL、出错后需重加(如Content-Type);连续成功请求之间无需再begin()或重复加 headers。
这些绑定在 xdrv_52_3_berry_webclient.ino 中实现,类方法注册于 be_webclient_lib.c。
最佳实践(遥测 / RPC)
- 超时:遥测推荐
set_timeouts(4000, 3000);弱链路用 6000/4000。 - 重试/中止:看到
RUNNING (1)且不想等,用async_abort()→async_state()→ 尝试新的async_post_start(...)。 - 重新 begin:仅出错后(
last_code < 0)、改 URL/UA/pins 后、或想重置 headers 时。 - 服务端响应:应返回
Content-Length或 204(CL=0),避免"identity with no data"(对端静默保持 socket 打开)。 - 长轮询:RPC GET 用较长 HTTP 超时(如 15000),connect 可保持 3000–4000。
典型应用场景
- 加密周期遥测(HTTP(S) + 本地 MQTT):一个 endpoint 一个 client,
begin()一次,加Content-Type: application/json,调度器里调async_post_start(payload),偶尔async_state()发布 last_code/last_rx 并清理。Berry VM 保持响应,无长阻塞写。大上传/下载回退到同步流式(write_file、get_bytes)。 - RPC 长轮询(如 ThingsBoard):异步 GET 保持长轮询打开(如
?timeout=60)而非每几秒重连。async_state()返回 DONE 时解析 body 执行命令(可选异步 POST 回复),随后立即发起下一次长轮询;返回 RUNNING 时什么都不做(连接保持打开),VM 空闲处理其他任务——降低连接抖动与 TIME_WAIT 压力,消除此前同步阻塞模式导致的 VM 停滞。
Berry 示例(来自 readme)
异步 POST(一次性):
var d = webclient()
d.tls_set_rsa_only(true)
d.tls_pin_pubkey(syscfg.fingerprint1, syscfg.fingerprint2)
d.set_timeouts(4000, 3000)
d.set_useragent("MSBNode/1.0")
d.begin("https://example.com/api/v1/telemetry")
d.add_header("Content-Type","application/json")
var rc = d.async_post_start(json.dump({"k":"v"}))
状态检查(例如放在 tick 中):
var st = d.async_state()
if st != 1
var code = d.last_code
if code == 200 || code == 204
var body = d.get_string()
end
end
异步 GET(长轮询发起):
var d = webclient()
d.tls_set_rsa_only(true)
d.tls_pin_pubkey(syscfg.fingerprint1, syscfg.fingerprint2)
d.set_timeouts(15000, 3000)
d.set_useragent("MSBNode/1.0")
d.begin("https://example.com/api/v1/rpc?timeout=10")
var s = d.async_get_start()
tick 中的干净处理:
var st = d.async_state()
if st == 2
var code = d.last_code
var body = d.get_string()
end
中止并立即重启(无需 begin):
var st = d.async_state()
if st == 1
d.async_abort()
d.async_state()
var r = d.async_post_start(json.dump({"k":"v"}))
end
出错后重新 begin:
var st = d.async_state()
if d.last_code < 0 && st != 1
d.close()
d.begin("https://example.com/api/v1/telemetry")
d.add_header("Content-Type","application/json")
end
关键 FAQ
- 每次 POST/GET 前都要
begin()吗?否。仅在初始化/变更/出错后。 - headers 何时消失?总是在
begin()之后,然后重新添加。 RUNNING (1)会永远挂起吗?实践中不会(有超时);"identity with no data"边界情况可由async_abort()打破。RUNNING期间close()+begin()有用吗?没有。资源仅在完成/中止后通过async_state()释放。tls_pin_pubkey设置一次够吗?够,按实例持久,直到clear_pins()或对象销毁。
八、附带的测试计划与风险评估
readme 给出了明确的测试计划与风险边界:
测试计划
- 同步:GET 大二进制 →
write_file();校验大小/hash;chunked 与 identity 两种编码。 - 异步:burst
async_post_start()+ 周期async_state();检查 last_code/last_rx、堆稳定、无 WDT。 - 重定向:验证 301/302/303/307 及 header 重置行为(注:审查 C4 恰恰指出 header 重置未按计划工作)。
- TLS:正确 vs 错误指纹;对 ECDSA 证书开 RSA-only(应失败)。
风险
- 仅 ESP32 路径;HTTPS 依赖既有 BearSSL light;
- 行为变更局限于 webclient 后端;公开同步 API 保持不变。
九、结论与使用建议
AsyncHttpClientLight 展示了一个方向正确的设计尝试:为 Berry 脚本提供 WDT 友好的非阻塞 HTTP(S) 传输,降低 TIME_WAIT 压力,并加入 TLS 公钥固定这类安全增强。然而,代码审查给出的结论是明确的——当前状态不可合并:
- **5 个阻断性缺陷(C1–C5)**均可能造成设备崩溃或死锁,其中 C1(use-after-free)、C2(死锁)风险最高;
- 架构层面,"每次请求一个 12 KB FreeRTOS 任务"的成本模型与 Tasmota 主循环协作式的网络惯例不符,值得在合并前重新讨论;
- 同步路径缺失超时/上限防护(C3、H2)、IPv4-only(H3)、TLS 缓冲区失衡(M1)、默认不认证(M3)等问题需要系统性整改;
- 许可证不一致与元数据错误必须在合入上游前修正。
对使用者而言,该特性当前处于默认关闭状态,属于评估中的候选代码;若要在自定义固件中试验,需在 my_user_config.h 打开 USE_BERRY_WEBCLIENT_ASYNC,并严格遵守 readme 的操作纪律(每次异步任务后至少调用一次 async_state()、RUNNING 期间不 begin()/close()、服务端尽量返回 Content-Length 或 204)。在 C1–C5 修复并合入上游之前,生产固件应继续使用默认的同步 HTTPClientLight 后端。