952cc663fe
新增插件系统： - 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：示例插件，演示中间件注册 - 集成测试：新增插件加载 + 日志验证测试（68项全部通过） - 单元测试：127个全部通过 - 编译：Makefile 添加 plugin.c 和 -ldl - .gitignore 排除编译产物和上传目录
161 lines
10 KiB
Markdown
161 lines
10 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] 访问日志（Nginx combined 格式，含 User-Agent / Referer）✅ 2026-06-05
|
||
- [x] Gzip 压缩 ✅ 2026-06-03（已接入响应流程）
|
||
- [x] Brotli 压缩 ✅ 2026-06-04（优先于 Gzip）
|
||
- [x] 集成测试 suite（66 项 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 框架，127 个测试全部通过）
|
||
|
||
### 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 / access_log / cors_enabled / auth_user / auth_pass / rate_limit
|
||
- `config_merge()`：命令行参数覆盖配置文件
|
||
- `cocoon.json` 示例配置
|
||
- `--no-gzip` / `--no-brotli` 命令行选项禁用压缩
|
||
- [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
|
||
- [x] **Windows 兼容性** — 跨平台抽象层，支持 Linux/macOS/Windows(MinGW/MSVC) ✅ 2026-06-04
|
||
|
||
### Phase 4 — 生态
|
||
- [x] **WebSocket 广播/频道路由** — 全局连接注册表 + 广播/定向发送 API ✅ 2026-06-05
|
||
- [x] **中间件机制** — 注册表 + 链式执行，内置 CORS / Basic Auth / Rate Limit ✅ 2026-06-06
|
||
- [ ] 插件系统 — 动态加载 .so/.dll 扩展
|
||
|
||
## 当前状态
|
||
|
||
- WebSocket 广播系统已上线：
|
||
- `ws_broadcast()` 全局广播、`ws_broadcast_to_path()` 按频道广播
|
||
- `ws_connection_count()` 连接计数
|
||
- 线程安全（链表 + mutex），连接自动注册/注销
|
||
- **中间件框架已上线**：
|
||
- `cocoon_middleware_register()` / `cocoon_middleware_execute()` 注册表 + 链式执行
|
||
- CORS 中间件：OPTIONS 预检 204 + 跨域响应头
|
||
- Basic Auth 中间件：HTTP 基础认证，401 未授权
|
||
- Rate Limit 中间件：基于 IP 秒级限流，429 Too Many Requests
|
||
- 命令行参数：`--cors` / `--auth-user` / `--auth-pass` / `--rate-limit`
|
||
- 配置文件支持：`cors_enabled` / `auth_user` / `auth_pass` / `rate_limit`
|
||
- 编译通过，零警告（除 coco 子模块的 linker .note.GNU-stack 提示）
|
||
- **66 项集成测试全部通过**（GET/HEAD/POST/404/Range/304/gzip/brotli/MIME/目录浏览/路径防护/文件上传/TLS/HTTP/2/h2c/WebSocket/访问日志/中间件）
|
||
- **127 个单元测试全部通过**（Unity 框架）
|
||
- 压测数据：wrk -t4 -c100 -d10s → 16,179 RPS，平均延迟 59.86μs（单线程）
|
||
- 多线程模式（-t -w 4）已修复（主线程 accept + poll，client_handler 1MB 协程栈）
|
||
- POST 支持：JSON 和 form-urlencoded 回显，multipart 文件上传，Content-Length 解析，8MB 上限
|
||
- **配置文件支持**：JSON 格式，13 个字段，命令行参数可覆盖
|
||
- **访问日志**：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 协商）
|
||
- **WebSocket**：RFC 6455 握手、文本/二进制帧 echo、ping/pong/close、**广播/频道**
|
||
- **Windows 兼容性**：跨平台抽象层 platform.h + platform.c，CMakeLists.txt 自动检测平台，Makefile 在 Windows 下自动链接 ws2_32
|
||
|
||
## 待办池
|
||
|
||
1. **[高] 插件系统** — 动态加载 .so/.dll 扩展，中间件注册 API 扩展
|
||
2. **[中] HTTP/2 压缩** — 接入 gzip/brotli 到 HTTP/2 响应
|
||
3. **[低] Doxygen 中文注释** — tls.c, config.c, multipart.c, access_log.c, main.c, websocket.c 等模块待补充
|
||
4. **[低] 性能优化** — 连接池复用、零拷贝优化、压缩预缓存
|
||
5. **[低] WebSocket 单元测试** — 为广播/注册表 API 添加 C 单元测试
|
||
6. **[低] 配置文件 JSON Schema 验证** — 配置文件格式校验
|
||
|
||
## 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-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: 其他历史记录...（省略）
|