Tasmota 异步 HTTP/HTTPS 客户端 AsyncHttpClientLight 代码审查深度解析:架构、缺陷与 Berry webclient 集成

原创2026-09-12 19:02:331,887 阅读
文章标签:物联网智能家居嵌入式固件IoT协议硬件开发边缘网关

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。

典型应用场景

  1. 加密周期遥测(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)。
  2. 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 公钥固定这类安全增强。然而,代码审查给出的结论是明确的——当前状态不可合并:

  1. **5 个阻断性缺陷(C1–C5)**均可能造成设备崩溃或死锁,其中 C1(use-after-free)、C2(死锁)风险最高;
  2. 架构层面,"每次请求一个 12 KB FreeRTOS 任务"的成本模型与 Tasmota 主循环协作式的网络惯例不符,值得在合并前重新讨论;
  3. 同步路径缺失超时/上限防护(C3、H2)、IPv4-only(H3)、TLS 缓冲区失衡(M1)、默认不认证(M3)等问题需要系统性整改;
  4. 许可证不一致与元数据错误必须在合入上游前修正。

对使用者而言,该特性当前处于默认关闭状态,属于评估中的候选代码;若要在自定义固件中试验,需在 my_user_config.h 打开 USE_BERRY_WEBCLIENT_ASYNC,并严格遵守 readme 的操作纪律(每次异步任务后至少调用一次 async_state()、RUNNING 期间不 begin()/close()、服务端尽量返回 Content-Length 或 204)。在 C1–C5 修复并合入上游之前,生产固件应继续使用默认的同步 HTTPClientLight 后端。

登录后查看全文
Tasmota