cocoon/.cocoon-plan.md

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（68 项 curl/bash 测试全部通过）✅ 2026-06-06
• 性能基准（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 框架，142 个测试全部通过）
• WebSocket 单元测试 ✅ 2026-06-06（12 项，覆盖帧解析/编码/握手/粘包/大负载）
• 健康检查端点 /_health ✅ 2026-06-06（JSON 状态：连接数、插件、中间件、运行时间）

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 / cors_enabled / auth_user / auth_pass / rate_limit
  • 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
• 中间件机制 — 注册表 + 链式执行，内置 CORS / Basic Auth / Rate Limit ✅ 2026-06-06
• 插件系统 — 动态加载 .so/.dll 扩展 ✅ 2026-06-06（MVP：dlopen + 中间件注册 + 示例插件）

当前状态

• 所有 Phase 1-4 核心功能已完成
• 编译通过，零警告（除 coco 子模块的 linker .note.GNU-stack 提示）
• 142 个单元测试全部通过（Unity 框架，新增 12 项 WebSocket 测试）
• 75 项集成测试全部通过（新增 7 项健康检查端点测试）
• 压测数据：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 格式，13 个字段，命令行参数可覆盖
• 访问日志：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. [低] Doxygen 中文注释 — tls.c, config.c, multipart.c, access_log.c, main.c, websocket.c 等模块待补充
2. [低] 性能优化 — 连接池复用、零拷贝优化、压缩预缓存
3. [低] 配置文件 JSON Schema 验证 — 配置文件格式校验
4. [x] 插件热重载 — 运行时 SIGUSR1 触发重新加载插件 ✅ 2026-06-06

最近行动记录

• 2026-06-06: 本轮行动 — 插件热重载支持（SIGUSR1）
  • plugin.c / plugin.h: 新增 cocoon_plugin_reload() API，自动存储已加载插件路径
  • 热重载流程：卸载所有插件 → 按存储路径重新加载 → 日志输出成功/失败数量
  • main.c: 注册 SIGUSR1 信号处理器，收到信号后触发 cocoon_plugin_reload()
  • --help 新增 Signals 说明文档
  • 集成测试：新增 2 项热重载测试（SIGUSR1 后 HTTP 200 验证 + 热重载日志验证）
  • 全部 142 个单元测试 + 77 项集成测试通过，编译零警告
  • 推送到 main（80385d9）
• 2026-06-06: 本轮行动 — 健康检查端点 /_health
  • server.c：新增 /_health 路由，返回 JSON 服务器状态
  • 包含：uptime_seconds、connections.active/max、plugins.count/list、middleware.count/names
  • middleware.c / middleware.h：新增 cocoon_middleware_list() 查询 API
  • 集成测试：新增 7 项测试（状态码 200、JSON 字段验证、HEAD 支持、路径遍历防护）
  • 全部 142 个单元测试 + 75 项集成测试通过，编译零警告
  • 推送到 main（09e592d）
• 2026-06-06: 本轮行动 — 插件配置数组支持 + 杂项修复
  • config.c：极简 JSON 解析器新增 [/] token 类型，支持字符串数组解析
  • plugins 字段向后兼容单字符串 "plugins.so"，向前支持数组 ["a.so", "b.so"]
  • .gitignore：补全遗漏的 tests/unit/test_websocket 二进制
  • Makefile：补全 test_log 单元测试编译规则（缺失导致 make unit-test 失败）
  • cocoon.json：示例配置改为数组格式 "plugins": ["plugins/hello.so"]
  • test_config.c：新增 3 项测试（test_load_plugins_string、test_load_plugins_array、test_load_plugins_array_multiple）
  • 全部 142 个单元测试 + 68 项集成测试通过，编译零警告
  • 推送到 main（2dc29d0）
