xmpp_websocket

第一部分：项目背景与战略目标
xmpp_websocket 是一个用于在 WebSocket 之上承载 XMPP（Extensible Messaging and Presence Protocol）协议的通信库，典型应用于即时通讯、物联网设备状态同步等后端场景。当前实现基于 TypeScript，在 OpenHarmony 等资源受限或高安全要求环境中存在内存安全隐患与性能瓶颈。本项目将利用仓颉编程语言（Cangjie Language）1.0.0+ 的核心优势——编译期内存安全（杜绝缓冲区溢出、空指针解引用）、轻量级线程模型（支持万级并发长连接）、强类型系统（精准建模 XMPP XML 流与 WebSocket 帧）以及 CJNative 高性能 FFI 能力，构建一个原生、高效、可嵌入微服务或边缘设备的 XMPP over WebSocket 客户端/服务端基础库。该库将为仓颉生态提供标准化的实时通信能力，支撑安全、可靠的双向消息通道。

第二部分：核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：单实例支持 ≥10,000 并发 XMPP 会话，P99 消息往返延迟 < 20ms（局域网环境）。

• 安全要求：完全消除内存安全漏洞；所有网络输入经严格校验，防止 XML 注入或 DoS 攻击。

• 可靠性：网络抖动、服务端重启等异常下自动恢复会话；消息发送支持失败重试与回调确认。

• 可维护性：协议层与传输层解耦，支持未来扩展 BOSH 或 QUIC 传输；接口设计符合仓颉惯用法。

2.3 核心接口设计示例 (伪代码)

interface XmppWebSocket {
    // 连接到 XMPP 服务器（WSS）
    fn connect(url: String, caPath: Option<String>): Result<Void, XmppError>

    // 注册事件监听器
    fn onConnect(callback: fn() -> Void): Void
    fn onData(callback: fn(XmlElement) -> Void): Void
    fn onError(callback: fn(XmppError) -> Void): Void
    fn onClose(callback: fn(isError: Bool, reason: String) -> Void): Void

    // 发送原始 XMPP 数据
    fn write(data: XmlElement, ackCallback: Option<fn()>): Result<Void, XmppError>

    // 关闭连接
    fn end(): Result<Void, XmppError>
}

enum XmppError {
    ConnectionFailed(String),
    TlsHandshakeError,
    SaslAuthFailed,
    InvalidXml,
    WriteTimeout
}

第三部分：项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：WebSocket 传输层、XMPP 流解析器、基础事件系统 + 单元测试（覆盖率≥95%）+ 接口文档

• 第二阶段：SASL 认证支持、自动重连、错误恢复机制 + 集成测试（与 Ejabberd/Openfire 互操作）+ 压测报告

• 第三阶段：性能调优报告、OpenHarmony HAP 示例、cjpm 发布包（支持 Linux 与 OHOS）

3.2 项目实施路线图

第四部分：技术实现规范与质量认证体系

4.1 仓颉语言专项质量规范

• 100% 通过 cjfmt 格式校验，禁止手动调整代码风格。

• 所有 XML 元素使用强类型结构体表示，禁止字符串模板拼接。

• 错误必须通过 Result<T, E> 显式返回，禁止 panic 处理业务逻辑异常。

4.2 测试与验证标准

• 单元测试覆盖所有协议状态转换、错误路径、边界条件，行覆盖率 ≥95%。

• 建立 XMPP 协议模糊测试（fuzzing）套件，持续验证 XML 解析鲁棒性。

• 使用仓颉 sanitizer 工具链进行内存安全与并发数据竞争检测。

4.3 文档与可维护性

• 所有 public 接口需包含 Doc Comments，说明线程安全级别、生命周期约束及错误码含义。

• 记录关键架构决策（如为何选择 pull-based vs push-based 事件模型）至 ADR 文档。

• 提供 CONTRIBUTING.md 明确本地构建、XMPP 服务器测试环境搭建、PR 提交流程。

4.4 持续集成质量门禁

cjpm fmt --check
cjpm build --release
cjpm lint --deny-warnings
cjpm test --all-features --coverage
cjpm bench --baseline=ts-xmpp-websocket

第五部分：技术栈与开发环境

• 核心语言：仓颉编程语言（Cangjie Language）1.0.0+（强制）

• 构建与包管理：CJPM (Cangjie Package Manager)

• 测试框架：仓颉原生测试框架（支持异步测试与 mock）

• 质量工具：cjfmt, cjpm lint, cjpm bench, cj-sanitizer

• 环境要求：Linux 开发环境（Ejabberd 23+ 测试集群），CI 使用 cangjie-lang/cjci:1.0 官方 Docker 镜像

交付件

验收标准

1.功能

1. 三方库必须有明确的功能；

2. 如果参考对标库移值开发，功能与参考三方库保持一致。

2.资料

1. Readme：包含简介，软件架构，目录结构，下载安装（编译构建），接口说明，使用示例，约束限制，开源协议，参与贡献等内容；

2. Changelog，三方库版本需包含基本的修改说明。

3.标准遵从性（可选），三方库实现需满足对应协议或行业标准，举例

1. appquth：支持对OAuth 的PKCE扩展；

2. icu4j：支持unicode标准库，通用字符集ISO/IEC 10646。

4.性能目标

1. 性能敏感三方库接口运行性能持平对标三方库

5.开源协议遵从，必须包含License文件

1. 放置合适的开源License协议，建议Apache License Version 2.0；

2. 引用或参考开源三方库，需遵从开源协议。

6.网络安全要求

1. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求