DrSmoothl
7ab91c81e9
The #211 concurrency attempt (c17fff6) was disproven on a live endpoint.
QQ's highway server requires blocks to arrive in offset order and rejects
an out-of-order PUT with error_code=102902 — ~20% failure under a real
account even after deferring the finalize block. Parallel connections
can't guarantee arrival order, so that approach is unshippable.
Replace it with a single persistent connection that PUTs blocks in strict
offset order, reusing the socket across the whole file via HTTP keep-alive:
- In order: the server never sees an out-of-order block, so no 102902.
- One warm connection: the TCP congestion window stays open across the
file instead of paying slow-start on a fresh connection per 1 MiB block.
That per-block cold start was the real throughput cap behind #211.
Adaptive to QQ's edge nodes FIN'ing between chunks (the reason #118 went
one-connection-per-chunk): on a transport failure, or a peer half-close
after a response, drop the socket, reconnect, and re-send the SAME block
(re-PUTting an offset is idempotent). Worst case degrades to one
connection per block — no worse than #118, and still strictly in order.
Also fixes a latent bug on the reconnect path, surfaced by review: a
response truncated mid-stream (header arrived, Content-Length unmet, then
FIN) was resolved as a partial frame and then fatally rejected by
unpackHighwayFrame OUTSIDE the retry loop, turning a recoverable mid-body
FIN into a failed upload. A truncated response now rejects as a retryable
transport failure so the block is re-sent. Added an idle read timeout so
a silent peer can't hang the upload forever (the persistent socket widens
that exposure).
Verified live (tempserver, repeated 48 MiB group-file uploads): 1
connection per file, 0 failures across dense repeats, ~1.4x throughput
over the old per-chunk-connection serial path in a low-RTT datacenter —
the win is larger on high-RTT home links where per-block slow-start hurt
most (the original #211 report). Unit tests cover keep-alive reuse,
FIN-after-each-response degradation, mid-stream reconnect+resume, body-
truncation retry, in-order exactly-once coverage, and close-once.
Next Remote Protocol Framework.
Releases · Issues · QQ 群 · Telegram
SnowLuma 是一个基于 TypeScript 的协议转换框架，旨在为 QQ 客户端提供 OneBot v11 标准接口，支持 WebSocket/HTTP 适配、多账号并行及 WebUI 管理。
⚠️ 免责声明：SnowLuma 是独立的第三方互操作项目，与腾讯 / QQ 无任何隶属或授权关系。本项目仅供学习与技术研究，请遵守《QQ 用户协议》及适用法律；软件按"现状"提供、不附带任何担保，使用风险自负。详见
EULA.md。⚠️ Disclaimer: SnowLuma is an independent, third-party interoperability project with no affiliation with or endorsement by Tencent / QQ, provided for study and research only, "as is" without warranty. Comply with the QQ User Agreement and applicable law; use at your own risk. See
EULA.md.
特性
- OneBot v11 兼容：支持文本、音视频、Markdown、JSON 等消息格式。
- 高性能架构：TypeScript 全栈，基于 pnpm monorepo 管理，核心逻辑分离。
- 现代化管理：内置 WebUI 面板，支持实时日志、密码热更、多账号管理。
- 多适配器支持：WebSocket (Server/Client)、HTTP (Server/Post)。
- 数据持久化：使用 SQLite 存储好友、群组等关系数据。
快速开始
- 从 Releases 下载最新发布包并解压。
- 运行
./launcher.bat(Windows) 或./launcher.sh(Linux)。 - 访问
http://localhost:5099(初始账号admin，密码见控制台输出)。
许可 / License
SnowLuma 采用 源码可见非商业许可（SnowLuma Source-Available Non-Commercial License），见 LICENSE。这不是 OSI 开源许可：源码公开供查看、学习与非商业自托管，但禁止任何商业使用（出售、转售、付费托管 / 代搭 / 代运营等），公开发布修改版须事先书面授权。随附的原生附加组件（snowluma-*.node 等）为专有组件，不在本许可范围内。二进制发行包另受 EULA.md 约束；商业授权请联系 motricseven@foxmail.com。参与贡献请阅读 CONTRIBUTING.md。
SnowLuma is under a source-available, non-commercial license (see LICENSE) — NOT an OSI open-source license. The source is published for study and non-commercial self-hosting; commercial use is prohibited without prior written permission, and the bundled native addon (snowluma-*.node) is proprietary and not covered by this license.
鸣谢
参考了 LagrangeV2 的协议定义与 NapCatQQ 的实现思路。