Cocoon
一只从 coco 协程库中孵化出的轻量 Web 服务器。
Cocoon（茧）—— 用协程的轻盈，包裹静态资源的安稳。
特性
| 特性 | 描述 |
|---|---|
| 🚀 协程驱动 | 基于 coco 有栈协程，每个连接一个协程，上下文切换 < 100ns |
| 📁 静态托管 | 目录浏览、MIME 自动识别、Range 请求、index.html 自动补全 |
| 🧵 多核扩展 | M:N 调度器 + Work-stealing，自动负载均衡至多核 |
| ⚡ 零拷贝 | 优先使用 sendfile，减少用户态/内核态数据拷贝 |
| 🔐 路径安全 | 自动防护路径遍历攻击 (../) |
| 🔧 极简配置 | 纯命令行启动，无需配置文件 |
Quick Start
依赖
- GCC / Clang（C11 标准）
- coco 协程库（通过 git submodule 自动获取）
- Linux（内核 ≥ 5.1，支持 io_uring）/ macOS
- CMake 3.10+（用于构建 coco 依赖）
构建
git clone --recursive https://github.com/xfy911/cocoon.git
cd cocoon
# 如果 clone 时忘了 --recursive，补初始化 submodule
git submodule update --init --recursive
# 构建 cocoon（会自动检测并构建 coco 依赖）
make build-all
# 或者分开构建
make deps # 先构建 coco
make # 再构建 cocoon
# 也可以使用系统上已有的 coco
make COCO_DIR=/path/to/coco
运行
# 单线程模式（开发调试）
./cocoon -r ./examples/www -p 8080
# 多线程模式（生产环境，自动检测 CPU 核心）
./cocoon -r ./examples/www -p 8080 -t
# 指定 8 个工作线程
./cocoon -r ./examples/www -p 8080 -t -w 8
测试
# 启动服务器
./cocoon -r ./examples/www -p 8080 &
# 访问首页
curl http://localhost:8080/
# 目录浏览
curl http://localhost:8080/examples/
# Range 请求
curl -H "Range: bytes=0-99" http://localhost:8080/index.html
命令行参数
Usage: ./cocoon [options]
Options:
-r <dir> 静态资源根目录（必填）
-p <port> 监听端口（默认 8080）
-t 启用多线程调度
-w <num> 工作线程数（默认自动检测 CPU 核心）
-v 详细日志输出
-h 显示帮助
架构
┌─────────────┐ ┌─────────────────┐ ┌──────────────┐
│ main.c │────▶│ server.c │────▶│ static.c │
│ (入口) │ │ (TCP 服务器) │ │ (静态文件) │
└─────────────┘ └─────────────────┘ └──────────────┘
│
▼
┌─────────────────┐
│ http.c │
│ (HTTP 解析) │
└─────────────────┘
│
▼
┌─────────────────┐
│ coco 协程库 │
│ (并发 + I/O) │
└─────────────────┘
模块职责
| 文件 | 职责 |
|---|---|
main.c |
程序入口、信号处理、命令行参数解析 |
server.c |
TCP 服务器生命周期：socket → bind → listen → accept → 协程分发 |
http.c |
HTTP/1.1 请求解析、响应头格式化、MIME 类型推断 |
static.c |
静态文件服务（sendfile）、目录浏览 HTML 生成、错误响应 |
cocoon.h |
公共配置结构体与错误码定义 |
核心 API 速览
HTTP 解析
http_request_t req;
int parsed = http_parse_request(buf, buf_len, &req);
// req.method, req.path, req.content_length, req.keep_alive ...
响应格式化
http_response_t resp = {
.status_code = 200,
.content_type = "text/html",
.content_length = file_size,
.keep_alive = true
};
int n = http_format_response_header(buf, sizeof(buf), &resp);
文件服务
static_serve_file(fd, &req, "/var/www/html");
static_serve_directory(fd, &req, "/var/www/html", real_path);
static_send_error(fd, 404, true);
安全设计
- 路径遍历防护：自动过滤
../，拒绝超出根目录的访问 - 目录隐藏：不显示以
.开头的隐藏文件 - HTML 转义：目录列表中的文件名自动转义，防止 XSS
- 请求方法过滤：仅允许
GET/HEAD，拒绝其他方法
性能
- 协程上下文切换：< 100ns（coco 基准）
- 单线程可支撑数万并发连接
- 多线程模式下 M:N 调度自动扩展至多核
示例页面
内置响应式示例首页，展示 Cocoon 三大特性：
渐变紫蓝背景 + 玻璃拟态卡片 + 移动端适配
路线图
- 支持
ETag/Last-Modified缓存协商 - Gzip / Brotli 动态压缩
- HTTPS / TLS 支持
- HTTP/2 多路复用
- 配置文件支持（JSON / YAML）
许可证
MIT © xfy
用 coco 孵化，为轻量而生。