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（已接入响应流程）
• 集成测试 suite（37 项 curl/bash 测试全部通过）✅ 2026-06-03
• 性能基准（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 框架，113 个测试全部通过）

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
  • config_merge()：命令行参数覆盖配置文件
  • cocoon.json 示例配置
  • --no-gzip / --no-brotli 命令行选项禁用压缩
• Brotli 压缩 — 比 gzip 更高压缩率，现代浏览器均支持 ✅ 2026-06-04
• Windows 兼容性 — 跨平台抽象层，支持 Linux/macOS/Windows(MinGW/MSVC) ✅ 2026-06-04
• HTTPS / TLS
• HTTP/2

Phase 4 — 生态

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

当前状态

• 编译通过，零警告（除 coco 子模块的 linker .note.GNU-stack 提示）
• 37 项集成测试全部通过（GET/HEAD/POST/404/Range/304/gzip/brotli/MIME/目录浏览/路径防护/文件上传）
• 113 个单元测试全部通过（Unity 框架，覆盖 http.c / static.c / multipart.c / config.c / server.c 核心逻辑）
• 压测数据：wrk -t4 -c100 -d10s → 16,179 RPS，平均延迟 59.86μs
• POST 支持：JSON 和 form-urlencoded 回显，multipart 文件上传，Content-Length 解析，8MB 上限
• 配置文件支持：JSON 格式，9 个字段，命令行参数可覆盖
• Windows 兼容性：跨平台抽象层 platform.h + platform.c，CMakeLists.txt 自动检测平台，Makefile 在 Windows 下自动链接 ws2_32
• README / Makefile / CMakeLists.txt 已更新

待办池

1. [高] HTTPS / TLS — 生产部署必备
2. [高] HTTP/2 多路复用 — 长期演进方向
3. [中] 完善 Doxygen 中文注释 — 所有模块的公共 API 需要完整文档

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
  • 单元测试：113 个通过（Linux 验证），集成测试：37 项通过
  • 推送到 feature/windows-compat-impl
• 2026-06-04: 本轮行动 — Brotli 压缩支持
  • static.c：brotli_compress() 函数，使用 libbrotlienc 高质量压缩（质量 11，窗口 22）
  • static_serve_file()：优先 Brotli，回退 Gzip，不可压缩/二进制文件跳过
  • http.c：解析 Accept-Encoding: br，http_request_t 新增 accept_brotli 字段
  • cocoon.h：cocoon_config_t 新增 brotli_enabled 字段（默认 true）
  • config.c / config.h：解析 brotli_enabled JSON 字段，config_merge() 新增 has_brotli_enabled 参数
  • main.c：--no-brotli 命令行选项，默认启用 Brotli
  • server.c：连接结构体新增 brotli_enabled，传递至 static_serve_file()
  • Makefile：链接 -lbrotlienc，单元测试编译也添加
  • 单元测试：test_static.c 新增 4 个 Brotli 测试（可压缩/不可压缩/小数据/溢出）
  • 单元测试：test_config.c 新增 brotli_enabled 解析与 merge 测试，修复所有 config_merge() 调用签名
  • 集成测试：assert_brotli() / assert_brotli_preferred() / assert_not_brotli()，新增 5 项 Brotli 测试
  • cocoon.json 示例配置添加 brotli_enabled: true
  • README：更新特性描述、curl 示例、命令行参数、路线图
  • 单元测试：113 个全部通过，集成测试：37 项全部通过
  • 推送到 main
• 2026-06-04: 本轮行动 — 配置文件支持 + README 修正 + bug 修复
  • config.c / config.h：极简 JSON 配置解析器（支持数字、字符串、布尔 true/false、// 注释）
  • cocoon_config_t 扩展 gzip_enabled 字段（默认 true）
  • main.c：-c <file> 加载配置文件，--no-gzip 禁用压缩，命令行参数覆盖配置文件
  • config_merge()：命令行显式指定值覆盖配置文件，新增 has_gzip_enabled 参数
  • 修复 -r 参数 strdup 崩溃：parse_args 中 config->root_dir = strdup(argv[i])，避免 free() 野指针
  • 修复 signal handler 双重 free：main() 中 server 指针仅在 server != NULL 时调用 server_destroy()
  • 单元测试：test_config.c 17 个测试（配置加载、merge、边界条件、gzip_enabled）全部通过
  • 集成测试：32 项全部通过，配置文件启动验证通过
  • cocoon.json 示例配置更新，添加 gzip_enabled 字段
  • README 修正：
    • "极简配置" → "配置文件"（已支持 JSON 配置）
    • 安全设计："仅允许 GET/HEAD" → "支持 GET/HEAD/POST"
    • -v 参数说明："显示版本号" → "详细日志输出（debug 级别）"
    • 路线图：配置文件支持打勾，添加 Brotli 压缩待办
  • 推送到 main
• 2026-06-04: 本轮行动 — multipart 文件上传
  • 实现 multipart.c / multipart.h：boundary 提取、multipart 解析、part 内存管理
  • server.c 集成：POST 请求检测 multipart，保存文件到 root_dir/uploads/
  • 修复 boundary 解析条件（>= b_len 替代 > b_len），修复边界扫描越界
  • 创建 tests/unit/test_multipart.c（12 个测试）：boundary 提取、解析、边界条件
  • 修复集成测试 CRLF 问题：使用 printf 生成真实 CRLF 字节
  • 集成测试 32 项全部通过，单元测试 99 个全部通过
  • 推送到 main
• 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 测试框架（ThrowTheSwitch）
  • 创建 tests/unit/test_http.c（35 个测试）：
    • 请求解析：方法、路径、头部、Range、缓存、编码、边界条件
    • 响应格式化：状态行、缓存头、Range、缓冲区溢出
    • MIME 类型：常见类型、大小写、无扩展名、特殊类型
    • 内存管理：请求体释放
  • 创建 tests/unit/test_static.c（31 个测试）：
    • 压缩判断：文本/二进制/空值
    • 时间处理：格式化、解析、边界
    • ETag：生成、匹配（精确/弱/通配符/空值）
    • 路径安全：正常拼接、路径遍历、空值、边界
    • HTML 转义：特殊字符、缓冲区溢出
    • gzip 压缩：可压缩/不可压缩/小数据/溢出
    • socket 层：send_all、错误响应（404/500/未知）
  • 更新 Makefile：make unit-test 一键编译运行
  • 66 个测试全部通过，集成测试保持 30 项通过
  • 推送到 main