xfy/cocoon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cocoon/.cocoon-plan.md

9.3 KiB
Raw Blame History

Cocoon 发展规划（自主维护）

此文件由 cron 任务每3小时更新，记录项目状态与下一步计划。

路线图

Phase 1 — 核心稳定（当前）

  • HTTP/1.1 请求解析
  • 响应头格式化
  • 静态文件服务（sendfile）
  • 目录浏览
  • Range 请求
  • MIME 类型识别
  • 多线程 M:N 调度
  • 命令行参数
  • 优雅关闭

Phase 2 — 健壮性

  • HTTP 缓存（ETag / Last-Modified / If-None-Match）✅ 2026-06-03
  • 连接超时管理（空闲连接自动清理）✅ 2026-06-03
  • 最大并发连接数限制 ✅ 2026-06-03
  • 分级日志系统（error / warn / info / debug）✅ 2026-06-03
  • 访问日志（Nginx combined 格式，含 User-Agent / Referer）✅ 2026-06-05
  • Gzip 压缩 ✅ 2026-06-03（已接入响应流程）
  • Brotli 压缩 ✅ 2026-06-04（优先于 Gzip）
  • 集成测试 suite（61 项 curl/bash 测试全部通过）✅ 2026-06-05
  • 性能基准（wrk: ~16.2K RPS / ~60μs 延迟）✅ 2026-06-03
  • 请求体解析（POST 支持）✅ 2026-06-03
    • Content-Length 读取
    • JSON / form-urlencoded 回显
    • multipart/form-data 文件上传（保存到 root_dir/uploads/）✅ 2026-06-04
  • C 语言单元测试框架 ✅ 2026-06-03（Unity 框架，127 个测试全部通过）

Phase 3 — 扩展（已完成）

  • 配置文件支持 — JSON 配置替代纯命令行 ✅ 2026-06-04
    • config.c / config.h：极简 JSON 解析器（数字、字符串、布尔、注释）
    • cocoon_config_t 结构体：root_dir / port / threaded / num_workers / max_connections / timeout_ms / log_level / gzip_enabled / brotli_enabled / access_log
    • config_merge()：命令行参数覆盖配置文件
    • cocoon.json 示例配置
    • --no-gzip / --no-brotli 命令行选项禁用压缩
  • Brotli 压缩 — 比 gzip 更高压缩率，现代浏览器均支持 ✅ 2026-06-04
  • HTTPS / TLS — OpenSSL Memory BIO 集成，支持命令行与配置文件启用 ✅ 2026-06-04
  • HTTP/2 — nghttp2 完整实现（TLS ALPN 协商 + 静态文件服务 + 缓存 + 目录浏览）✅ 2026-06-04
  • h2c 升级支持 — 明文 HTTP/2（PRI 魔术字直接连接 + Upgrade: h2c 协商）✅ 2026-06-04
  • HTTP/2 目录浏览 — 目录无 index.html 时返回目录列表 ✅ 2026-06-04
  • WebSocket 支持 — RFC 6455 握手 + 帧解析/编码 + echo 服务器 ✅ 2026-06-05
  • Windows 兼容性 — 跨平台抽象层，支持 Linux/macOS/Windows(MinGW/MSVC) ✅ 2026-06-04

Phase 4 — 生态

  • WebSocket 广播/频道路由 — 全局连接注册表 + 广播/定向发送 API ✅ 2026-06-05
  • 中间件机制
  • 插件系统

当前状态

  • WebSocket 广播系统已上线：
    • ws_broadcast() 全局广播、ws_broadcast_to_path() 按频道广播
    • ws_connection_count() 连接计数
    • 线程安全（链表 + mutex），连接自动注册/注销
  • 编译通过，零警告（除 coco 子模块的 linker .note.GNU-stack 提示）
  • 61 项集成测试全部通过（GET/HEAD/POST/404/Range/304/gzip/brotli/MIME/目录浏览/路径防护/文件上传/TLS/HTTP/2/h2c/WebSocket/访问日志）
  • 127 个单元测试全部通过（Unity 框架）
  • 压测数据：wrk -t4 -c100 -d10s → 16,179 RPS，平均延迟 59.86μs（单线程）
  • 多线程模式（-t -w 4）已修复（主线程 accept + poll，client_handler 1MB 协程栈）
  • POST 支持：JSON 和 form-urlencoded 回显，multipart 文件上传，Content-Length 解析，8MB 上限
  • 配置文件支持：JSON 格式，9 个字段（含 access_log），命令行参数可覆盖
  • 访问日志：Nginx combined 格式，支持文件路径或 stdout（-），线程安全（pthread_mutex），记录 User-Agent / Referer / 状态码
  • TLS/HTTPS：OpenSSL 3.0 Memory BIO + coco 协程集成，自签名证书支持，ALPN 协商 h2/http1.1
  • HTTP/2：完整功能（静态文件服务、目录浏览、缓存协商、压缩、HEAD 请求）
  • h2c：明文 HTTP/2 支持（prior knowledge + Upgrade 协商）
  • WebSocket：RFC 6455 握手、文本/二进制帧 echo、ping/pong/close、广播/频道
  • Windows 兼容性：跨平台抽象层 platform.h + platform.c，CMakeLists.txt 自动检测平台，Makefile 在 Windows 下自动链接 ws2_32

