nixevol/NixMsg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[K-03][critical] Python SDK：没关 paho 自动重连导致被顶号后两端互踢、回调在锁下执行会死锁、断线后发送挂起、async 回调不被等待就确认 #60

New Issue
Closed
opened 2026-09-30 13:57:07 +08:00 by nixevol · 2 comments
nixevol commented 2026-09-30 13:57:07 +08:00
Owner
Copy Link
Copy Source

编号：K-03　严重级：critical　工作线：SDK（sdk/*）　来源：审查 S-01、S-03、S-05、S-06、S-10、S-12、S-13、S-14、S-15、S-17、S-18、S-19
依赖：K-00 (#57)（对外语义条目）　被依赖：无

结论与统一方案

本 issue 汇总涉及 Python SDK 的条目，由 Python SDK 负责人一次改完（集中在 client.py、transport.py、async_client.py）。下方"问题明细"是跨四套的原文，请只看 Python 的部分。

条目 严重级 Python SDK 的改法
S-03 paho 2.x 默认自动重连未关闭：被顶号后两端约每秒互踢、认证失败后后台持续重试（已真机复现） critical 创建 client 时传 reconnect_on_failure=False；在 taken_over 与认证失败分支里（异步）调 transport.disconnect()；修正 DEVIATIONS S2-PY/JAVA 1–3 第 6 条的错误描述
S-01 断线后已发出的发送永不重交、调用可永久阻塞 critical 断线且将重连时把在途条目 pending.rid=""、重算在途数，按原 id 重交
S-05 回调在不可重入的 _cb_lock 下执行，on_connection 还持 _lock；存在 ABBA 死锁（已复现） high 锁内只记录状态变化，锁外由单一线程按序派发回调
S-06 自动确认失败被吞、重复回执不 ack、手动 ack() 失败不报错 high 回调成功即置为 acked 再 ack；重复回执同样发 receipt_ack（可节流）；手动 ack 失败抛异常
S-10 send_at_ms 原样透传，语义未说明 medium 文档注明 send_at_ms 是服务器时间，send_at 是本机时间并做偏差校正
S-12 fatal 与断线的处理顺序导致先报 session_invalid 再报真实原因 medium 收包路径识别 fatal 后立即置停止标志、失败发送与挂起请求、只报一次原因
S-13 断线时挂起请求要等满 60 秒 medium 断线钩子以 not_connected 立即失败非发送请求
S-14 rate_limited 后立即重交形成热循环 medium 按 K-00 的退避参数
S-15 断线后立即重连、闪断不抬升退避 medium 按 K-00 (#57) 修订后的"重连退避"算法实现（不要照搬 JS 现有代码，它有双重翻倍，见 K-02 (#59)）
S-16 / S-24 对外语义 medium / low 按 K-00 统一（错误码、queue_full、只返回 data、sendAt+delay 报错、停止后 send 立即失败、取消语义）
S-17 AsyncClient 接受 async 回调却不 await，消息被直接确认 medium connect 时记录事件循环；遇到协程函数用 run_coroutine_threadsafe(...).result() 执行，抛错不 ack；同步 Client 收到协程返回值时报错
S-18 https 走明文、mqtt:// 未开启也走裸 TCP low 按 K-00 的 URL 映射
S-19 离线入队的帧不检查整帧大小 low 入队和 drain 前都检查
S-23 工程问题（Python 部分） low 假传输不从 __init__.py 导出
补充：logout() 吞掉请求失败（client.py:231-235 的 except Exception: pass），离线时服务端没有作废令牌，应用却以为已经退出 medium 按 K-00 (#57) 新增的"logout"一行：本地照常停止重连、清空令牌、结束队列、断开传输，但把请求失败抛给调用方

标"补充"的条目来自第二轮 SDK 审查，总审查人已对照代码核实，证据写在条目里（没有对应的原文段落）。

改动文件

sdk/python/src/nixmsg/client.py、transport.py、async_client.py、protocol.py、__init__.py，sdk/python/tests/*，README。

与其他问题的交互 / 冲突说明

  • 只改 sdk/python；对外语义条目以 K-00 为准。
  • 测试结束后删除本地 .venv 等产物。

验收与测试

  • test_10_kick_no_reconnect 改为被顶号后 5 秒内每 0.2 秒采样，状态始终不翻转；错误密码场景 10 秒内只有 1 次连接尝试。
  • 在回调里调 close / logout / send / 改密 / 手动 ack：2 秒内返回。
  • 断线重连后在途发送以原 id 重交并完成。
  • async 回调成功时 ack 在回调完成之后发出；回调抛错时不 ack。
  • 连续回 3 次 rate_limited，重发间隔约为 1、2、4 秒。
  • 退避单测（比较去掉抖动的标称值）：连续失败 6 次，间隔为 1、2、4、8、16、30 秒；断线后第一次重连约 1 秒。
  • 离线时调用 logout()：抛出请求错误，之后不再重连。

问题明细（各区审查原文，证据含文件与行号）

以下是本次复审各区审查报告的原文段落。A、M、I、P、S 开头的是原始发现编号（A 管理后台与网页、M 消息核心、I 身份认证群在线、P 传输平台部署、S SDK）。解决方案以本 issue 上方的"结论与统一方案"为准；原文里的方案与之不一致时，按上方执行。

[S-01] 断线时已发出、未收到 resp 的发送永不重交，调用方挂起，在途额度泄漏（Go / JS / Python / Java）

  • 严重级：critical
  • 分类：逻辑 / 与PRD不符
  • 现象与影响：发送帧 publish 后、resp 回来前断线，这一条会一直标记为“在途”。重连后的 drain/pump 只挑未在途的条目，所以永不按原消息号重交。
    • 调用方挂起情况：Go 的 Send 在 ctx 没有截止时间时永久阻塞；JS 的 Promise 永远不会完成；Python 调用时若已在线，会 wait(timeout=None) 永久阻塞；Java 等 1 小时后抛 busy，但条目仍留在队列里。
    • 在途计数永不回退：累计 100 次后该进程再也发不出消息，最终队列报满。
    • JS 更严重：MQTT.js 在 reconnectPeriod:0 下，非主动断开时只清掉 volatile 回调，QoS1 publish 的回调永不触发，所以在 PUBACK 之前断线也会卡住。
    • Java：PUBACK 之前断线时，pumpSends 直接把这条发送判为失败并出队，不会重交。
  • 证据：
    • Go：send.go:170-180（publish 成功后 rf := <-ch 既无超时，也没有断线出口）、send.go:141-153（只挑 !it.inflight）、connect.go:57-64（OnOffline 没有处理在途条目）。
    • JS：client.ts:494-543、client.ts:174-177、mqtt.ts:93-99（断线后新建 client，不 end 旧的）；MQTT.js client.js:380-384、:882-904、:985-987、:490-496。
    • Python：client.py:861-873（只挑 rid==""）、client.py:605-640、client.py:323。
    • Java：Client.java:1000-1006、Client.java:1019-1029（publish 抛异常就判失败并出队）、Transport.java:383-391。
  • 文档依据：
    • PRD F19：“重连后按原消息号再交；已经发出但没等到结果的也一样”。
    • DEVELOPMENT 9 发送：“包括已发出但没收到 resp 的……重连后按原消息号、原请求内容再交”。
    • DEVELOPMENT 5：“提交成功但还没发出 resp 就断线时，客户端用同一消息号重试”。
  • 为何不是故意设计：DEVIATIONS 没有相关条目；各 SDK 的注释都写着“网络错误：保留队列”，意图就是重交。
  • 解决方案：
    1. 在“断线且将重连”的钩子里遍历发送队列：删除 pending rid，置回未在途（Python/Java 设 pending.rid=""），按实际状态重算在途数；帧内容保持原样（原 id、原 send_at_ms）。服务器按消息号防重，会返回原结果。
    2. Go 的 dispatchSend 改为 select 三路：ch、每次连接一个的 connGone、c.ctx.Done()。
    3. JS 在 close 事件里对旧 client 调 end(true)，并加 generation 编号，防止同一条被重复完成。
    4. Java 的 publish 失败在未停止重连时回退为未在途，不判失败。
    5. 可选：等 resp 超时（如 60 秒）也按原 id 重交，兜底 mochi 在 inflight 满时静默丢弃的 resp。
  • 改动文件：sdk/go/send.go、connect.go；sdk/js/src/client.ts、mqtt.ts；sdk/python/src/nixmsg/client.py；sdk/java/.../Client.java
  • 与其他模块的交互/冲突风险：不需要服务端配合（依赖已有的消息号防重）。和 S-13 改的是同一个断线钩子。
  • 需补测试：假传输中 publish 后不回 resp，模拟断线重连，断言以同 id、同 send_at_ms 重发并完成；循环 150 次后仍能发送；Java 模拟 publish 抛异常，断言重交而非失败。
  • 置信度：代码阅读确定；MQTT.js 行为已按库源码核对。

[S-03] Python 没关 paho 自带的自动重连：被顶号后互踢，认证失败后后台持续重试（Python）

  • 严重级：critical
  • 分类：逻辑 / 与PRD不符
  • 现象与影响：PahoClient(...) 没有传 reconnect_on_failure=False（paho 2.x 默认开启）。SDK 在被顶号或认证失败时只改自己的标志，不断开底层 paho client，于是 paho 会用创建时的凭据自己重连。
    • 首次用密码登录的连接，paho 持有的是密码：1 秒后它用密码重新登录，把新设备顶掉，新设备又顶回来，两端无限互踢。每次都是新的密码登录，会换令牌、跑 argon2，双方反复收到 onSession。
    • 认证失败后，paho 用错误凭据按 1/3/7/15…秒持续重试，计入登录锁定次数，并反复触发 auth_failed 回调。
  • 证据：
    • 代码：transport.py:208-213、client.py:605-631；paho 2.1.0 client.py:741（默认开启）、:2315-2328（loop_forever 自动重连）、:4018-4039（收到 DISCONNECT 不改状态）。
    • 真机复现（临时编译 nixmsg，监听 127.0.0.1:0，数据放临时目录，结束后已删除）：c1、c2 用同一编号先后登录后，状态约每 1.03 秒翻转一次，持续 8 秒直到关闭。
    • 错误密码复现：connect 之后在 1.09 秒、3.11 秒、7.13 秒又出现 auth_failed。
    • 现有的 test_10_kick_no_reconnect 在 2.5 秒采样，恰好落在互踢周期回到初始状态的时刻，属于偶然通过。
  • 文档依据：PRD F02 验收“A 被踢下线且不再重连，B 可用”，D13、D28；DEVELOPMENT 5“不会两处来回互踢”。
  • 为何不是故意设计：DEVIATIONS S2-PY/JAVA 1–3 第 6 条声称“Paho 库内自动重连关闭”，与代码不符。
  • 解决方案：创建 client 时传 reconnect_on_failure=False；在 taken_over 和认证失败分支里（异步）调用 transport.disconnect()。
  • 改动文件：sdk/python/src/nixmsg/transport.py、client.py
  • 与其他模块的交互/冲突风险：无。
  • 需补测试：test_10 改为被顶号后 5 秒内每 0.2 秒采样，断言状态始终不翻转；错误密码场景断言 10 秒内只有 1 次连接尝试。
  • 置信度：已用测试复现。

[S-05] 回调在 SDK 内部锁下执行，回调里调用 SDK 方法会死锁；Java 还持全局锁等 PUBACK（Go / Python / Java）

  • 严重级：high
  • 分类：并发
  • 现象与影响：
    • Python：
      • _cb_lock 是不可重入的 threading.Lock，所有回调都在它下面执行。在回调里调用 close()、logout()、change_login_password()，或手动 ack() 时撤回先到，都会自锁。
      • on_connection 回调还持有 _lock：回调里调 send() 会永久卡住；调 _request 类方法会卡 60 秒，期间 paho 网络线程拿不到锁，心跳也停。
      • 另外存在 _cb_lock 与 _lock 交叉加锁（ABBA）的死锁。
    • Java：
      • setState 在 lock 内调用回调，而 ONLINE 回调就运行在 runLoop 线程上。回调里调 sendSync 会卡 1 小时，调 .get() 会永久卡住。
      • request() 在 synchronized(lock) 里调用 transport.publish()，最多阻塞 10 秒等 PUBACK。结果所有 SDK 操作都被串行到网络往返上。
      • HiveMQ 的回调和 PUBACK 完成都跑在 RxJava computation 调度器上（线程轮转分配）。如果 PUBACK 的完成恰好排到正阻塞在 dispatchResp 的那条线程，就会死锁 10 秒，然后以 busy 失败，而服务器其实已经处理了请求。
    • Go：cbMu 不可重入，每个回调期间都持有。ChangeLoginPassword 和 Ack（结果为撤回时会 emitRevoked）都会再次加这把锁。手动确认模式下，在 OnMessage 末尾调 Ack 若遇上撤回先到（PRD F13 本身就有这个竞态），downLoop 会永久卡死。
  • 证据：
    • Python：client.py:109、:192,220,573-578,605-640（持 _lock 调 _set_state）、:951-959、:787-788。
    • Java：Client.java:659-665,913-915,1034-1054,1108-1120、Transport.java:377-391；javap 可见 MqttRxClient.publishes/publishUnsafe 用 observeOn(applicationScheduler)，默认为 Schedulers.computation()。
    • Go：receive.go:121-125,247-253、api.go:134-139。
    • 复现：Python 在 on_connection(online) 里调 close()，永不返回、锁一直被占；调 send() 同样卡死。Java 在 onConnection(ONLINE) 里调 sendSync，5 秒后 nixmsg-client 线程仍处于 TIMED_WAITING。
  • 文档依据：DEVELOPMENT 9“回调串行”；DEVIATIONS S1.7-6 和 S2 4–5 第 3 条专门为“回调里调用 SDK”做了 resp 分流。
  • 为何不是故意设计：那两条偏差只处理了“resp 与 msg 同队列”的问题，没有覆盖锁重入和持锁执行回调。
  • 解决方案：
    1. 锁内只记录状态变化，释放锁后由单一回调线程或 goroutine 按顺序派发，保证回调不在任何 SDK 锁下运行。
    2. 去掉串行用的互斥锁（或改为可重入锁）。
    3. Java 的 request() 在锁内只登记 pending，锁外 publish，且不在调用线程里等待 PUBACK。
  • 改动文件：sdk/python/.../client.py；sdk/java/.../Client.java、Transport.java；sdk/go/receive.go、connect.go、api.go
  • 与其他模块的交互/冲突风险：和 S-12（Go 事件乱序）是同一改动点。
  • 需补测试：在回调里调用 close / logout / send / 改密 / 手动 ack（撤回结果），断言 2 秒内返回；Java 用 -Drx2.computation-threads=1 做并发 ack 压测。
  • 置信度：Python 和 Java onConnection 已用测试复现；Go 的锁重入、Java 持锁等 PUBACK 为代码阅读确定，10 秒死锁的触发概率为“较高”。

[S-06] 确认失败后没有恢复：重推被忽略、重复回执不再确认、手动 ack 吞掉失败（Python / Java / JS）

  • 严重级：high
  • 分类：协议一致性 / 逻辑
  • 现象与影响：
    1. 自动确认：回调成功后 ack 失败，Python/Java 吞掉异常，去重状态停在“已交未确认”；JS 跳过了置为 acked 这一步。之后服务器重推同一条，SDK 走“已交未确认就忽略”的分支，永不再确认。结果是：保留消息最终过期，不保留消息被丢弃，发送方拿到 expired/dropped，但应用其实已经处理过；确认超时之前这条还占着 32 个推送窗口中的一个。Go 在回调成功后直接置为 acked，重推时会再 ack，这是正确做法。
    2. 重复回执：Python/Java 遇到重复的 receipt_id 直接 return，不发 receipt_ack。服务器每次 PushPending（每个接收方 ack 都会唤醒发送方）都会重推 receipt_id 最小的 64 条未确认回执。一旦首次确认失败（例如断线后还在消化积压，_request 直接返回 NotConnected），这条回执就永远占着窗口；积满 64 条后，该发送方再也收不到新回执。
    3. 手动确认：Python 的 ack() 和 Java 的 ack() 失败时不报错（Java 的 future 正常完成），应用无从得知。
  • 证据：
    • Python：client.py:756-758,798-803,836-851。
    • Java：Client.java:884-887,928-934,965-984。
    • JS：client.ts:352-360。
    • 对照 Go：receive.go:136-141,202-206。
    • 服务端：push.go:88-237,456-495,549-560。
  • 文档依据：DEVELOPMENT 9“已确认过的再次到达：直接再发一次 ack”；6.4“回执……可能重复，SDK 按 receipt_id 去重”。
  • 为何不是故意设计：文档里的“忽略”针对的是回调还在执行、或手动模式等应用确认的情形。Go 的实现与此一致，另外三套偏离了。
  • 解决方案：
    1. 自动模式下回调成功就置为 acked，再发 ack。
    2. 重复回执同样发 receipt_ack（可按 id 节流）。
    3. 手动 ack 失败时 Python 抛异常、Java 的 future 以异常完成。
  • 改动文件：Python client.py、Java Client.java、JS client.ts
  • 与其他模块的交互/冲突风险：与 S-1、S-13 配合，让断线时的 ack 快速失败，而不是等 60 秒。服务端“每次唤醒重推 64 条回执”的放大问题见待核实第 3 条。
  • 需补测试：ack 失败一次后再注入同一条 msg，断言发出 ack 且不重复回调；重复回执每次都 ack；手动 ack 失败时报错。
  • 置信度：代码阅读确定。

[S-10] Java 定时发送不做时钟偏差校正（Java；Python 的 send_at_ms 也原样透传）

  • 严重级：medium
  • 分类：与PRD不符
  • 现象与影响：Java 只有 sendAtMs，写入帧时不加 clockSkewMs。设备时钟偏差多少，定时消息就早到或晚到多少。Python 的 send_at 会校正，但 send_at_ms 原样透传，而且两者的语义没有说明。
  • 证据：Java Client.java:288-289、Types.java:90-100；Python client.py:292-299；对照 Go send.go:83-87、JS client.ts:472-473。
  • 文档依据：PRD F11、F19“本机时间与服务器偏差由 SDK 校正”；DEVELOPMENT 9。
  • 为何不是故意设计：没有偏差记录，Go/JS 和 Python 的 send_at 都做了校正。
  • 解决方案：Java 增加本机时间语义的 sendAt（epoch 毫秒或 java.util.Date，Android API 24 没有 java.time），入队时加上偏差；在 Javadoc 明确 sendAtMs 表示服务器时间，两者同时设置时报 bad_request。Python 在文档里注明 send_at_ms 是服务器时间。
  • 改动文件：Java Types.java、Client.java；Python 文档
  • 与其他模块的交互/冲突风险：Java 公开 API 增项，需在发布前完成。
  • 需补测试：hello 返回的服务器时间比本机快 60 秒时，断言帧里 send_at_ms 约等于本机时间加 62 秒。
  • 置信度：代码阅读确定。

[S-12] fatal 与顶号的处理时序、原因上报不一致（Go / Python / Java；Go / JS 原因名）

  • 严重级：medium
  • 分类：协议一致性 / 并发
  • 现象与影响：服务端的顺序是：先清令牌，再发 fatal，20ms 后以 0x98 断开。
    1. Go/Python/Java 把 fatal 放进串行业务队列异步处理。如果处理线程正忙（执行回调或等 ack），断线会先被处理：Python/Java 立刻重连，Go 的退避 Func(0)=0 也立刻重连，拿作废令牌连上得到 0x86，于是先上报 auth_failed(session_invalid)；Python/Java 随后再报一次真实原因；Go 的 failAuth 调 cancel 后，downLoop 在 select 里可能直接退出，fatal 原因根本没上报。JS 在收包回调里同步处理 fatal，是正确的。
    2. Go 每个状态事件起一个 goroutine，顺序不保证。
    3. Go/JS 被顶号时原因写 "0x8E"，应为 taken_over。
    4. Go/JS fatal 之后不失败挂起中的其他请求。
  • 证据：服务端 session.go:316-336、broker.go:274-292；Go receive.go:38-42,75-87、connect.go:120,135-146、backoff.go:27-29、transport_mqtt.go:81-92（只看 t.stopped，fatal 没有设置它）；Python client.py:652-655,735-745；Java Client.java:752,863-875；JS client.ts:207,304-311。
  • 文档依据：DEVELOPMENT 6.8；9 第 6 条“收到 fatal……事件 auth_failed 带原因”；5“原因 taken_over”。
  • 为何不是故意设计：没有偏差记录；JS 已经按同步方式处理。
  • 解决方案：
    1. 在收包路径识别 fatal 后立即置停止标志、失败发送队列和所有挂起请求、只上报一次原因、异步停止传输（Go 还要设 transport 的 stopped）；之后到来的 CONNACK 拒绝不再覆盖原因。
    2. Go 的状态事件改为有序派发。
    3. Go/JS 顶号原因改为 taken_over。
  • 改动文件：Go receive.go、connect.go、transport_mqtt.go；Python client.py；Java Client.java；JS client.ts
  • 与其他模块的交互/冲突风险：和 S-5、S-8 同文件。
  • 需补测试：处理线程阻塞时注入 fatal 加断线，断言只出现一次正确原因、没有重连尝试；真机上停用、删除、重置密码分别断言原因为 disabled、deleted、password_reset。
  • 置信度：代码阅读确定；时序竞态部分为“较高”。

[S-13] 断线时非发送请求不失败、JS 请求无超时；Go / JS 的 logout 不收尾（Go / JS；Python / Java 部分）

  • 严重级：medium
  • 分类：协议一致性
  • 现象与影响：
    • 断线时挂起中的 recall、群操作等请求：JS 永不结束，Go 只能等调用方 ctx，Python/Java 要等满 60 秒；Python/Java 的 down 线程还会卡在 ack 上。
    • Go 的 Logout 不失败发送队列、不停止传输、不发 offline 事件；JS 的 logout 不失败队列、不发 offline 事件。
  • 证据：JS client.ts:413-437,718-725；Go receive.go:322-337、connect.go:232-245；Python client.py:913；Java Client.java:1055。
  • 文档依据：PRD F19“除发送以外的请求在离线时直接失败”；DEVELOPMENT 9“停止重连时队列里的发送全部以对应错误结束”。
  • 为何不是故意设计：没有偏差记录，Python/Java 的 logout 已经收尾。
  • 解决方案：断线钩子里以 not_connected 失败非发送请求；Go/JS 默认请求超时 60 秒；logout 做和 close 相同的收尾。
  • 改动文件：Go receive.go、connect.go；JS client.ts；Python client.py、Java Client.java（断线失败挂起请求）
  • 与其他模块的交互/冲突风险：和 S-1 同一断线钩子。
  • 需补测试：recall 未得到响应时断线，断言立即报错；logout 后断言队列清空并发出 offline。
  • 置信度：代码阅读确定。

[S-14] 发送收到 rate_limited 后重交没有退避（Python / Java 热循环；Go / JS 固定 1 秒）

  • 严重级：medium
  • 分类：协议一致性
  • 现象与影响：Python/Java 清空 rid 后立即唤醒发送泵，形成按往返时间计的重试风暴，持续打满服务器令牌桶。Go/JS 固定 1 秒重试，不会随连续限流拉长。
  • 证据：Python client.py:682-689；Java Client.java:797-805；Go send.go:186-195；JS client.ts:528-533。
  • 文档依据：DEVELOPMENT 9“按退避自动重交”。
  • 为何不是故意设计：没有偏差记录，文档明确要求退避。
  • 解决方案：每条发送记录连续限流次数，按 1 秒起、翻倍、上限 30 秒、±30% 抖动退避，成功后清零。
  • 改动文件：四套 send/pump 相关文件
  • 与其他模块的交互/冲突风险：无。
  • 需补测试：连续回 3 次 rate_limited，断言重发间隔约为 1、2、4 秒。
  • 置信度：代码阅读确定。

[S-15] 重连退避与连接超时四套不一致（Go / Python / Java）

  • 严重级：medium
  • 分类：设计 / 协议一致性
  • 现象与影响：
    • Go 断线后立即重连（Func(0)=0）；paho 的 PacketTimeout 默认 10 秒，限制了等 CONNACK 的时间，SDK 设置的 30 秒连接超时实际不生效——这正是文档点名要改的情况。
    • Python/Java 断线后立即重连；连上又很快被断开（闪断）时退避不增长，和 Go/JS“未稳定在线则跨周期继续抬升”（S1.3）的做法不同；首次连接也会上报 reconnecting。
    • JS 基本符合。
  • 证据：Go backoff.go:24-39、autopaho net.go:43-52、transport_mqtt.go:115-133（没设 PacketTimeout）、paho client.go:186-188,272；Python client.py:458-499；Java Client.java:522-581。
  • 文档依据：DEVELOPMENT 9 第 3、4 条；第 15 节“不要在四种 SDK 里各写一套不一样的重连”。
  • 为何不是故意设计：S1.3 只说明了 Go/JS 自管退避，没有声明断线后立即重连或 Python/Java 闪断不抬升。
  • 解决方案：Go 记录“是否曾连上”，连上过之后首次重连也等待；设 PacketTimeout = ConnectTimeout。Python/Java 移植与 Go/JS 相同的退避对象。
  • 改动文件：Go backoff.go、transport_mqtt.go；Python client.py；Java Client.java
  • 与其他模块的交互/冲突风险：无。
  • 需补测试：退避对象单测（在线 5 秒断开约 2 秒、在线 61 秒断开约 1 秒）；CONNACK 延迟 15 秒时仍能连上。
  • 置信度：代码阅读确定。

[S-17] Python AsyncClient 接受 async 回调却从不 await，消息被直接确认（Python）

  • 严重级：medium
  • 分类：逻辑
  • 现象与影响：写成 async def on_message 时，SDK 调用它只得到一个协程对象，没有 await，随即自动 ack。结果是消息从没被处理却被确认了，只留下一条 “coroutine never awaited” 警告。
  • 证据：async_client.py:32-33、client.py:786-796。
  • 文档依据：DEVELOPMENT 9（同包提供 asyncio 包装）；PRD F08“处理回调抛错则不确认”。
  • 为何不是故意设计：没有偏差记录；asyncio 用户最自然的写法就是 async 回调。
  • 解决方案：connect 时记录当前事件循环；遇到协程函数用 run_coroutine_threadsafe(...).result() 执行，抛错则不 ack；同步 Client 收到协程返回值时报错。
  • 改动文件：async_client.py、client.py
  • 与其他模块的交互/冲突风险：无。
  • 需补测试：async 回调成功时，ack 在回调完成之后发出；回调抛错时不 ack。
  • 置信度：代码阅读确定。

[S-18] Python / Java 的 URL scheme 处理：https 走明文、mqtt:// 未开启也走裸 TCP（Python / Java）

  • 严重级：low
  • 分类：安全
  • 现象与影响：只有 wss 会开 TLS。传 https:// 会以明文连接（没写端口时连 80）；服务器仅接受 TLS 时连接会失败（默认安全），但若服务器同时允许明文，凭据就会明文传输。mqtt:// 不需要开启选项就走裸 TCP。
  • 证据：transport.py:204-245、Transport.java:239-301；对照 Go transport_mqtt.go:206-237、JS mqtt.ts:151-164。
  • 文档依据：DEVELOPMENT 9“裸 TCP 只在选项里显式打开时使用”；6.9 地址映射。
  • 为何不是故意设计：Go/JS 已把 http/https 映射为 ws/wss 并拒绝未开启的裸 TCP。
  • 解决方案：统一 scheme 映射表：http→ws、https→wss，mqtt/mqtts 只在开启选项时允许。
  • 改动文件：Python transport.py、protocol.py；Java Transport.java、Protocol.java
  • 与其他模块的交互/冲突风险：无。
  • 需补测试：URL 解析单测。
  • 置信度：代码阅读确定。

[S-19] 本地整帧检查有缺口（四套）

  • 严重级：low
  • 分类：协议一致性
  • 现象与影响：JS 用字符串长度（UTF-16 码元）比较字节上限；四套在离线时入队的帧都不检查，握手后也不复查。超限帧会被服务器直接断开，重连后重交同一帧，形成无限循环。
  • 证据：JS client.ts:478-482；Go send.go:96-102。
  • 文档依据：DEVELOPMENT 9 本地检查一段。
  • 为何不是故意设计：文档明确要求本地拦截，正是为了避免这个循环。
  • 解决方案：JS 按 UTF-8 字节计长；四套在入队和 drain 前都按握手给出的 max_frame_bytes 检查。
  • 改动文件：四套 send 相关文件
  • 与其他模块的交互/冲突风险：无。
  • 需补测试：离线时发送超大 meta 应报 frame_too_large；用中文 meta 构造“UTF-16 未超、UTF-8 超限”的用例。
  • 置信度：代码阅读确定。

复审基线：main 4059a15（2026-09-30）。编号说明、各工作线的合并顺序、共享文件归属见总览 #7。

**编号**：K-03　**严重级**：critical　**工作线**：SDK（sdk/*）　**来源**：审查 S-01、S-03、S-05、S-06、S-10、S-12、S-13、S-14、S-15、S-17、S-18、S-19 **依赖**：K-00 (#57)（对外语义条目）　**被依赖**：无 ### 结论与统一方案 本 issue 汇总涉及 Python SDK 的条目，由 Python SDK 负责人一次改完（集中在 `client.py`、`transport.py`、`async_client.py`）。下方"问题明细"是跨四套的原文，请只看 Python 的部分。 | 条目 | 严重级 | Python SDK 的改法 | |---|---|---| | S-03 paho 2.x 默认自动重连未关闭：被顶号后两端约每秒互踢、认证失败后后台持续重试（已真机复现） | critical | 创建 client 时传 `reconnect_on_failure=False`；在 taken_over 与认证失败分支里（异步）调 `transport.disconnect()`；修正 DEVIATIONS S2-PY/JAVA 1–3 第 6 条的错误描述 | | S-01 断线后已发出的发送永不重交、调用可永久阻塞 | critical | 断线且将重连时把在途条目 `pending.rid=""`、重算在途数，按原 id 重交 | | S-05 回调在不可重入的 `_cb_lock` 下执行，on_connection 还持 `_lock`；存在 ABBA 死锁（已复现） | high | 锁内只记录状态变化，锁外由单一线程按序派发回调 | | S-06 自动确认失败被吞、重复回执不 ack、手动 `ack()` 失败不报错 | high | 回调成功即置为 acked 再 ack；重复回执同样发 receipt_ack（可节流）；手动 ack 失败抛异常 | | S-10 `send_at_ms` 原样透传，语义未说明 | medium | 文档注明 `send_at_ms` 是服务器时间，`send_at` 是本机时间并做偏差校正 | | S-12 fatal 与断线的处理顺序导致先报 `session_invalid` 再报真实原因 | medium | 收包路径识别 fatal 后立即置停止标志、失败发送与挂起请求、只报一次原因 | | S-13 断线时挂起请求要等满 60 秒 | medium | 断线钩子以 `not_connected` 立即失败非发送请求 | | S-14 rate_limited 后立即重交形成热循环 | medium | 按 K-00 的退避参数 | | S-15 断线后立即重连、闪断不抬升退避 | medium | 按 K-00 (#57) 修订后的"重连退避"算法实现（不要照搬 JS 现有代码，它有双重翻倍，见 K-02 (#59)） | | S-16 / S-24 对外语义 | medium / low | 按 K-00 统一（错误码、`queue_full`、只返回 data、sendAt+delay 报错、停止后 send 立即失败、取消语义） | | S-17 AsyncClient 接受 async 回调却不 await，消息被直接确认 | medium | connect 时记录事件循环；遇到协程函数用 `run_coroutine_threadsafe(...).result()` 执行，抛错不 ack；同步 Client 收到协程返回值时报错 | | S-18 https 走明文、mqtt:// 未开启也走裸 TCP | low | 按 K-00 的 URL 映射 | | S-19 离线入队的帧不检查整帧大小 | low | 入队和 drain 前都检查 | | S-23 工程问题（Python 部分） | low | 假传输不从 `__init__.py` 导出 | | 补充：`logout()` 吞掉请求失败（`client.py:231-235` 的 `except Exception: pass`），离线时服务端没有作废令牌，应用却以为已经退出 | medium | 按 K-00 (#57) 新增的"logout"一行：本地照常停止重连、清空令牌、结束队列、断开传输，但把请求失败抛给调用方 | 标"补充"的条目来自第二轮 SDK 审查，总审查人已对照代码核实，证据写在条目里（没有对应的原文段落）。 ### 改动文件 `sdk/python/src/nixmsg/client.py`、`transport.py`、`async_client.py`、`protocol.py`、`__init__.py`，`sdk/python/tests/*`，README。 ### 与其他问题的交互 / 冲突说明 - 只改 sdk/python；对外语义条目以 K-00 为准。 - 测试结束后删除本地 `.venv` 等产物。 ### 验收与测试 - `test_10_kick_no_reconnect` 改为被顶号后 5 秒内每 0.2 秒采样，状态始终不翻转；错误密码场景 10 秒内只有 1 次连接尝试。 - 在回调里调 close / logout / send / 改密 / 手动 ack：2 秒内返回。 - 断线重连后在途发送以原 id 重交并完成。 - async 回调成功时 ack 在回调完成之后发出；回调抛错时不 ack。 - 连续回 3 次 rate_limited，重发间隔约为 1、2、4 秒。 - 退避单测（比较去掉抖动的标称值）：连续失败 6 次，间隔为 1、2、4、8、16、30 秒；断线后第一次重连约 1 秒。 - 离线时调用 `logout()`：抛出请求错误，之后不再重连。 --- ### 问题明细（各区审查原文，证据含文件与行号） > 以下是本次复审各区审查报告的原文段落。A、M、I、P、S 开头的是原始发现编号（A 管理后台与网页、M 消息核心、I 身份认证群在线、P 传输平台部署、S SDK）。**解决方案以本 issue 上方的"结论与统一方案"为准**；原文里的方案与之不一致时，按上方执行。 #### [S-01] 断线时已发出、未收到 resp 的发送永不重交，调用方挂起，在途额度泄漏（Go / JS / Python / Java） - **严重级**：critical - **分类**：逻辑 / 与PRD不符 - **现象与影响**：发送帧 publish 后、resp 回来前断线，这一条会一直标记为“在途”。重连后的 drain/pump 只挑未在途的条目，所以永不按原消息号重交。 - 调用方挂起情况：Go 的 `Send` 在 ctx 没有截止时间时永久阻塞；JS 的 Promise 永远不会完成；Python 调用时若已在线，会 `wait(timeout=None)` 永久阻塞；Java 等 1 小时后抛 busy，但条目仍留在队列里。 - 在途计数永不回退：累计 100 次后该进程再也发不出消息，最终队列报满。 - JS 更严重：MQTT.js 在 `reconnectPeriod:0` 下，非主动断开时只清掉 volatile 回调，QoS1 publish 的回调永不触发，所以在 PUBACK 之前断线也会卡住。 - Java：PUBACK 之前断线时，`pumpSends` 直接把这条发送判为失败并出队，不会重交。 - **证据**： - Go：`send.go:170-180`（publish 成功后 `rf := <-ch` 既无超时，也没有断线出口）、`send.go:141-153`（只挑 `!it.inflight`）、`connect.go:57-64`（OnOffline 没有处理在途条目）。 - JS：`client.ts:494-543`、`client.ts:174-177`、`mqtt.ts:93-99`（断线后新建 client，不 `end` 旧的）；MQTT.js `client.js:380-384`、`:882-904`、`:985-987`、`:490-496`。 - Python：`client.py:861-873`（只挑 `rid==""`）、`client.py:605-640`、`client.py:323`。 - Java：`Client.java:1000-1006`、`Client.java:1019-1029`（publish 抛异常就判失败并出队）、`Transport.java:383-391`。 - **文档依据**： - PRD F19：“重连后按原消息号再交；已经发出但没等到结果的也一样”。 - DEVELOPMENT 9 发送：“包括已发出但没收到 resp 的……重连后按原消息号、原请求内容再交”。 - DEVELOPMENT 5：“提交成功但还没发出 resp 就断线时，客户端用同一消息号重试”。 - **为何不是故意设计**：DEVIATIONS 没有相关条目；各 SDK 的注释都写着“网络错误：保留队列”，意图就是重交。 - **解决方案**： 1. 在“断线且将重连”的钩子里遍历发送队列：删除 pending rid，置回未在途（Python/Java 设 `pending.rid=""`），按实际状态重算在途数；帧内容保持原样（原 id、原 `send_at_ms`）。服务器按消息号防重，会返回原结果。 2. Go 的 `dispatchSend` 改为 `select` 三路：`ch`、每次连接一个的 `connGone`、`c.ctx.Done()`。 3. JS 在 `close` 事件里对旧 client 调 `end(true)`，并加 generation 编号，防止同一条被重复完成。 4. Java 的 publish 失败在未停止重连时回退为未在途，不判失败。 5. 可选：等 resp 超时（如 60 秒）也按原 id 重交，兜底 mochi 在 inflight 满时静默丢弃的 resp。 - **改动文件**：`sdk/go/send.go`、`connect.go`；`sdk/js/src/client.ts`、`mqtt.ts`；`sdk/python/src/nixmsg/client.py`；`sdk/java/.../Client.java` - **与其他模块的交互/冲突风险**：不需要服务端配合（依赖已有的消息号防重）。和 S-13 改的是同一个断线钩子。 - **需补测试**：假传输中 publish 后不回 resp，模拟断线重连，断言以同 id、同 `send_at_ms` 重发并完成；循环 150 次后仍能发送；Java 模拟 publish 抛异常，断言重交而非失败。 - **置信度**：代码阅读确定；MQTT.js 行为已按库源码核对。 #### [S-03] Python 没关 paho 自带的自动重连：被顶号后互踢，认证失败后后台持续重试（Python） - **严重级**：critical - **分类**：逻辑 / 与PRD不符 - **现象与影响**：`PahoClient(...)` 没有传 `reconnect_on_failure=False`（paho 2.x 默认开启）。SDK 在被顶号或认证失败时只改自己的标志，不断开底层 paho client，于是 paho 会用创建时的凭据自己重连。 - 首次用密码登录的连接，paho 持有的是**密码**：1 秒后它用密码重新登录，把新设备顶掉，新设备又顶回来，两端无限互踢。每次都是新的密码登录，会换令牌、跑 argon2，双方反复收到 onSession。 - 认证失败后，paho 用错误凭据按 1/3/7/15…秒持续重试，计入登录锁定次数，并反复触发 auth_failed 回调。 - **证据**： - 代码：`transport.py:208-213`、`client.py:605-631`；paho 2.1.0 `client.py:741`（默认开启）、`:2315-2328`（loop_forever 自动重连）、`:4018-4039`（收到 DISCONNECT 不改状态）。 - 真机复现（临时编译 nixmsg，监听 `127.0.0.1:0`，数据放临时目录，结束后已删除）：c1、c2 用同一编号先后登录后，状态约每 1.03 秒翻转一次，持续 8 秒直到关闭。 - 错误密码复现：connect 之后在 1.09 秒、3.11 秒、7.13 秒又出现 auth_failed。 - 现有的 `test_10_kick_no_reconnect` 在 2.5 秒采样，恰好落在互踢周期回到初始状态的时刻，属于偶然通过。 - **文档依据**：PRD F02 验收“A 被踢下线且不再重连，B 可用”，D13、D28；DEVELOPMENT 5“不会两处来回互踢”。 - **为何不是故意设计**：DEVIATIONS S2-PY/JAVA 1–3 第 6 条声称“Paho 库内自动重连关闭”，与代码不符。 - **解决方案**：创建 client 时传 `reconnect_on_failure=False`；在 taken_over 和认证失败分支里（异步）调用 `transport.disconnect()`。 - **改动文件**：`sdk/python/src/nixmsg/transport.py`、`client.py` - **与其他模块的交互/冲突风险**：无。 - **需补测试**：test_10 改为被顶号后 5 秒内每 0.2 秒采样，断言状态始终不翻转；错误密码场景断言 10 秒内只有 1 次连接尝试。 - **置信度**：已用测试复现。 #### [S-05] 回调在 SDK 内部锁下执行，回调里调用 SDK 方法会死锁；Java 还持全局锁等 PUBACK（Go / Python / Java） - **严重级**：high - **分类**：并发 - **现象与影响**： - **Python**： - `_cb_lock` 是不可重入的 `threading.Lock`，所有回调都在它下面执行。在回调里调用 `close()`、`logout()`、`change_login_password()`，或手动 `ack()` 时撤回先到，都会自锁。 - on_connection 回调还持有 `_lock`：回调里调 `send()` 会永久卡住；调 `_request` 类方法会卡 60 秒，期间 paho 网络线程拿不到锁，心跳也停。 - 另外存在 `_cb_lock` 与 `_lock` 交叉加锁（ABBA）的死锁。 - **Java**： - `setState` 在 `lock` 内调用回调，而 ONLINE 回调就运行在 runLoop 线程上。回调里调 `sendSync` 会卡 1 小时，调 `.get()` 会永久卡住。 - `request()` 在 `synchronized(lock)` 里调用 `transport.publish()`，最多阻塞 10 秒等 PUBACK。结果所有 SDK 操作都被串行到网络往返上。 - HiveMQ 的回调和 PUBACK 完成都跑在 RxJava computation 调度器上（线程轮转分配）。如果 PUBACK 的完成恰好排到正阻塞在 `dispatchResp` 的那条线程，就会死锁 10 秒，然后以 busy 失败，而服务器其实已经处理了请求。 - **Go**：`cbMu` 不可重入，每个回调期间都持有。`ChangeLoginPassword` 和 `Ack`（结果为撤回时会 `emitRevoked`）都会再次加这把锁。手动确认模式下，在 OnMessage 末尾调 `Ack` 若遇上撤回先到（PRD F13 本身就有这个竞态），downLoop 会永久卡死。 - **证据**： - Python：`client.py:109`、`:192,220,573-578,605-640`（持 `_lock` 调 `_set_state`）、`:951-959`、`:787-788`。 - Java：`Client.java:659-665,913-915,1034-1054,1108-1120`、`Transport.java:377-391`；javap 可见 `MqttRxClient.publishes/publishUnsafe` 用 `observeOn(applicationScheduler)`，默认为 `Schedulers.computation()`。 - Go：`receive.go:121-125,247-253`、`api.go:134-139`。 - 复现：Python 在 on_connection(online) 里调 `close()`，永不返回、锁一直被占；调 `send()` 同样卡死。Java 在 onConnection(ONLINE) 里调 `sendSync`，5 秒后 nixmsg-client 线程仍处于 TIMED_WAITING。 - **文档依据**：DEVELOPMENT 9“回调串行”；DEVIATIONS S1.7-6 和 S2 4–5 第 3 条专门为“回调里调用 SDK”做了 resp 分流。 - **为何不是故意设计**：那两条偏差只处理了“resp 与 msg 同队列”的问题，没有覆盖锁重入和持锁执行回调。 - **解决方案**： 1. 锁内只记录状态变化，释放锁后由单一回调线程或 goroutine 按顺序派发，保证回调不在任何 SDK 锁下运行。 2. 去掉串行用的互斥锁（或改为可重入锁）。 3. Java 的 `request()` 在锁内只登记 pending，锁外 publish，且不在调用线程里等待 PUBACK。 - **改动文件**：`sdk/python/.../client.py`；`sdk/java/.../Client.java`、`Transport.java`；`sdk/go/receive.go`、`connect.go`、`api.go` - **与其他模块的交互/冲突风险**：和 S-12（Go 事件乱序）是同一改动点。 - **需补测试**：在回调里调用 close / logout / send / 改密 / 手动 ack（撤回结果），断言 2 秒内返回；Java 用 `-Drx2.computation-threads=1` 做并发 ack 压测。 - **置信度**：Python 和 Java onConnection 已用测试复现；Go 的锁重入、Java 持锁等 PUBACK 为代码阅读确定，10 秒死锁的触发概率为“较高”。 #### [S-06] 确认失败后没有恢复：重推被忽略、重复回执不再确认、手动 ack 吞掉失败（Python / Java / JS） - **严重级**：high - **分类**：协议一致性 / 逻辑 - **现象与影响**： 1. **自动确认**：回调成功后 ack 失败，Python/Java 吞掉异常，去重状态停在“已交未确认”；JS 跳过了置为 acked 这一步。之后服务器重推同一条，SDK 走“已交未确认就忽略”的分支，永不再确认。结果是：保留消息最终过期，不保留消息被丢弃，发送方拿到 expired/dropped，但应用其实已经处理过；确认超时之前这条还占着 32 个推送窗口中的一个。Go 在回调成功后直接置为 acked，重推时会再 ack，这是正确做法。 2. **重复回执**：Python/Java 遇到重复的 receipt_id 直接 return，不发 receipt_ack。服务器每次 PushPending（每个接收方 ack 都会唤醒发送方）都会重推 receipt_id 最小的 64 条未确认回执。一旦首次确认失败（例如断线后还在消化积压，`_request` 直接返回 NotConnected），这条回执就永远占着窗口；积满 64 条后，该发送方再也收不到新回执。 3. **手动确认**：Python 的 `ack()` 和 Java 的 `ack()` 失败时不报错（Java 的 future 正常完成），应用无从得知。 - **证据**： - Python：`client.py:756-758,798-803,836-851`。 - Java：`Client.java:884-887,928-934,965-984`。 - JS：`client.ts:352-360`。 - 对照 Go：`receive.go:136-141,202-206`。 - 服务端：`push.go:88-237,456-495,549-560`。 - **文档依据**：DEVELOPMENT 9“已确认过的再次到达：直接再发一次 ack”；6.4“回执……可能重复，SDK 按 receipt_id 去重”。 - **为何不是故意设计**：文档里的“忽略”针对的是回调还在执行、或手动模式等应用确认的情形。Go 的实现与此一致，另外三套偏离了。 - **解决方案**： 1. 自动模式下回调成功就置为 acked，再发 ack。 2. 重复回执同样发 receipt_ack（可按 id 节流）。 3. 手动 ack 失败时 Python 抛异常、Java 的 future 以异常完成。 - **改动文件**：Python `client.py`、Java `Client.java`、JS `client.ts` - **与其他模块的交互/冲突风险**：与 S-1、S-13 配合，让断线时的 ack 快速失败，而不是等 60 秒。服务端“每次唤醒重推 64 条回执”的放大问题见待核实第 3 条。 - **需补测试**：ack 失败一次后再注入同一条 msg，断言发出 ack 且不重复回调；重复回执每次都 ack；手动 ack 失败时报错。 - **置信度**：代码阅读确定。 #### [S-10] Java 定时发送不做时钟偏差校正（Java；Python 的 `send_at_ms` 也原样透传） - **严重级**：medium - **分类**：与PRD不符 - **现象与影响**：Java 只有 `sendAtMs`，写入帧时不加 `clockSkewMs`。设备时钟偏差多少，定时消息就早到或晚到多少。Python 的 `send_at` 会校正，但 `send_at_ms` 原样透传，而且两者的语义没有说明。 - **证据**：Java `Client.java:288-289`、`Types.java:90-100`；Python `client.py:292-299`；对照 Go `send.go:83-87`、JS `client.ts:472-473`。 - **文档依据**：PRD F11、F19“本机时间与服务器偏差由 SDK 校正”；DEVELOPMENT 9。 - **为何不是故意设计**：没有偏差记录，Go/JS 和 Python 的 `send_at` 都做了校正。 - **解决方案**：Java 增加本机时间语义的 `sendAt`（epoch 毫秒或 `java.util.Date`，Android API 24 没有 java.time），入队时加上偏差；在 Javadoc 明确 `sendAtMs` 表示服务器时间，两者同时设置时报 bad_request。Python 在文档里注明 `send_at_ms` 是服务器时间。 - **改动文件**：Java `Types.java`、`Client.java`；Python 文档 - **与其他模块的交互/冲突风险**：Java 公开 API 增项，需在发布前完成。 - **需补测试**：hello 返回的服务器时间比本机快 60 秒时，断言帧里 `send_at_ms` 约等于本机时间加 62 秒。 - **置信度**：代码阅读确定。 #### [S-12] fatal 与顶号的处理时序、原因上报不一致（Go / Python / Java；Go / JS 原因名） - **严重级**：medium - **分类**：协议一致性 / 并发 - **现象与影响**：服务端的顺序是：先清令牌，再发 fatal，20ms 后以 0x98 断开。 1. Go/Python/Java 把 fatal 放进串行业务队列异步处理。如果处理线程正忙（执行回调或等 ack），断线会先被处理：Python/Java 立刻重连，Go 的退避 `Func(0)=0` 也立刻重连，拿作废令牌连上得到 0x86，于是先上报 `auth_failed(session_invalid)`；Python/Java 随后再报一次真实原因；Go 的 `failAuth` 调 cancel 后，downLoop 在 select 里可能直接退出，fatal 原因根本没上报。JS 在收包回调里同步处理 fatal，是正确的。 2. Go 每个状态事件起一个 goroutine，顺序不保证。 3. Go/JS 被顶号时原因写 `"0x8E"`，应为 `taken_over`。 4. Go/JS fatal 之后不失败挂起中的其他请求。 - **证据**：服务端 `session.go:316-336`、`broker.go:274-292`；Go `receive.go:38-42,75-87`、`connect.go:120,135-146`、`backoff.go:27-29`、`transport_mqtt.go:81-92`（只看 `t.stopped`，fatal 没有设置它）；Python `client.py:652-655,735-745`；Java `Client.java:752,863-875`；JS `client.ts:207,304-311`。 - **文档依据**：DEVELOPMENT 6.8；9 第 6 条“收到 fatal……事件 auth_failed 带原因”；5“原因 taken_over”。 - **为何不是故意设计**：没有偏差记录；JS 已经按同步方式处理。 - **解决方案**： 1. 在收包路径识别 fatal 后立即置停止标志、失败发送队列和所有挂起请求、只上报一次原因、异步停止传输（Go 还要设 transport 的 stopped）；之后到来的 CONNACK 拒绝不再覆盖原因。 2. Go 的状态事件改为有序派发。 3. Go/JS 顶号原因改为 `taken_over`。 - **改动文件**：Go `receive.go`、`connect.go`、`transport_mqtt.go`；Python `client.py`；Java `Client.java`；JS `client.ts` - **与其他模块的交互/冲突风险**：和 S-5、S-8 同文件。 - **需补测试**：处理线程阻塞时注入 fatal 加断线，断言只出现一次正确原因、没有重连尝试；真机上停用、删除、重置密码分别断言原因为 disabled、deleted、password_reset。 - **置信度**：代码阅读确定；时序竞态部分为“较高”。 #### [S-13] 断线时非发送请求不失败、JS 请求无超时；Go / JS 的 logout 不收尾（Go / JS；Python / Java 部分） - **严重级**：medium - **分类**：协议一致性 - **现象与影响**： - 断线时挂起中的 recall、群操作等请求：JS 永不结束，Go 只能等调用方 ctx，Python/Java 要等满 60 秒；Python/Java 的 down 线程还会卡在 ack 上。 - Go 的 `Logout` 不失败发送队列、不停止传输、不发 offline 事件；JS 的 `logout` 不失败队列、不发 offline 事件。 - **证据**：JS `client.ts:413-437,718-725`；Go `receive.go:322-337`、`connect.go:232-245`；Python `client.py:913`；Java `Client.java:1055`。 - **文档依据**：PRD F19“除发送以外的请求在离线时直接失败”；DEVELOPMENT 9“停止重连时队列里的发送全部以对应错误结束”。 - **为何不是故意设计**：没有偏差记录，Python/Java 的 logout 已经收尾。 - **解决方案**：断线钩子里以 not_connected 失败非发送请求；Go/JS 默认请求超时 60 秒；logout 做和 close 相同的收尾。 - **改动文件**：Go `receive.go`、`connect.go`；JS `client.ts`；Python `client.py`、Java `Client.java`（断线失败挂起请求） - **与其他模块的交互/冲突风险**：和 S-1 同一断线钩子。 - **需补测试**：recall 未得到响应时断线，断言立即报错；logout 后断言队列清空并发出 offline。 - **置信度**：代码阅读确定。 #### [S-14] 发送收到 rate_limited 后重交没有退避（Python / Java 热循环；Go / JS 固定 1 秒） - **严重级**：medium - **分类**：协议一致性 - **现象与影响**：Python/Java 清空 rid 后立即唤醒发送泵，形成按往返时间计的重试风暴，持续打满服务器令牌桶。Go/JS 固定 1 秒重试，不会随连续限流拉长。 - **证据**：Python `client.py:682-689`；Java `Client.java:797-805`；Go `send.go:186-195`；JS `client.ts:528-533`。 - **文档依据**：DEVELOPMENT 9“按退避自动重交”。 - **为何不是故意设计**：没有偏差记录，文档明确要求退避。 - **解决方案**：每条发送记录连续限流次数，按 1 秒起、翻倍、上限 30 秒、±30% 抖动退避，成功后清零。 - **改动文件**：四套 send/pump 相关文件 - **与其他模块的交互/冲突风险**：无。 - **需补测试**：连续回 3 次 rate_limited，断言重发间隔约为 1、2、4 秒。 - **置信度**：代码阅读确定。 #### [S-15] 重连退避与连接超时四套不一致（Go / Python / Java） - **严重级**：medium - **分类**：设计 / 协议一致性 - **现象与影响**： - Go 断线后立即重连（`Func(0)=0`）；paho 的 `PacketTimeout` 默认 10 秒，限制了等 CONNACK 的时间，SDK 设置的 30 秒连接超时实际不生效——这正是文档点名要改的情况。 - Python/Java 断线后立即重连；连上又很快被断开（闪断）时退避不增长，和 Go/JS“未稳定在线则跨周期继续抬升”（S1.3）的做法不同；首次连接也会上报 reconnecting。 - JS 基本符合。 - **证据**：Go `backoff.go:24-39`、autopaho `net.go:43-52`、`transport_mqtt.go:115-133`（没设 PacketTimeout）、paho `client.go:186-188,272`；Python `client.py:458-499`；Java `Client.java:522-581`。 - **文档依据**：DEVELOPMENT 9 第 3、4 条；第 15 节“不要在四种 SDK 里各写一套不一样的重连”。 - **为何不是故意设计**：S1.3 只说明了 Go/JS 自管退避，没有声明断线后立即重连或 Python/Java 闪断不抬升。 - **解决方案**：Go 记录“是否曾连上”，连上过之后首次重连也等待；设 `PacketTimeout = ConnectTimeout`。Python/Java 移植与 Go/JS 相同的退避对象。 - **改动文件**：Go `backoff.go`、`transport_mqtt.go`；Python `client.py`；Java `Client.java` - **与其他模块的交互/冲突风险**：无。 - **需补测试**：退避对象单测（在线 5 秒断开约 2 秒、在线 61 秒断开约 1 秒）；CONNACK 延迟 15 秒时仍能连上。 - **置信度**：代码阅读确定。 #### [S-17] Python AsyncClient 接受 async 回调却从不 await，消息被直接确认（Python） - **严重级**：medium - **分类**：逻辑 - **现象与影响**：写成 `async def on_message` 时，SDK 调用它只得到一个协程对象，没有 await，随即自动 ack。结果是消息从没被处理却被确认了，只留下一条 “coroutine never awaited” 警告。 - **证据**：`async_client.py:32-33`、`client.py:786-796`。 - **文档依据**：DEVELOPMENT 9（同包提供 asyncio 包装）；PRD F08“处理回调抛错则不确认”。 - **为何不是故意设计**：没有偏差记录；asyncio 用户最自然的写法就是 async 回调。 - **解决方案**：`connect` 时记录当前事件循环；遇到协程函数用 `run_coroutine_threadsafe(...).result()` 执行，抛错则不 ack；同步 Client 收到协程返回值时报错。 - **改动文件**：`async_client.py`、`client.py` - **与其他模块的交互/冲突风险**：无。 - **需补测试**：async 回调成功时，ack 在回调完成之后发出；回调抛错时不 ack。 - **置信度**：代码阅读确定。 #### [S-18] Python / Java 的 URL scheme 处理：https 走明文、mqtt:// 未开启也走裸 TCP（Python / Java） - **严重级**：low - **分类**：安全 - **现象与影响**：只有 wss 会开 TLS。传 `https://` 会以明文连接（没写端口时连 80）；服务器仅接受 TLS 时连接会失败（默认安全），但若服务器同时允许明文，凭据就会明文传输。`mqtt://` 不需要开启选项就走裸 TCP。 - **证据**：`transport.py:204-245`、`Transport.java:239-301`；对照 Go `transport_mqtt.go:206-237`、JS `mqtt.ts:151-164`。 - **文档依据**：DEVELOPMENT 9“裸 TCP 只在选项里显式打开时使用”；6.9 地址映射。 - **为何不是故意设计**：Go/JS 已把 http/https 映射为 ws/wss 并拒绝未开启的裸 TCP。 - **解决方案**：统一 scheme 映射表：http→ws、https→wss，mqtt/mqtts 只在开启选项时允许。 - **改动文件**：Python `transport.py`、`protocol.py`；Java `Transport.java`、`Protocol.java` - **与其他模块的交互/冲突风险**：无。 - **需补测试**：URL 解析单测。 - **置信度**：代码阅读确定。 #### [S-19] 本地整帧检查有缺口（四套） - **严重级**：low - **分类**：协议一致性 - **现象与影响**：JS 用字符串长度（UTF-16 码元）比较字节上限；四套在离线时入队的帧都不检查，握手后也不复查。超限帧会被服务器直接断开，重连后重交同一帧，形成无限循环。 - **证据**：JS `client.ts:478-482`；Go `send.go:96-102`。 - **文档依据**：DEVELOPMENT 9 本地检查一段。 - **为何不是故意设计**：文档明确要求本地拦截，正是为了避免这个循环。 - **解决方案**：JS 按 UTF-8 字节计长；四套在入队和 drain 前都按握手给出的 max_frame_bytes 检查。 - **改动文件**：四套 send 相关文件 - **与其他模块的交互/冲突风险**：无。 - **需补测试**：离线时发送超大 meta 应报 frame_too_large；用中文 meta 构造“UTF-16 未超、UTF-8 超限”的用例。 - **置信度**：代码阅读确定。 --- <sub>复审基线：main `4059a15`（2026-09-30）。编号说明、各工作线的合并顺序、共享文件归属见总览 #7。</sub>
nixevol added the P0-criticallane/sdkreview-2026-09-30 labels 2026-09-30 13:57:07 +08:00
nixevol commented 2026-09-30 14:17:36 +08:00
Author
Owner
Copy Link
Copy Source

按第二轮 SDK 审查补充 1 条（logout() 吞掉请求失败）；S-15 改为按 K-00 (#57) 修订后的退避算法实现，不再写"移植 Go/JS 的退避对象"（JS 现有实现有双重翻倍）。补充条目已由总审查人对照代码核实，详见正文。

按第二轮 SDK 审查补充 1 条（`logout()` 吞掉请求失败）；S-15 改为按 K-00 (#57) 修订后的退避算法实现，不再写"移植 Go/JS 的退避对象"（JS 现有实现有双重翻倍）。补充条目已由总审查人对照代码核实，详见正文。
nixevol commented 2026-09-30 16:36:17 +08:00
Author
Owner
Copy Link
Copy Source

已合入 origin/main 0c9b459。落地提交 537cef0 fix: 按 K-00 约定修复 Python SDK 断线重交与退避 (#60)。

已合入 origin/main `0c9b459`。落地提交 `537cef0` fix: 按 K-00 约定修复 Python SDK 断线重交与退避 (#60)。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
P0-critical
严重：可导致全站不可用、数据丢失或无需凭据的攻击
 P1-high
高：核心功能错误或明显安全问题
 P2-medium
中：功能偏差、健壮性或一致性问题
 P3-low
低：体验、质量或小问题
 lane/admin
工作线：管理后端
 lane/broker
工作线：broker（internal/broker）
 lane/identity
工作线：身份、群、在线与认证基础
 lane/listener
工作线：监听与 HTTP
 lane/message
工作线：消息核心
 lane/sdk
工作线：SDK
 lane/store
工作线：存储、配置、命令行与部署
 lane/test-docs
工作线：测试与文档
 lane/web
工作线：后台网页
 review-2026-09-30
2026-09-30 全量复审提出
 tracking
总览与跟踪
No labels P0-critical lane/sdk review-2026-09-30
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
nixevol (Nixevol)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: nixevol/NixMsg#60