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

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

## 路线图

### Phase 1 — 核心稳定（当前）
- [x] HTTP/1.1 请求解析
- [x] 响应头格式化
- [x] 静态文件服务（sendfile）
- [x] 目录浏览
- [x] Range 请求
- [x] MIME 类型识别
- [x] 多线程 M:N 调度
- [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（68 项 curl/bash 测试全部通过）✅ 2026-06-06
- [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 框架，142 个测试全部通过）
- [x] **WebSocket 单元测试** ✅ 2026-06-06（12 项，覆盖帧解析/编码/握手/粘包/大负载）
- [x] **健康检查端点** /_health ✅ 2026-06-06（JSON 状态：连接数、插件、中间件、运行时间）

### 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 + h2c + 静态文件 + 缓存）✅ 2026-06-04
- [x] **HTTP/2 目录浏览** — 无 index.html 时返回目录列表 ✅ 2026-06-04
- [x] **WebSocket 支持** — RFC 6455 握手 + 帧解析/编码 + echo + 广播/频道 ✅ 2026-06-05
- [x] **Windows 兼容性** — 跨平台抽象层 ✅ 2026-06-04
- [x] **反向代理** — 路径前缀匹配 → HTTP/1.1 后端，JSON 配置支持 ✅ 2026-06-07
  - `proxy.h` / `proxy.c`：路径前缀匹配、HTTP/1.1 后端转发、X-Forwarded-* 头透传
  - `cocoon.json`：支持 `proxies` 数组配置
  - 80 项集成测试全部通过（含 3 项代理测试）

### Phase 4 — 生态
- [x] **WebSocket 广播/频道路由** — 全局连接注册表 + 广播/定向发送 API ✅ 2026-06-05
- [x] **中间件机制** — 注册表 + 链式执行，内置 CORS / Basic Auth / Rate Limit ✅ 2026-06-06
- [x] **插件系统** — 动态加载 .so/.dll 扩展 ✅ 2026-06-06（MVP：dlopen + 中间件注册 + 示例插件）

## 项目状态：已暂停

> **注意**：用户已指示暂停 cocoon 新功能开发，核心任务转向 ephemeral 软件引擎方向。项目进入维护状态，不再主动推进新功能。

- 所有 Phase 1-4 核心功能已完成（反向代理 MVP 已加入）
- 编译通过，零警告
- **142 个单元测试全部通过** + **80 项集成测试全部通过**
- 如需恢复开发，请取消暂停状态后重新执行 cron 任务

## 待办池（冻结，不再推进）

## 最近行动记录

- 2026-06-07 12:00: **项目暂停** — 用户指示停止 cocoon 新功能开发，核心任务转向 ephemeral 软件引擎。本轮 cron 执行仅更新计划文件，未新增代码。项目所有功能保持可用，编译和测试全部通过。
- 2026-06-07: **本轮行动 — 为 config.c、log.c、tls.c 添加函数级 Doxygen 注释**
  - `config.c`: 为 JSON 解析器内部函数（parser_init、parser_skip_ws、parser_next_token、token_expect、token_str_dup、token_to_long、str_to_log_level）和公共 API（config_load_from_file、config_merge）添加完整 Doxygen 注释
  - `log.c`: 为日志级别转换和输出函数（level_str、log_set_level、log_set_prefix、log_get_level、log_output、log_error、log_warn、log_info、log_debug）添加注释
  - `tls.c`: 为 TLS 连接管理（tls_lookup、tls_map_set、tls_map_clear）、Memory BIO 操作（socket_read、socket_write_all、flush_wbio）、ALPN 回调（tls_alpn_select_cb）和公共 API（tls_create_context、tls_destroy_context、tls_has_context、tls_accept、tls_read、tls_write、tls_close、tls_has_connection、tls_negotiated_http2）添加注释
  - `http2.c`: 移除过时的 TODO 占位注释（请求体收集已实现）
  - 编译零警告，142 个单元测试 + 80 项集成测试全部通过
  - 推送到 main（9da9bd9）
- 2026-06-07: **本轮行动 — 修复编译警告与测试清理**
  - `config.c`: 将 `strncpy` 替换为 `memcpy` + 显式 null 结尾，消除 `-Wstringop-truncation` 警告
  - `proxy.c`: 同上，修复 `proxy_add_rule` 中的 `strncpy` 警告
  - `tests/integration_test.sh`: 修复 `kill_server` 函数，补充 `pgrep -f "cocoon.*-c "` 以清理通过 `-c` 配置文件启动的测试服务器进程，解决端口占用导致测试失败的问题
  - 编译零警告，142 个单元测试 + 80 项集成测试全部通过
  - 推送到 main（1b930aa）
- 2026-06-07: **本轮行动 — 反向代理支持（MVP）**
  - `proxy.h` / `proxy.c`：新增反向代理模块
    - `cocoon_proxy_rule_t` / `cocoon_proxy_config_t`：路径前缀匹配规则（最多 8 条）
    - `proxy_init()` / `proxy_add_rule()`：解析 URL（`http://host:port/path`），提取 host / port / path / https 标志
    - `proxy_match()`：根据路径前缀查找匹配规则
    - `proxy_forward()`：连接后端（`gethostbyname` + `socket` + `connect`），流式转发 HTTP/1.1 请求 + 响应
    - 透传头：Host、X-Forwarded-For、X-Forwarded-Proto、Content-Type、Content-Length
    - 目前不支持 HTTPS 后端（运行时拒绝并警告）
  - `cocoon.h`：新增 `COCOON_MAX_PROXY_RULES = 8`，`cocoon_config_t` 添加 `proxies[8]` 和 `num_proxies`
  - `config.c`：JSON 解析器新增 `proxies` 数组解析（对象项含 `prefix` 和 `target` 字符串）
  - `server.c`：
    - `connection_t` 新增 `server_context_t *ctx` 指针，用于 `handle_request()` 访问代理配置
    - `accept_loop()` 中设置 `conn->ctx = ctx`
    - `server_create()` 中初始化代理规则（从配置加载）
    - `handle_request()` 中在静态文件服务之前检查代理规则，匹配时调用 `proxy_forward()`
  - `Makefile`：`proxy.c` 加入 `SRCS` 和 `test_server` 编译规则
  - `cocoon.json`：示例配置添加 `"proxies": [{"prefix": "/api", "target": "http://localhost:3000"}]`
  - `tests/integration_test.sh`：新增 3 项反向代理集成测试（代理 GET 200、响应体包含后端内容、非代理路径静态文件正常）
  - 编译通过（零警告），142 个单元测试 + 80 项集成测试全部通过
  - 推送到 main
- 2026-06-07: **本轮行动 — HTTP/2 POST 请求体支持**
  - `on_data_chunk_recv_callback`: 实现请求体收集，将 DATA 帧数据追加到 `stream->request.body`
  - `on_frame_recv_callback`: 根据请求方法选择处理方式（GET/HEAD → `http2_serve_static`，POST → `http2_serve_post`）
  - `http2_serve_post`: 新增函数，处理 HTTP/2 POST 请求
    - 支持 multipart/form-data 文件上传（保存到 root_dir/uploads/）
    - 支持 application/json 和 x-www-form-urlencoded 回显
    - 构建 JSON 响应并通过 nghttp2 发送
  - 包含 `multipart.h` 和 `platform.h` 到 `http2.c`
  - 全部 142 个单元测试 + 77 项集成测试通过，编译零警告
  - 推送到 main
- 2026-06-06: **本轮行动 — WebSocket 空闲超时 + 跨平台 poll/select 抽象**
  - `platform.h` / `platform.c`: 新增 `cocoon_socket_poll_readable()` 跨平台 socket 可读等待
    - POSIX: `poll()` + `POLLIN`
    - Windows: `select()` + `fd_set`（readfds）
  - `websocket.c`: `ws_handle_connection()` 实现 `timeout_ms` 空闲超时处理
    - 每次循环前调用 `cocoon_socket_poll_readable()` 等待数据或超时
    - 超时时发送 `1001 Idle timeout` 关闭帧，清理连接资源
    - 解决 TODO: `/* TODO: 超时处理 */`
  - `tests/websocket_test.py`: 新增 `test_timeout()` 测试（Python 标准库，零依赖）
    - 连接后不发帧，验证服务端 2 秒后发送 1001 关闭帧
  - `tests/integration_test.sh`: 新增 WebSocket 空闲超时集成测试（启动 `-o 2000` 短超时服务器）
  - `Makefile`: 补全 `test_websocket` 单元测试编译规则，加入 `platform.c`（修复 undefined reference）
  - 全部 142 个单元测试 + 77 项集成测试通过，编译零警告
  - 推送到 main（待提交）
- 2026-06-06: **本轮行动 — 基础设施完善（Makefile + CI + README）**
  - `Makefile`: 添加 `integration-test` 别名和 `test-all` 目标（一键运行全部测试）
  - `.github/workflows/ci.yml`: GitHub Actions 工作流，push/PR 时自动编译 + 单元测试 + 集成测试
  - `README.md`: 同步项目现状，添加 CI badge、补充全部新特性与模块说明
  - 编译零警告，142 个单元测试 + 77 项集成测试全部通过
  - 推送到 main（87f89f5 → b0ae0f7 → 068ab7d）
- 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: 其他历史记录...（省略）