xfy
782bce9122
- 将 Windows 兼容性标记为已完成 - 更新当前状态：跨平台抽象层 platform.h + platform.c - 更新待办池：移除 Windows 任务，聚焦 HTTPS/TLS 和 HTTP/2 - 添加 Windows 兼容性实现详情章节
160 lines
9.6 KiB
Markdown
160 lines
9.6 KiB
Markdown
# 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] Gzip 压缩 ✅ 2026-06-03（已接入响应流程）
|
||
- [x] 集成测试 suite（37 项 curl/bash 测试全部通过）✅ 2026-06-03
|
||
- [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 框架，113 个测试全部通过）
|
||
|
||
### Phase 3 — 扩展
|
||
- [x] **配置文件支持** — 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` 命令行选项禁用压缩
|
||
- [x] **Brotli 压缩** — 比 gzip 更高压缩率，现代浏览器均支持 ✅ 2026-06-04
|
||
- [x] **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
|