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
• Gzip 压缩 ✅ 2026-06-03（已接入响应流程）
• Brotli 压缩 ✅ 2026-06-04（优先于 Gzip）
• 集成测试 suite（45 项 curl/bash 测试全部通过）✅ 2026-06-04
• 性能基准（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
• Brotli 压缩 — 比 gzip 更高压缩率 ✅ 2026-06-04
• HTTPS / TLS — OpenSSL Memory BIO 集成，支持命令行与配置文件启用 ✅ 2026-06-04
• HTTP/2 — nghttp2 完整实现（TLS ALPN 协商 + 静态文件服务 + 缓存）✅ 2026-06-04
• Windows 兼容性
• h2c 升级支持 — 明文 HTTP/2 升级（PRI 方法 + 魔术字）

Phase 4 — 生态

• WebSocket 支持
• 中间件机制
• 插件系统

当前状态

• 编译通过，零警告（除 coco 子模块的 linker .note.GNU-stack 提示）
• 45 项集成测试全部通过（新增 6 项 HTTP/2 测试：ALPN 协商、GET、HEAD、404、缓存）
• 127 个单元测试全部通过（Unity 框架，1 个忽略）
• 压测数据：wrk -t4 -c100 -d10s → 16,179 RPS，平均延迟 59.86μs
• POST 支持：JSON 和 form-urlencoded 回显，multipart 文件上传，Content-Length 解析，8MB 上限
• 配置文件支持：JSON 格式，8 个字段，命令行参数可覆盖
• TLS/HTTPS：OpenSSL 3.0 Memory BIO + coco 协程集成，自签名证书支持，ALPN 协商 h2/http1.1
• HTTP/2：
  • 基于 nghttp2 的完整会话管理（431 行）
  • TLS ALPN 自动协商 h2
  • 静态文件服务（GET/HEAD、路径安全、ETag、304 Not Modified）
  • HEAD 请求正确处理（无 body）
  • 目录自动 fallback 到 index.html
  • 路径遍历防护（.. 检查）
  • 文件内容通过 nghttp2_data_provider 流式传输
  • 修复 send_callback 返回值 bug（send_all 返回 0 而非已发送字节数）
  • 修复 :path 伪头长度解析 bug（4→5）和路径空终止问题

待办池

1. [中] h2c 升级支持 — 明文 HTTP/2 升级（PRI 方法 + 魔术字），server.c 读取前几个字节检测
2. [中] Windows 兼容性 — 平台抽象层（platform.h / platform.c），sendfile 替代方案，io_uring 替代方案
3. [中] Doxygen 中文注释 — 所有模块的公共 API 需要完整文档（http2.c 已部分完成）
4. [低] 检查远程更新内容 — 上游有 new commits，需 review 9041d8d
5. [低] HTTP/2 动态压缩 — 在 HTTP/2 响应中支持 gzip/brotli 压缩（当前未启用）
6. [低] HTTP/2 目录浏览 — 目前返回 404，可考虑支持目录列表

最近行动记录

• 2026-06-04: 本轮行动 — HTTP/2 静态文件服务 + ALPN 修复
  • http2.c: 实现完整的 HTTP/2 静态文件服务（GET/HEAD、路径安全、ETag、304 缓存）
  • http2.c: 修复 :path 伪头长度解析 bug（4→5）和路径空终止问题
  • http2.c: 修复 send_callback 返回值 bug（send_all 返回 0 而非已发送字节数，导致 nghttp2 重试死循环）
  • http2.c: 添加 If-None-Match / If-Modified-Since 缓存头解析到 nghttp2 头回调
  • http2.h: 扩展 http2_session_t 结构体，添加 root_dir/gzip/brotli 字段
  • http2.h: 新增 http2_session_set_context() 接口
  • server.c: 在 handle_http2() 中调用 set_context 传入连接配置
  • tls.c: 实现 ALPN 选择回调（tls_alpn_select_cb），优先协商 h2 次选 http/1.1
  • tls.c: 修正 ALPN 协议格式解析（长度前缀字符串序列）
  • tests/integration_test.sh: 新增 6 项 HTTP/2 集成测试（ALPN 协商、GET、HEAD、404、缓存）
  • 编译通过，零警告（除 coco 子模块 linker 提示）
  • 45 项集成测试全部通过，127 个单元测试全部通过
  • 推送到 main（22c9f74）
• 2026-06-04: 本轮行动 — HTTP/2 骨架 + server.c 集成
  • 新增 http2.c / http2.h：基于 nghttp2 的 HTTP/2 会话管理（431 行）
  • 修复编译：匹配 http_request_t 结构，使用 log_error 替代 LOG_ERROR
  • server.c: 添加 handle_http2() 函数，在 client_handler 中检测 HTTP/2 连接
  • TLS ALPN 协商后自动创建 HTTP/2 会话
  • HTTP/2 连接走独立处理路径（帧读写循环）
  • tls.c/tls.h: 新增 tls_negotiated_http2()，检查 ALPN 是否协商为 h2
  • Makefile：加入 http2.c、链接 -lnghttp2
  • 编译通过，39 项集成测试 + 127 单元测试全部通过
  • 推送到 main
• 2026-06-04: 本轮行动 — 实现 TLS/HTTPS 支持
  • 新增 tls.c / tls.h：OpenSSL 3.0 Memory BIO 与 coco 协程 I/O 集成
  • cocoon.h：新增 tls_enabled, tls_cert, tls_key 配置字段
  • server.c：accept 后执行 TLS 握手，读/写/关闭路由到 TLS 层
  • static.c：TLS 连接降级 sendfile 为缓冲 read+write，修复 lseek 定位（压缩读取后重置文件位置）
  • config.c / config.h：JSON 配置支持 tls_cert, tls_key, tls_enabled
  • main.c：新增 --cert, --key, --tls CLI 选项
  • Makefile：加入 tls.c，链接 -lssl -lcrypto
  • 生成自签名测试证书 tests/server.crt / tests/server.key
  • tests/integration_test.sh：新增 TLS 握手 + HTTPS 响应验证，修复 kill_server 匹配规则，curl 添加 --max-time 和 -k
  • tests/unit/test_config.c：更新 config_merge 测试签名
  • 单元测试：127 个通过（1 忽略），集成测试：39 个通过（含 2 个 TLS 测试）
  • 推送到 main
• 2026-06-04: 修复拼写错误 + 扩展 server 单元测试（17 个）
• 2026-06-04: Brotli 压缩支持（优先于 Gzip）
• 2026-06-04: 配置文件支持 + gzip_enabled 控制 + README 修正
• 2026-06-04: multipart 文件上传
• 2026-06-03: 项目初始化，核心模块全部实现
• 2026-06-03: 添加缓存协商（ETag + Last-Modified + 304），修复编译警告
• 2026-06-03: 添加连接空闲超时管理 + 最大并发限制 + 分级日志系统
• 2026-06-03: 创建集成测试套件 + 性能基准 + 更新文档
• 2026-06-03: 添加 POST 请求体解析支持，30 项测试全部通过，README 更新
• 2026-06-03: 单元测试框架（Unity，66 个测试全部通过）