cocoon/.cocoon-plan.md

# Cocoon 发展规划（自主维护）

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

## 路线图

### Phase 1 — 核心稳定（当前）
- [x] HTTP/1.1 请求解析
- [x] 响应头格式化
- [x] 静态文件服务（sendfile）
- [x] 目录浏览
- [x] Range 请求
- [x] MIME 类型识别
- [x] 多线程 M:N 调度（**有已知问题**：`-t` 模式下主线程不在协程上下文，client_handler 非阻塞 fd busy loop）
- [x] 命令行参数
- [x] 优雅关闭

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

### Phase 3 — 扩展（已完成）
- [x] **配置文件支持** — JSON 配置替代纯命令行 ✅ 2026-06-04
- [x] **Brotli 压缩** — 比 gzip 更高压缩率 ✅ 2026-06-04
- [x] **HTTPS / TLS** — OpenSSL Memory BIO 集成，支持命令行与配置文件启用 ✅ 2026-06-04
- [x] **HTTP/2** — nghttp2 完整实现（TLS ALPN 协商 + 静态文件服务 + 缓存 + 目录浏览）✅ 2026-06-04
- [x] **h2c 升级支持** — 明文 HTTP/2（PRI 魔术字直接连接 + Upgrade: h2c 协商）✅ 2026-06-04
- [x] **HTTP/2 目录浏览** — 目录无 index.html 时返回目录列表 ✅ 2026-06-04
- [x] **WebSocket 支持** — RFC 6455 握手 + 帧解析/编码 + echo 服务器 ✅ 2026-06-05
- [ ] Windows 兼容性（阻塞：需 coco 提供 Windows I/O 后端）

### Phase 4 — 生态
- [ ] WebSocket 支持
- [ ] 中间件机制
- [ ] 插件系统

## 当前状态

- 编译通过，零警告（除 coco 子模块的 linker .note.GNU-stack 提示）
- **61 项集成测试全部通过**（新增 2 项 WebSocket 测试）
- **127 个单元测试全部通过**（Unity 框架）
- 压测数据：wrk -t4 -c100 -d10s → 16,179 RPS，平均延迟 59.86μs
- WebSocket 支持：RFC 6455 握手、文本/二进制帧 echo、ping/pong/close
  - **coco v2.2.0 压测**：wrk -t4 -c100 -d10s → 15,056 RPS，平均延迟 64.49μs（单线程模式，性能在合理范围内）
  - 多线程模式（-t -w 4）当前存在连接问题，待排查
- 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 协商）

## 待办池

1. **[已完成] ~~多线程模式修复~~** — ✅ 2026-06-05 已修复（主线程 accept + poll，client_handler 1MB 协程栈）
2. **[高] Phase 4 生态功能** — WebSocket 广播/消息路由、中间件机制、插件系统
3. **[中] 完善 WebSocket 功能** — 消息路由、广播、连接管理面板
4. **[中] Windows 兼容性** — 阻塞：coco 当前仅支持 epoll/kqueue/io_uring，无 Windows IOCP 后端
5. **[低] Doxygen 中文注释** — tls.c, config.c, multipart.c, access_log.c, main.c 等模块待补充
6. **[低] 性能优化** — 连接池复用、零拷贝优化、压缩预缓存

## 最近行动记录

- **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: 本轮行动 — 升级 coco 子模块到 v2.2.0**
  - 检查 upstream 新提交：发现 release 2.2.0，包含调度器重大改进
  - 主要更新：负载重分配、热栈迁移槽位释放、调度器停止时状态清理、原子减量修复
  - fast-forward 子模块从 62dbb13 到 b45045e
  - 编译通过，零警告（仅 coco linker .note.GNU-stack 提示）
  - **59 项集成测试全部通过，127 个单元测试全部通过**
  - 推送到 main（d2c6dc3）
- **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 项访问日志测试（日志生成、GET 记录、User-Agent、Referer、404 状态码）
  - 编译通过，零警告
  - **59 项集成测试全部通过，35 个单元测试全部通过**
  - 推送到 main
- **2026-06-04: 本轮行动 — http2.c 完整中文 Doxygen 注释**
  - 为 http2.c 全部 29 个函数添加中文文档注释
  - 会话管理模块：init, cleanup, create, destroy, is_http2, get, set_context, upgrade
  - 数据收发模块：recv, send_pending, want_read, want_write
  - nghttp2 回调：send, begin_headers, header, frame_recv, stream_close, data_chunk
  - 静态文件服务：format_http_time, generate_etag, parse_http_time, match_etag, data_source_read, serve_directory, serve_static
  - 连接处理：on_connection_accepted
  - 所有注释包含功能说明、参数说明、返回值说明
  - 编译通过，零警告
  - **54 项集成测试全部通过，35 个单元测试全部通过**
  - 推送到 main（d0f3bb8）
- **2026-06-04: 本轮行动 — HTTP/2 目录浏览支持**
  - http2.c: 新增 `http2_serve_directory()` 函数，生成 HTML 目录列表页面
  - http2.c: 在 `http2_serve_static()` 中检测目录无 index.html 时调用目录浏览
  - http2.c: 目录浏览支持 HTML 转义、文件大小格式化、修改时间显示、上级目录链接
  - http2.c: 目录浏览支持 HEAD 请求（不发送 body）
  - http2.c: 添加 `#include <dirent.h>` 头文件
  - tests/integration_test.sh: 新增 2 项 HTTP/2 目录浏览集成测试（HTTPS h2 + h2c）
  - 编译通过，零警告
  - **54 项集成测试全部通过，35 个单元测试全部通过**
  - 推送到 main
- **2026-06-04: 本轮行动 — h2c 升级支持（明文 HTTP/2）**
  - server.c: 添加 h2c 检测逻辑（PRI 魔术字 + Upgrade: h2c 协商）
  - server.c: `is_h2c_upgrade_request()` 检查 Upgrade 和 Connection 头
  - server.c: `send_h2c_upgrade_response()` 发送 101 Switching Protocols
  - server.c: `client_handler` 循环中检测 h2c 前言和 Upgrade 请求，正确销毁会话（避免双重 free）
  - http2.h: 新增 `http2_session_upgrade()` 声明
  - http2.c: 实现 `http2_session_upgrade()`，通过 `nghttp2_session_upgrade2` 注册 stream 1
  - http2.c: 修复 `nghttp2_session_upgrade2` 第四个参数误用（`head_request` 而非 `stream_id`）
  - tests/integration_test.sh: 新增 4 项 h2c 集成测试（prior knowledge、Upgrade 协商、404 ×2）
  - 编译通过，零警告
  - **52 项集成测试全部通过，35 个单元测试全部通过**
  - 推送到 main
  - 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 个测试全部通过）