---
name: run-http-file-server
description: Build, run, and smoke-test the Linux HTTP File Server (C + libevent). Use when asked to start the server, build it, test it, or interact with the running server.
---

所有路径均相对于项目根目录（`Linux-HTTP_File_Server/`）。

这是一个基于 **C + libevent** 的 Linux 原生 HTTP 静态文件服务器。在当前 Windows 环境下通过 **WSL2（Ubuntu 22.04）** 构建和运行。所有命令都通过 `wsl bash -c '...'` 执行。

快速烟雾测试（构建 + 启动 + 10 项 HTTP 检查 + 清理）：
```bash
wsl bash .claude/skills/run-http-file-server/smoke.sh
```

## 前置依赖

WSL2 + Ubuntu 22.04，需安装 GCC、make 和 libevent-dev：

```bash
wsl bash -c 'sudo apt-get update && sudo apt-get install -y build-essential libevent-dev'
# 当前环境已安装
```

## 构建

```bash
wsl bash -c 'cd /mnt/c/Users/34068/Project/Linux-HTTP_File_Server && make clean && make'
```

产物：`server.out`（项目根目录），目标文件在 `obj/`。

## 运行（Agent 路径）

### 快速烟雾测试

```bash
wsl bash .claude/skills/run-http-file-server/smoke.sh
```

全部通过时退出码为 0。测试项：构建、启动、目录列表、静态文件、Content-Type 头、Range 请求（206）、图片服务、POST 处理（服务端仅实现 GET）。

### 手动启动

```bash
# 后台启动服务
wsl bash -c 'cd /mnt/c/Users/34068/Project/Linux-HTTP_File_Server && nohup ./server.out > /tmp/http-server.log 2>&1 &'

# 等待服务就绪
wsl bash -c 'for i in $(seq 1 20); do curl -sf http://localhost:8080/ >/dev/null && break; sleep 0.5; done'

# 通过 curl 交互
wsl curl -s http://localhost:8080/
wsl curl -s -D - http://localhost:8080/some-file.txt | head

# 停止
wsl bash -c 'pkill -f server.out'
```

`server.conf` 控制端口（默认 8080）、根目录、超时和统计。

## 运行（人类路径）

```bash
cd /mnt/c/Users/34068/Project/Linux-HTTP_File_Server
./server.out      # 前台运行，Ctrl-C 停止
```

## 配置项

`server.conf` 位于项目根目录：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `root_dir` | `res/` | 静态资源根目录的绝对路径 |
| `port` | `8080` | 监听端口 |
| `timeout_seconds` | `60` | 读超时时间（秒） |
| `enable_connection_info` | `1` | 是否在 stdout 输出连接信息 |
| `enable_stats_logging` | `0` | 是否定期输出统计到日志文件 |
| `stats_timer` | `30` | 统计写入间隔（秒） |

## 测试

```bash
wsl bash .claude/skills/run-http-file-server/smoke.sh
```

烟雾脚本覆盖：构建、目录列表、URL 编码中文文件名的静态文件、Content-Type 检测、403 处理（不存在的文件）、HTTP Range（206）、二进制图片服务、POST 处理。

## 直接调用

如需在不启动完整服务器的情况下测试内部函数（如 URL 解码、MIME 类型查询、Range 解析），可编写小型 C 测试程序或单元测试。该项目目前尚无测试框架。

## 注意事项

- **WSL 路径转换**：项目在 WSL 中的路径为 `/mnt/c/Users/34068/Project/Linux-HTTP_File_Server`。`server.conf` 中的文件系统路径必须使用 Linux 路径格式。
- **`server.out` 必须从项目根目录启动**：它会 `chdir` 到配置的 `root_dir`。从错误目录启动会导致路径解析失败。
- **不存在的文件返回 403 而非 404**：`realpath()` 在不存在的路径上返回 NULL，代码将其视为"无效路径"（403）。这是已知行为特性，非 Bug。
- **无 Keep-Alive**：每个响应都带 `Connection: close`，每次请求都是全新的 TCP 连接。

## 故障排查

- **`curl: (7) Failed to connect`**：服务未运行或端口错误。先执行 `pkill -f server.out` 再重启。检查 `server.conf` 中的端口配置。
- **构建失败：`linux/limits.h: No such file or directory`**：未在 WSL 中构建（例如直接在 MINGW64/MSYS2 中）。该项目需要 Linux 头文件，请使用上述 `wsl bash` 方式。
- **`make: command not found`**：WSL 中未安装 `build-essential`。执行 `sudo apt-get install -y build-essential libevent-dev`。
- **服务启动但返回 HTTP 000**：服务端静默崩溃。检查日志文件或前台运行以查看错误信息。