• 2026-06-06: 本轮行动 — 添加 WebSocket 单元测试
  • 新增 tests/unit/test_websocket.c：12 项 WebSocket 协议单元测试
  • 覆盖：帧解析（文本/二进制/关闭/空负载、掩码解掩码、16位/64位长度）、帧编码（文本/关闭/ping/pong）、握手验证（Sec-WebSocket-Accept）、粘包多帧解析、64KB 大负载、空负载边界
  • 使用 socketpair 创建内部通信管道，无需真实网络依赖
  • 全部 12 项测试通过，139 个单元测试 + 68 项集成测试全部通过
  • 推送到 main（faedbd5）
• 2026-06-06: 本轮行动 — 实现动态插件系统（Phase 4 MVP）
  • 新增 tests/unit/test_websocket.c：12 项 WebSocket 协议单元测试
  • 覆盖：帧解析（文本/二进制/关闭/空负载、掩码解掩码、16位/64位长度）、帧编码（文本/关闭/ping/pong）、握手验证（Sec-WebSocket-Accept）、粘包多帧解析、64KB 大负载、空负载边界
  • 使用 socketpair 创建内部通信管道，无需真实网络依赖
  • 全部 12 项测试通过，139 个单元测试 + 68 项集成测试全部通过
  • 推送到 main（faedbd5）
• 2026-06-06: 本轮行动 — 实现动态插件系统（Phase 4 MVP）
  • plugin.h / plugin.c：基于 dlopen/dlsym 的插件加载器，最多8个插件，逆序卸载
  • 插件接口：cocoon_plugin_init()（初始化）、cocoon_plugin_shutdown()（清理）、cocoon_plugin_version()（版本）
  • 插件通过 cocoon_middleware_register() 注册中间件参与请求处理
  • 命令行：--plugin <path> 可多次指定
  • 配置文件：plugins 字段支持字符串路径（单插件，数组支持待扩展）
  • server.c：在 server_create() 中加载插件，server_destroy() 中逆序卸载
  • plugins/hello.c：示例插件，演示中间件注册/注销/版本返回
  • Makefile：添加 plugin.c 和 -ldl 链接选项
  • cocoon.json：示例配置添加 "plugins": "plugins/hello.so"
  • .gitignore：排除 plugins/*.so 和 www/uploads/
  • 集成测试：68项全部通过（新增插件加载+日志验证2项）
  • 单元测试：139个全部通过
  • 编译零警告，推送到 main（952cc66）
• 2026-06-06: 本轮行动 — 中间件框架（CORS / Basic Auth / Rate Limit）
  • middleware.c / middleware.h：注册表（最多 16 个）+ 链式执行 + 短路机制
  • CORS 中间件：OPTIONS 预检 204 + 跨域响应头（Access-Control-Allow-Origin/Methods/Headers）
  • Basic Auth 中间件：HTTP 基础认证，Base64 解码，401 Unauthorized + WWW-Authenticate 头
  • Rate Limit 中间件：基于 IP 秒级限流，哈希表（256 桶），429 Too Many Requests
  • config.c / config.h：新增 cors_enabled / auth_user / auth_pass / rate_limit 字段
  • main.c：新增 --cors / --auth-user / --auth-pass / --rate-limit CLI 选项；修复 access_log_path 未初始化段错误
  • server.c：集成 cocoon_middleware_init_builtin() 在 server_create() 中初始化；修复 server_destroy 与 main() 双重释放字符串指针；新增 mw_config 字段避免栈变量悬空
  • 修复 rate_limit_hash：仅使用 IP 地址计算哈希，排除端口，避免同一 IP 不同 bucket
  • 修复 401/429 响应 Content-Length：与 body 长度严格匹配，避免 curl 挂起等待
  • 集成测试：66 项全部通过（新增 CORS/Basic Auth/Rate Limit 5 项测试）
  • 单元测试：127 个全部通过（修复 test_config.c 中 config_merge 参数不匹配）
  • 编译零警告，推送到 main（dd41464）
• 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: 其他历史记录...（省略）