newsie

项目背景与战略目标

newsie 是一个实现了网络新闻传输协议（NNTP）客户端功能的三方库，用于从 Usenet 新闻服务器获取和发布新闻组文章。在仓颉后端生态中，此类协议库是构建消息聚合、内容爬取、分布式论坛系统等服务的关键基础设施。本项目旨在利用仓颉语言 1.0.0+ 的核心优势——编译期内存安全（彻底规避缓冲区溢出、空指针解引用等 CVE 风险）、轻量级并发模型（支持高吞吐异步 I/O）、强类型系统与代数数据类型（精准建模 NNTP 响应状态与文章结构），打造一个高性能、高可靠、可嵌入微服务架构的原生 NNTP 客户端库。该库将为 OpenHarmony 及更广泛的仓颉后端应用提供标准化的新闻组通信能力，填补生态中协议工具链的空白。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：

  • P99 命令响应延迟 < 20ms（局域网）

  • 单连接吞吐 ≥ 500 articles/s（中等大小文章）

  • 内存占用 ≤ 3MB（空闲客户端实例）

• 安全要求：

  • 100% 通过仓颉编译器内存安全检查，无未定义行为

  • 网络输入经严格边界检查，杜绝整数溢出/注入风险

  • 敏感操作（如 POST）需显式启用，防止意外写入

• 可靠性：

  • 网络中断自动重连（指数退避策略）

  • 所有资源（TCP 连接、缓冲区）100% RAII 管理

  • 完善的错误上下文链（Error Context Chaining）

• 可维护性：

  • 协议逻辑与网络 I/O 解耦

  • 接口设计符合仓颉惯用法（如 impl Display for Article）

  • 代码 100% 通过 cjfmt 格式化

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

// NNTP 协议错误类型
enum NntpError {
    ConnectionFailed(IoError),
    ProtocolViolation(String),
    ArticleNotFound,
    ServerRejected(String),
}

// 新闻组信息
struct Newsgroup {
    name: String,
    low: U64,
    high: U64,
    status: GroupStatus, // enum: Public/Restricted/Moderated
}

// 核心客户端接口
interface NntpClient {
    // 异步连接服务器
    async fn connect(host: String, port: U16) -> Result<Void, NntpError>
    
    // 获取新闻组列表
    async fn list() -> Result<[Newsgroup], NntpError>
    
    // 选择新闻组并返回统计信息
    async fn group(name: String) -> Result<GroupStats, NntpError>
    
    // 获取指定文章（支持 article/head/body）
    async fn article(msgId: String) -> Result<Article, NntpError>
    
    // 获取时间之后的新文章（UTC）
    async fn newnews(group: String, since: DateTime) -> Result<[String], NntpError>
    
    // 安全关闭连接
    fn quit() -> Result<Void, NntpError>
}

// 文章结构（强类型头部）
struct Article {
    headers: ArticleHeaders, // 包含 From/Subject/Date/Message-ID 等
    body: String,
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：NNTP 核心命令实现（connect/list/group/article） + 单元测试（覆盖率≥95%） + 接口文档

• 第二阶段：扩展命令支持（HDR/OVER/NEWNEWS） + 高并发适配 + 与主流 NNTP 服务器（INN/Diablo）集成测试

• 第三阶段：性能调优报告 + cjpm 发布包 + 生产部署指南（含 TLS 扩展示例）

3.2 项目实施路线图

技术实现规范与质量认证体系

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt --check，禁止使用 unsafe 块

• 类型安全：

  • 所有 NNTP 状态码映射为枚举（如 ResponseCode::OkGroupSelected）

  • 文章 ID 使用 MessageId 新类型封装，防止字符串误用

• 错误处理：所有 public API 返回 Result<T, NntpError>，禁止隐式 panic

4.2 测试与验证标准

• 单元测试：核心模块行覆盖率 ≥ 95%（cjpm test --coverage 验证）

• 性能基准：

  • 建立 benches/nntp_bench.cj 对比 Python/Go 参考实现

  • 监控 list() 和 article() 的内存分配次数

• 安全扫描：集成 cj-analyzer 检测潜在 DoS 向量（如超长行处理）

4.3 文档与可维护性

• API 文档：所有 public 接口包含 /// 注释，说明线程安全性和错误场景

• 架构决策记录：

  • ADR-01：为何采用异步而非同步阻塞模型

  • ADR-02：多行响应解析器的状态机设计

• 贡献指南：明确 PR 需包含：协议兼容性说明 + 基准测试对比

4.4 持续集成质量门禁

# PR 自动化流水线
cjpm fmt --check
cjpm build --release
cjpm lint --deny-warnings
cjpm test --all-features --coverage
cjpm bench --baseline=main

技术栈与开发环境

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

• 构建工具：CJPM (Cangjie Package Manager)

• 测试框架：@std/testing 原生测试库

• 质量工具：cjfmt, cjpm lint, cjpm bench

• 开发环境：

  • 本地：仓颉 1.0.0+ SDK（Linux/macOS）

  • CI：cangjie-lang/cjci:1.0.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. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求