待办池

  1. [高] 中间件机制 — 请求处理前后 hook 系统，允许插入自定义逻辑（认证、限流、CORS）
  2. [高] 插件系统 — 动态加载 .so/.dll 扩展
  3. [低] Doxygen 中文注释 — tls.c, config.c, multipart.c, access_log.c, main.c, websocket.c 等模块待补充
  4. [低] 性能优化 — 连接池复用、零拷贝优化、压缩预缓存
  5. [低] WebSocket 单元测试 — 为广播/注册表 API 添加 C 单元测试

Windows 兼容性实现详情

方案：引入 platform.h + platform.c 跨平台抽象层，通过条件编译实现双平台支持。

POSIX 路径：fcntl → O_NONBLOCK，sendfile 零拷贝，opendir/readdir/closedir，sysconf

Windows 路径：ioctlsocket(FIONBIO)，WSAStartup/WSACleanup，FindFirstFile/FindNextFile，GetSystemInfo，read+send 64KB 循环

错误码统一：WSAEWOULDBLOCK→EAGAIN，WSAEINTR→EINTR，WSAECONNRESET→ECONNRESET

文件清单：

  • platform.h — 跨平台类型定义、函数声明、宏定义（全部中文注释）
  • platform.c — POSIX 实现 + Windows 实现（条件编译）
  • CMakeLists.txt — 全新跨平台构建配置，支持 Linux/macOS/Windows
  • 修改 server.c — socket 类型、非阻塞设置、socket 关闭、文件元数据、路径处理、CPU 核心数
  • 修改 static.c — 文件打开/读取/关闭/seek/发送，目录遍历，socket 发送，路径处理
  • 修改 main.c — 信号处理、socket 初始化/清理
  • 修改 Makefile — 添加 platform.c，Windows 下链接 ws2_32

最近行动记录

  • 2026-06-04: 本轮行动 — Windows 兼容性
    • platform.h：跨平台抽象层头文件，定义 cocoon_socket_t/cocoon_file_t/cocoon_dir_iter_t 类型
    • platform.c：双平台实现，POSIX 分支（fcntl/sendfile/opendir）+ Windows 分支（ioctlsocket/WSAStartup/FindFirstFile）
    • server.c：移除全部 POSIX 头文件，使用跨平台 API；int fd → cocoon_socket_t
    • static.c：文件操作和目录遍历全部跨平台化；sendfile 替代方案 64KB 缓冲区
    • main.c：信号处理跨平台化，新增 cocoon_socket_init()/cocoon_socket_cleanup()
    • CMakeLists.txt：全新跨平台构建配置，自动检测 Windows/POSIX
    • Makefile：添加 platform.c，Windows 下自动链接 ws2_32
    • 单元测试：127 个通过（Linux 验证），集成测试：61 项通过
    • 推送到 feature/windows-compat-impl
  • 2026-06-05: 本轮行动 — WebSocket 广播/频道路由系统
    • websocket.c：新增全局连接注册表（链表 + pthread_mutex + 原子计数）
    • ws_registry_add/remove: 连接自动注册/注销
    • ws_broadcast(): 向所有活跃连接广播文本消息
    • ws_broadcast_to_path(): 按握手路径（如 /ws/chat）定向广播
    • ws_connection_count(): 获取当前连接数
    • ws_handle_connection() 新增 path 参数，用于频道标识
    • server.c：修改调用处，传入 req.path 作为频道
    • websocket.h：新增广播 API 声明
    • 编译零警告，61 项集成测试 + 127 个单元测试全部通过
    • 提交：fix(coco) 修正子模块 + feat(websocket) 广播系统
  • 2026-06-05: 本轮行动 — 实现 WebSocket 支持（RFC 6455）
    • 新增 websocket.h / websocket.c：WebSocket 协议完整实现
    • 帧解析：支持 FIN、opcode、payload length（7/16/64 位）、mask 解掩码
    • 帧编码：服务器端发送（无掩码），支持文本/二进制/close/ping/pong
    • 握手：Sec-WebSocket-Key + SHA1 + Base64 计算 Accept
    • server.c：添加 is_websocket_upgrade_request() 检测，握手后进入 ws_handle_connection()
    • 连接处理：文本/二进制 echo、ping/pong 自动响应、close 帧处理
    • 集成测试：tests/websocket_test.py（Python 标准库，零依赖）
    • 编译通过，零警告
    • 61 项集成测试全部通过，127 个单元测试全部通过
    • 推送到 main（2775033）
  • 2026-06-05: 本轮行动 — 访问日志（Nginx combined 格式）
    • 新增 access_log.c / access_log.h：Nginx combined 格式访问日志，线程安全（pthread_mutex）
    • cocoon.h：新增 access_log_path 配置字段
    • config.c / config.h：JSON 配置和命令行参数支持 access_log
    • main.c：新增 --access-log <path> CLI 选项，- 表示输出到 stdout
    • server.c：扩展 connection_t 结构体，添加 client_addr / addr_len / response_status
    • server.c：handle_request() 中每个响应路径设置 response_status，请求结束时调用 access_log_write()
    • server.c：accept_loop() 将客户端地址复制到连接上下文
    • Makefile：加入 access_log.c，更新单元测试编译规则
    • cocoon.json：示例配置添加 "access_log": "-"
    • tests/integration_test.sh：新增 5 项访问日志测试
    • 编译通过，零警告
    • 59 项集成测试全部通过，127 个单元测试全部通过
    • 推送到 main
  • 2026-06-04: 其他历史记录...（省略）