xfy/lolly
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: remove stale AGENTS.md files, rewrite root AGENTS.md

Browse Source
This commit is contained in:
xfy 2026-06-03 23:47:29 +08:00
parent 29752f62bd
commit 6612819f3a
56 changed files with 51 additions and 2517 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
AGENTS.md
View File

@ -1,60 +1,64 @@
<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->
# lolly
## Purpose
高性能 HTTP 服务器，类似 nginx 的纯 Go 实现。使用 YAML 配置，单二进制运行，支持静态文件服务、反向代理、负载均衡、SSL/TLS、安全控制等功能。
高性能 HTTP 服务器，类似 nginx 的纯 Go 实现。YAML 配置，单二进制，支持反向代理、负载均衡、SSL/TLS、HTTP/2、HTTP/3、Lua 脚本。
## Key Files
Module: `rua.plus/lolly` | Go 1.26+ | CGO disabled (static builds)
| File | Description |
|------|-------------|
| `main.go` | 程序入口，CLI 参数解析和启动逻辑 |
| `go.mod` | Go 模块定义，依赖 fasthttp、zerolog、yaml.v3 |
| `go.sum` | 依赖版本锁定 |
| `Makefile` | 构建脚本，支持多平台编译、测试、覆盖率 |
| `lolly.yaml` | 默认配置文件示例 |
| `.gitignore` | Git 忽略规则 |
## Commands
## Subdirectories
```
make build # static build → bin/lolly
make test # unit tests only (./internal/...)
make test-integration # L2 integration tests (build tag: integration)
make test-e2e # L3 E2E tests (build tag: e2e, requires Docker)
make test-all # all three in parallel
make fmt # gofumpt (not go fmt)
make lint # golangci-lint (falls back to go vet)
make check # fmt → lint → test-all
```
| Directory | Purpose |
|-----------|---------|
| `internal/` | 核心业务代码（不可被外部导入） |
| `bin/` | 编译输出目录 |
| `docs/` | 项目文档和实现计划 |
| `examples/` | Lua 脚本示例 |
| `html/` | 静态 HTML 文件（测试/示例） |
| `scripts/` | 构建/测试辅助脚本（回归检测） |
Run a single test or package:
```
go test -v -run TestName ./internal/config/...
go test -v ./internal/server/...
```
## For AI Agents
Integration/E2E require build tags:
```
go test -v -tags=integration ./internal/integration/...
go test -v -tags=e2e ./internal/e2e/...
```
### Working In This Directory
- 这是 Go 项目，使用 `go mod` 管理依赖
- 使用 `make build` 构建二进制文件到 `bin/` 目录
- 使用 `make test` 运行测试，`make test-cover` 生成覆盖率报告
- 配置文件使用 YAML 格式，结构定义在 `internal/config/config.go`
- HTTP 库使用 fasthttp（比 net/http 快 6 倍），路由使用 fasthttp/router
- 日志库使用 zerolog（零分配，JSON 输出）
## Architecture
### Testing Requirements
- 运行测试前确保依赖已下载：`go mod download`
- 测试覆盖率目标 >80%
- 使用 `make check` 运行完整检查（fmt + lint + test）
- 使用 `lolly --generate-config` 生成完整配置文件模板
- `main.go` → `internal/app` — CLI entry; `app.Run()` owns lifecycle
- `internal/config` — YAML config structs; `config.go` is the root, split into `server_config.go`, `ssl_config.go`, `proxy_config.go`, etc.
- `internal/server` — HTTP server core: routing, middleware chain, vhosts, upgrade/reload, connection pool
- `internal/proxy` — reverse proxy + load balancing
- `internal/middleware/` — individual middleware packages (compression, bodylimit, security, rewrite, accesslog, errorintercept)
- `internal/handler` — static file handler and other request handlers
- `internal/lua` — embedded Lua scripting (gopher-lua)
- `internal/converter/nginx` — nginx config importer
- `internal/{http2,http3,stream,ssl,sslutil,cache,loadbalance,resolver,logging,variable,matcher}` — supporting packages
- `internal/e2e` — L3 E2E tests (testcontainers, build tag `e2e`)
- `internal/integration` — L2 integration tests (build tag `integration`)
### Common Patterns
- 配置结构体使用 `yaml` 标签，通过 `gopkg.in/yaml.v3` 解析
- 中间件使用 `fasthttp.RequestHandler` 函数签名
- 版本信息通过 `-ldflags` 在编译时注入
- 信号处理：SIGTERM/SIGINT 快速停止，SIGQUIT 优雅停止
## Key Conventions
## Dependencies
- HTTP stack: **fasthttp** + **fasthttp/router** (NOT net/http). All handlers use `fasthttp.RequestHandler` signature.
- Logging: **zerolog** (zero-alloc JSON). No fmt.Printf or log.Printf in production code.
- Config: YAML with `yaml` struct tags, parsed by `gopkg.in/yaml.v3`.
- Version: injected at build time via `-ldflags -X` into `internal/version`.
- Signals: SIGTERM/SIGINT = fast stop, SIGQUIT = graceful stop. Graceful upgrade via `internal/server/upgrade.go`.
- Formatter: **gofumpt** (stricter than gofmt). `make fmt` runs it.
- Linter: **golangci-lint** with v2 config (`.golangci.yml`). Uses `default: all` with many disabled — don't add new linter warnings.
- Build: always `CGO_ENABLED=0`, static linked, `-trimpath`.
- Tests use **testify** assertions.
### External
- `github.com/valyala/fasthttp` - 高性能 HTTP 服务器
- `github.com/fasthttp/router` - 基于 radix tree 的路由器
- `github.com/rs/zerolog` - 零分配 JSON 日志库
- `gopkg.in/yaml.v3` - YAML 解析库
## Gotchas
<!-- MANUAL: -->
- fasthttp uses `[]byte` strings, NOT `string`. Use `[]byte("literal")` or `fasthttp.AcquireRequest()` patterns. Don't mix net/http types.
- E2E tests need Docker running (testcontainers-go). If Docker is unavailable, run `make test-e2e-short` for testutil-only tests.
- Config file path defaults to `lolly.yaml` in CWD. Use `-c path` or `--config path`.
- `--generate-config` outputs a full config template; `-o file` writes to file.
- `--import nginx.conf` converts nginx config to lolly YAML.

76
docs/AGENTS.md
View File

@ -1,76 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-13 -->
# docs
## Purpose
项目文档目录，包含实现计划、nginx 功能参考文档、代码规范和开发指南。
## Key Files
| File | Description |
|------|-------------|
| `plan.md` | 实现计划，定义 6 个开发阶段和任务列表（关键文件，高频访问） |
| `README.md` | 项目概述文档 |
| `prompts.md` | 开发提示和 AI 交互指南 |
| `comments.md` | 代码注释规范（必须遵循） |
| `13-git-commit-guide.md` | Git 提交规范指南 |
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `config/` | nginx 配置示例和功能对照表 |
| `lua/` | Lua 功能文档和 API 参考 |
| `lua-nginx-module/` | lua-nginx-module 文档 |
### nginx 功能参考文档
| File | Description |
|------|-------------|
| `01-nginx-overview.md` | nginx 概述和架构介绍 |
| `02-nginx-installation.md` | nginx 安装指南 |
| `03-nginx-http-core.md` | HTTP 核心功能参考 |
| `04-nginx-proxy-loadbalancing.md` | 反向代理和负载均衡参考 |
| `05-nginx-ssl-https.md` | SSL/HTTPS 配置参考 |
| `06-nginx-rewrite.md` | URL 重写规则参考 |
| `07-nginx-compression-caching.md` | 压缩和缓存配置参考 |
| `08-nginx-logging-monitoring.md` | 日志和监控配置参考 |
| `09-nginx-security.md` | 安全控制参考 |
| `10-nginx-stream-tcp-udp.md` | TCP/UDP Stream 代理参考 |
| `11-nginx-mail-proxy.md` | 邮件代理参考 |
| `12-nginx-performance-tuning.md` | 性能调优参考 |
| `14-nginx-grpc-uwsgi.md` | gRPC/uWSGI/SCGI 代理参考 |
| `15-nginx-advanced-features.md` | 高级特性参考 |
| `16-nginx-internal-redirect.md` | 内部重定向参考 |
| `17-nginx-mirror-slice.md` | 镜像与切片参考 |
| `18-nginx-memcached.md` | Memcached 集成参考 |
| `19-nginx-http-modules-detail.md` | HTTP 功能模块详解 |
| `20-nginx-rate-limiting.md` | 限流与连接控制参考 |
| `21-nginx-http2-http3.md` | HTTP/2 与 HTTP/3 参考 |
| `22-nginx-third-party-modules.md` | 第三方扩展模块参考 |
| `23-nginx-special-modules.md` | 特殊功能模块参考 |
| `24-nginx-core-events.md` | 核心与事件模块参考 |
## For AI Agents
### Working In This Directory
- `plan.md` 是开发的核心参考，定义了各阶段的任务和验证方法
- 修改代码前应先查阅对应的 nginx 参考文档了解功能需求
- 代码注释必须遵循 `comments.md` 规范
- Git 提交格式遵循 `13-git-commit-guide.md`
### Testing Requirements
- 文档无测试要求，但修改代码后需按 `plan.md` 中的验证方法测试
### Common Patterns
- 参考文档采用 nginx 配置对比方式说明功能
- plan.md 使用阶段划分（Phase 1-6）组织任务
- 每个阶段有明确的任务列表和验证方法
## Dependencies
### Internal
- `../internal/` - 实现代码目录，文档描述的功能在此实现
<!-- MANUAL: -->

47
docs/config/AGENTS.md
View File

@ -1,47 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
# config
## Purpose
nginx 配置示例目录，展示 lolly 需要兼容的功能特性，用于功能对照和迁移参考。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 目录结构和功能对照表（关键参考文件） |
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `basic/` | 基础配置：静态服务器、反向代理、虚拟主机 |
| `ssl/` | SSL/TLS 配置：HTTPS、mTLS、OCSP、HSTS |
| `load-balancing/` | 负载均衡：轮询、加权、最少连接、IP 哈希、一致性哈希 |
| `advanced/` | 高级功能：WebSocket、gRPC、HTTP/2、HTTP/3、Stream |
| `security/` | 安全配置：限流、连接限制、访问控制、认证、安全头 |
| `caching/` | 缓存配置：代理缓存、Gzip、Brotli |
| `rewriting/` | URL 重写：rewrite 规则、重定向 |
| `lua/` | Lua 配置：基础 Lua、access_by_lua、content_by_lua、balancer_by_lua |
## For AI Agents
### Working In This Directory
- `README.md` 包含 nginx 指令与 lolly 配置对照表（关键参考）
- 每个子目录包含 nginx 配置文件和对应的 lolly YAML 注释
- 修改功能时应先查阅对应目录了解 nginx 兼容需求
### Testing Requirements
- 配置示例通过集成测试验证功能兼容性
### Common Patterns
- 配置对照格式：nginx 指令 ↔ lolly YAML 配置项
- 功能覆盖：负载均衡、SSL、安全、代理、缓存、重写、Lua
## Dependencies
### Internal
- `../../internal/config` - lolly 配置解析实现
<!-- MANUAL: -->

44
docs/config/advanced/AGENTS.md
View File

@ -1,44 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# advanced
## Purpose
高级功能配置示例目录，包含 WebSocket、gRPC、HTTP/2、HTTP/3、Stream 代理等高级协议配置。
## Key Files
| File | Description |
|------|-------------|
| `websocket.conf` | WebSocket 代理配置：Upgrade 头处理、长连接支持 |
| `grpc.conf` | gRPC 代理配置：HTTP/2 透传、超时设置 |
| `http2.conf` | HTTP/2 配置：多路复用、服务器推送、流控制 |
| `http3.conf` | HTTP/3 (QUIC) 配置：UDP 传输、0-RTT 连接 |
| `stream-tcp.conf` | TCP Stream 代理：四层负载均衡、连接复用 |
| `stream-udp.conf` | UDP Stream 代理：DNS 负载均衡、无状态转发 |
## For AI Agents
### Working In This Directory
- HTTP/2 需要 HTTPS，HTTP/3 需要 QUIC 支持
- Stream 代理工作在四层（TCP/UDP），不解析 HTTP
- WebSocket 需要正确处理 Upgrade 和 Connection 头
### Testing Requirements
- 高级协议通过集成测试验证
- HTTP/3 测试需要 QUIC 客户端支持
### Common Patterns
- WebSocket：`proxy_set_header Upgrade $http_upgrade`
- gRPC：`grpc_pass grpc://upstream`
- Stream：`listen 12345` 在 stream 块中
## Dependencies
### Internal
- `../../../internal/http2/` - HTTP/2 实现
- `../../../internal/http3/` - HTTP/3 (QUIC) 实现
- `../../../internal/stream/` - Stream 代理实现
- `../../../internal/proxy/websocket.go` - WebSocket 代理
<!-- MANUAL: -->

38
docs/config/basic/AGENTS.md
View File

@ -1,38 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# basic
## Purpose
基础配置示例目录，包含静态文件服务器、反向代理、虚拟主机等核心功能的 nginx 配置示例。
## Key Files
| File | Description |
|------|-------------|
| `static-server.conf` | 静态文件服务器配置：sendfile、try_files、缓存策略 |
| `reverse-proxy.conf` | 反向代理配置：proxy_pass、超时设置、缓冲配置 |
| `virtual-host.conf` | 虚拟主机配置：多域名、server_name 匹配 |
## For AI Agents
### Working In This Directory
- 每个配置文件包含 Lolly YAML 对照注释
- 修改基础功能时应参考这些配置了解 nginx 兼容需求
- 配置文件使用 nginx 指令风格，注释说明 Lolly 对应项
### Testing Requirements
- 配置示例通过集成测试验证功能兼容性
- 运行测试：`go test ./internal/integration/...`
### Common Patterns
- 配置对照格式：nginx 指令 ↔ Lolly YAML 配置项
- 注释使用 `# Lolly 对应:` 标记映射关系
## Dependencies
### Internal
- `../../../internal/config/` - Lolly 配置解析实现
- `../../../internal/handler/` - 静态文件处理器
<!-- MANUAL: -->

40
docs/config/caching/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# caching
## Purpose
缓存配置示例目录，包含代理缓存、Gzip 压缩、Brotli 压缩等性能优化配置。
## Key Files
| File | Description |
|------|-------------|
| `proxy-cache.conf` | 代理缓存：响应缓存、缓存键、过期策略 |
| `gzip.conf` | Gzip 压缩：文本压缩、压缩级别、MIME 类型 |
| `brotli.conf` | Brotli 压缩：更高压缩率、现代浏览器支持 |
## For AI Agents
### Working In This Directory
- 代理缓存适用于后端响应不频繁变化的场景
- Gzip 是通用压缩方案，所有浏览器支持
- Brotli 压缩率更高，但需要浏览器支持
- 压缩级别建议 4-6，平衡 CPU 和压缩率
### Testing Requirements
- 缓存配置通过集成测试验证
- 压缩测试验证 Content-Encoding 头
### Common Patterns
- 缓存键：`$scheme$host$request_uri`
- 缓存控制：`X-Cache-Status` 头
- 压缩条件：`gzip_types text/plain text/css application/json`
## Dependencies
### Internal
- `../../../internal/cache/` - 文件缓存实现
- `../../../internal/middleware/compression/` - 压缩中间件
<!-- MANUAL: -->

43
docs/config/load-balancing/AGENTS.md
View File

@ -1,43 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# load-balancing
## Purpose
负载均衡配置示例目录，包含轮询、加权、最少连接、IP 哈希、一致性哈希等负载均衡策略配置。
## Key Files
| File | Description |
|------|-------------|
| `round-robin.conf` | 轮询负载均衡：默认策略、均匀分配 |
| `weighted.conf` | 加权轮询：按权重分配流量、服务器能力差异 |
| `least-conn.conf` | 最少连接：动态分配到连接最少的服务器 |
| `ip-hash.conf` | IP 哈希：会话保持、同一客户端固定后端 |
| `consistent-hash.conf` | 一致性哈希：分布式缓存、节点增减影响最小化 |
## For AI Agents
### Working In This Directory
- 默认策略是轮询（round-robin）
- 加权适用于服务器性能差异场景
- 最少连接适用于长连接场景
- IP 哈希适用于需要会话保持的场景
- 一致性哈希适用于分布式缓存场景
### Testing Requirements
- 负载均衡策略通过单元测试和集成测试验证
- 运行测试：`go test ./internal/loadbalance/...`
### Common Patterns
- 权重配置：`weight=N` 参数
- 健康检查：`max_fails`, `fail_timeout`
- 备用服务器：`backup` 标记
## Dependencies
### Internal
- `../../../internal/loadbalance/` - 负载均衡策略实现
- `../../../internal/resolver/` - 动态 DNS 解析
<!-- MANUAL: -->

45
docs/config/lua/AGENTS.md
View File

@ -1,45 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# lua
## Purpose
Lua 配置示例目录，包含 Lua 脚本集成、各阶段钩子、共享字典等 Lua 功能配置。
## Key Files
| File | Description |
|------|-------------|
| `basic-lua.conf` | 基础 Lua 配置：脚本加载、基本语法 |
| `access-by-lua.conf` | access 阶段 Lua：访问控制、认证检查 |
| `content-by-lua.conf` | content 阶段 Lua：动态内容生成 |
| `balancer-by-lua.conf` | 负载均衡 Lua：动态上游选择 |
| `shared-dict.conf` | 共享字典：进程间数据共享、缓存 |
## For AI Agents
### Working In This Directory
- Lua 钩子按 nginx 处理阶段执行：rewrite → access → content
- 共享字典用于进程间数据共享，适合缓存场景
- Lua 代码在沙箱中执行，有安全限制
- 参考 OpenResty 风格的 ngx API
### Testing Requirements
- Lua 脚本通过集成测试验证
- 运行测试：`go test ./internal/lua/...`
### Common Patterns
- 访问控制：`access_by_lua_block { ... }`
- 动态内容：`content_by_lua_block { ngx.say(...) }`
- 共享字典：`lua_shared_dict cache 10m`
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎实现
- `../../../docs/lua-nginx-module/` - lua-nginx-module 文档参考
### External
- `github.com/yuin/gopher-lua` - Go Lua 解释器
<!-- MANUAL: -->

39
docs/config/rewriting/AGENTS.md
View File

@ -1,39 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# rewriting
## Purpose
URL 重写配置示例目录，包含 rewrite 规则、重定向等 URL 处理配置。
## Key Files
| File | Description |
|------|-------------|
| `rewrite-rules.conf` | URL 重写规则：正则匹配、变量替换、内部重定向 |
| `redirect.conf` | 重定向配置：301/302 跳转、域名迁移 |
## For AI Agents
### Working In This Directory
- rewrite 使用正则表达式匹配 URL
- last 表示重写后重新匹配 location
- break 表示重写后直接处理，不再匹配
- redirect 返回 302，permanent 返回 301
### Testing Requirements
- 重写规则通过单元测试验证
- 测试正则匹配和变量替换正确性
### Common Patterns
- 正则捕获：`rewrite ^/user/(\d+)$ /profile?id=$1 last`
- 域名迁移：`return 301 https://new.domain.com$request_uri`
- HTTP 转 HTTPS：`return 301 https://$host$request_uri`
## Dependencies
### Internal
- `../../../internal/middleware/rewrite/` - 重写中间件实现
- `../../../internal/handler/` - 请求处理器
<!-- MANUAL: -->

43
docs/config/security/AGENTS.md
View File

@ -1,43 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# security
## Purpose
安全配置示例目录，包含访问控制、认证、限流、连接限制、安全头部等安全防护配置。
## Key Files
| File | Description |
|------|-------------|
| `access-control.conf` | 访问控制：IP 白名单/黑名单、allow/deny 规则 |
| `basic-auth.conf` | Basic 认证：用户名密码保护、htpasswd 文件 |
| `auth-request.conf` | 子请求认证：外部认证服务集成 |
| `rate-limit.conf` | 请求限流：令牌桶、漏桶、请求速率控制 |
| `conn-limit.conf` | 连接限制：并发连接数、单 IP 连接限制 |
| `security-headers.conf` | 安全头部：X-Frame-Options、CSP、HSTS |
## For AI Agents
### Working In This Directory
- 访问控制按顺序匹配：先检查黑名单，再检查白名单
- Basic Auth 使用 bcrypt 密码哈希
- 限流使用令牌桶算法，支持按 IP/全局限流
- 安全头部建议全部启用
### Testing Requirements
- 安全配置通过单元测试验证
- 运行测试：`go test ./internal/middleware/security/...`
### Common Patterns
- 认证失败返回 401 Unauthorized
- 限流触发返回 429 Too Many Requests
- 访问拒绝返回 403 Forbidden
## Dependencies
### Internal
- `../../../internal/middleware/security/` - 安全中间件实现
- `../../../internal/config/` - 安全配置解析
<!-- MANUAL: -->

40
docs/config/ssl/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# ssl
## Purpose
SSL/TLS 配置示例目录，包含 HTTPS、mTLS、OCSP Stapling、HSTS 等安全传输配置示例。
## Key Files
| File | Description |
|------|-------------|
| `basic-ssl.conf` | 基础 HTTPS 配置：证书、TLS 协议、加密套件、HTTP/2 |
| `hsts.conf` | HSTS 配置：Strict-Transport-Security、预加载 |
| `mtls.conf` | 双向 TLS 认证：客户端证书验证、CA 配置 |
| `ocsp-stapling.conf` | OCSP Stapling：在线证书状态验证、缓存配置 |
## For AI Agents
### Working In This Directory
- TLS 1.0/1.1 已弃用，推荐使用 TLS 1.2/1.3
- 加密套件推荐使用 AEAD（AES-GCM、CHACHA20-POLY1305）
- Session Tickets 禁用更安全，但会影响会话恢复性能
### Testing Requirements
- SSL 配置通过集成测试验证
- 测试证书位于 `internal/ssl/testdata/`
### Common Patterns
- 证书路径：`ssl.cert`, `ssl.key`, `ssl.cert_chain`
- 协议配置：`ssl.protocols: ["TLSv1.2", "TLSv1.3"]`
- HTTP/2 启用：`ssl.http2.enabled: true`
## Dependencies
### Internal
- `../../../internal/ssl/` - SSL 证书加载和管理
- `../../../internal/sslutil/` - SSL 工具函数
<!-- MANUAL: -->

48
docs/lua/AGENTS.md
View File

@ -1,48 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
# lua
## Purpose
Lua 功能文档目录，包含 API 参考、使用指南和最佳实践示例。
## Key Files
| File | Description |
|------|-------------|
| `API.md` | Lua Engine API 参考（定时器限制、安全/不安全 API 区分） |
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `api-gateway/` | API 网关使用示例 |
| `authentication/` | 认证功能示例 |
| `caching/` | 缓存使用示例 |
| `dynamic-routing/` | 动态路由示例 |
| `logging-monitoring/` | 日志和监控示例 |
| `middleware/` | 中间件使用示例 |
| `rate-limiting/` | 限流功能示例 |
| `websocket/` | WebSocket 功能示例 |
## For AI Agents
### Working In This Directory
- `API.md` 是关键参考，说明定时器回调限制和 API 可用性
- 定时器回调不能捕获闭包变量，必须使用 `ngx.shared.DICT` 传递数据
- Request-scoped API（ngx.req、ngx.resp、ngx.var、ngx.ctx）在定时器回调中不可用
### Testing Requirements
- Lua 功能通过 `../../internal/lua` 测试验证
### Common Patterns
- 安全 API（timer 可用）：`ngx.shared.DICT.*`, `ngx.log`, `ngx.timer.*`
- 不安全 API（仅请求协程）：`ngx.req.*`, `ngx.resp.*`, `ngx.var.*`, `ngx.ctx.*`
## Dependencies
### Internal
- `../../internal/lua` - Lua 引擎实现
- `../../examples/lua-scripts` - 脚本示例
<!-- MANUAL: -->

44
docs/lua/api-gateway/AGENTS.md
View File

@ -1,44 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# api-gateway
## Purpose
API 网关示例项目，演示如何使用 Lua 脚本实现动态路由、认证、限流、健康检查等网关核心功能。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 项目说明：功能特性、快速开始、配置示例 |
| `gateway.lua` | 网关主逻辑：路由、认证、限流、错误处理 |
| `upstream.lua` | 上游服务管理：健康检查、故障剔除、动态负载均衡 |
| `nginx.conf` | NGINX 配置示例：Lua 脚本集成方式 |
## For AI Agents
### Working In This Directory
- 基于 OpenResty / lua-nginx-module 风格
- 路由规则在 `gateway.lua` 的 `routes` 表中定义
- 上游节点在 `upstream.lua` 的 `upstreams` 表中配置
- 生产环境建议使用 Redis 替代共享字典存储
### Testing Requirements
- Lua 脚本通过集成测试验证
- 测试框架：`internal/lua/` 模块测试
### Common Patterns
- 路由匹配：路径 + 方法 + Header 组合
- 限流算法：令牌桶滑动窗口
- 健康检查：被动探测 + 故障剔除
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎实现
- `../../../internal/loadbalance/` - 负载均衡策略
### External
- OpenResty / lua-nginx-module - Lua 运行环境
<!-- MANUAL: -->

41
docs/lua/authentication/AGENTS.md
View File

@ -1,41 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# authentication
## Purpose
认证示例目录，演示如何使用 Lua 实现 Basic Auth、JWT 验证等认证功能。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 功能说明和使用指南 |
| `basic_auth.lua` | Basic Auth 认证：用户名密码验证、bcrypt 哈希 |
| `jwt_validate.lua` | JWT 验证：令牌解析、签名验证、过期检查 |
| `nginx.conf` | NGINX 配置示例：认证钩子集成 |
## For AI Agents
### Working In This Directory
- Basic Auth 使用 bcrypt 密码哈希存储
- JWT 验证支持 HS256、RS256 算法
- 认证失败返回 401 Unauthorized
- 可与外部认证服务集成
### Testing Requirements
- 认证逻辑通过单元测试验证
- 测试密码验证、令牌解析正确性
### Common Patterns
- Basic Auth：解析 Authorization 头，验证用户名密码
- JWT：解析 Bearer 令牌，验证签名和有效期
- 错误响应：`ngx.exit(401)`
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎
- `../../../internal/middleware/security/auth.go` - 认证中间件
<!-- MANUAL: -->

40
docs/lua/caching/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# caching
## Purpose
缓存示例目录，演示如何使用 Lua 实现响应缓存、缓存失效等缓存功能。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 功能说明和使用指南 |
| `cache_handler.lua` | 缓存处理器：缓存键生成、存储/读取、过期管理 |
| `nginx.conf` | NGINX 配置示例：共享字典缓存配置 |
## For AI Agents
### Working In This Directory
- 使用共享字典（shared dict）存储缓存数据
- 缓存键通常基于 URL、请求头、参数组合
- 支持缓存过期时间配置
- 缓存失效策略：TTL、主动清除
### Testing Requirements
- 缓存逻辑通过单元测试验证
- 测试缓存命中/未命中、过期清理
### Common Patterns
- 缓存键：`local key = ngx.md5(ngx.var.uri .. ngx.var.args)`
- 缓存读取：`local data = shared_dict:get(key)`
- 缓存写入：`shared_dict:set(key, data, ttl)`
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎
- `../../../internal/cache/` - 文件缓存实现
<!-- MANUAL: -->

40
docs/lua/dynamic-routing/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# dynamic-routing
## Purpose
动态路由示例目录，演示如何使用 Lua 实现基于路径、方法、Header 的动态路由。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 功能说明和使用指南 |
| `router.lua` | 路由器实现：路由规则匹配、上游选择 |
| `nginx.conf` | NGINX 配置示例：动态路由集成 |
## For AI Agents
### Working In This Directory
- 路由规则支持正则表达式匹配
- 支持按路径、方法、Header 组合匹配
- 动态上游选择支持负载均衡
- 路由规则可热更新
### Testing Requirements
- 路由逻辑通过单元测试验证
- 测试路由匹配、上游选择正确性
### Common Patterns
- 路由表：`local routes = { ["/api/*"] = "api_upstream" }`
- 匹配逻辑：遍历路由表，正则匹配请求路径
- 上游设置：`ngx.var.upstream = matched_upstream`
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎
- `../../../internal/loadbalance/` - 负载均衡实现
<!-- MANUAL: -->

41
docs/lua/logging-monitoring/AGENTS.md
View File

@ -1,41 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# logging-monitoring
## Purpose
日志和监控示例目录，演示如何使用 Lua 实现自定义日志格式、指标收集等监控功能。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 功能说明和使用指南 |
| `log_formatter.lua` | 日志格式化器：自定义日志格式、字段提取 |
| `metrics.lua` | 指标收集：请求计数、延迟统计、Prometheus 格式 |
| `nginx.conf` | NGINX 配置示例：日志钩子集成 |
## For AI Agents
### Working In This Directory
- 日志格式支持 JSON、文本格式
- 指标可导出为 Prometheus 格式
- 支持请求级别的详细日志
- 监控数据可存储到共享字典
### Testing Requirements
- 日志和指标逻辑通过单元测试验证
- 测试日志格式、指标计算正确性
### Common Patterns
- 日志字段：`ngx.log(ngx.INFO, json.encode(log_entry))`
- 指标计数：`metrics_dict:incr("request_count")`
- Prometheus 格式：`# TYPE http_requests_total counter`
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎
- `../../../internal/logging/` - 日志系统实现
<!-- MANUAL: -->

38
docs/lua/middleware/AGENTS.md
View File

@ -1,38 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# middleware
## Purpose
中间件示例目录，演示 Lua 中间件的概念和用法。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 中间件概念说明和使用指南 |
## For AI Agents
### Working In This Directory
- 中间件按处理阶段执行：rewrite → access → content → log
- 中间件可链式组合
- 支持请求修改和响应拦截
- 参考 OpenResty 风格的中间件模式
### Testing Requirements
- 中间件逻辑通过集成测试验证
- 测试中间件链执行顺序
### Common Patterns
- 链式调用：按注册顺序执行
- 请求修改：`ngx.req.set_header()`
- 响应拦截：`ngx.exit()` 提前返回
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎
- `../../../internal/middleware/` - 中间件框架实现
<!-- MANUAL: -->

40
docs/lua/rate-limiting/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# rate-limiting
## Purpose
限流示例目录，演示如何使用 Lua 实现请求限流、令牌桶算法等限流功能。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 功能说明和使用指南 |
| `access.lua` | 限流实现：令牌桶、滑动窗口、请求计数 |
| `nginx.conf` | NGINX 配置示例：限流钩子集成 |
## For AI Agents
### Working In This Directory
- 令牌桶算法：固定速率生成令牌，请求消耗令牌
- 滑动窗口：统计时间窗口内请求数
- 支持按 IP、全局限流
- 限流触发返回 429 Too Many Requests
### Testing Requirements
- 限流逻辑通过单元测试验证
- 测试令牌桶、滑动窗口算法正确性
### Common Patterns
- 令牌桶：`local tokens = min(max_tokens, tokens + rate * elapsed)`
- 限流检查：`if tokens < 1 then ngx.exit(429) end`
- 滑动窗口：使用共享字典存储请求时间戳
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎
- `../../../internal/middleware/security/ratelimit.go` - 限流中间件
<!-- MANUAL: -->

40
docs/lua/websocket/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
# websocket
## Purpose
WebSocket 示例目录，演示如何使用 Lua 实现 WebSocket 服务器和客户端功能。
## Key Files
| File | Description |
|------|-------------|
| `README.md` | 功能说明和使用指南 |
| `ws_handler.lua` | WebSocket 处理器：握手、消息收发、连接管理 |
| `nginx.conf` | NGINX 配置示例：WebSocket 代理配置 |
## For AI Agents
### Working In This Directory
- WebSocket 需要正确处理 Upgrade 和 Connection 头
- 支持双向消息传递
- 需要处理连接保活（ping/pong）
- 错误处理：连接断开、协议错误
### Testing Requirements
- WebSocket 逻辑通过集成测试验证
- 测试握手、消息收发、连接关闭
### Common Patterns
- 握手验证：检查 `Upgrade: websocket` 头
- 消息循环：`while true do local data = ws:recv() end`
- 心跳：定期发送 ping 帧
## Dependencies
### Internal
- `../../../internal/lua/` - Lua 脚本引擎
- `../../../internal/proxy/websocket.go` - WebSocket 代理实现
<!-- MANUAL: -->

25
examples/AGENTS.md
View File

@ -1,25 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
# examples
## Purpose
示例目录，包含 Lua 脚本示例展示 lolly 的脚本嵌入能力。
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `lua-scripts/` | Lua 脚本示例（认证、日志、定时器等） |
## For AI Agents
### Working In This Directory
- 示例脚本用于演示功能，不参与生产运行
- 脚本遵循 OpenResty API 兼容风格
- 修改示例时参考 `docs/lua/API.md` 了解 API 限制
### Testing Requirements
- 示例脚本通过 `internal/lua` 测试间接验证
<!-- MANUAL: -->

50
examples/lua-scripts/AGENTS.md
View File

@ -1,50 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
# lua-scripts
## Purpose
Lua 脚本示例集合，展示 lolly Lua 沙箱的各种用法。
## Key Files
| File | Description |
|------|-------------|
| `auth.lua` | Access 阶段认证检查示例（token 验证） |
| `content.lua` | Content 阶段内容生成示例 |
| `log.lua` | Log 阶段日志记录示例 |
| `timer.lua` | 定时器使用示例（ngx.timer.at） |
| `shared_dict.lua` | 共享字典使用示例 |
| `subrequest.lua` | 子请求示例（ngx.location.capture） |
## For AI Agents
### Working In This Directory
- 示例脚本演示典型用法，可作为配置参考
- 脚本使用 OpenResty 兼容的 `ngx.*` API
- 定时器回调不能捕获闭包变量，需使用 `ngx.shared.DICT` 传递数据
### Testing Requirements
- 示例脚本通过集成测试验证功能
### Common Patterns
```lua
-- Access 阶段认证
local auth_header = ngx.req.get_headers()["Authorization"]
if not auth_header then
ngx.exit(401)
end
-- 定时器（使用 shared_dict 传递数据）
ngx.shared.timer_data:set("key", ngx.var.request_id)
ngx.timer.at(5, function()
ngx.log(ngx.INFO, ngx.shared.timer_data:get("key"))
end)
```
## Dependencies
### Internal
- `../../internal/lua` - Lua 引擎实现
<!-- MANUAL: -->

67
internal/AGENTS.md
View File

@ -1,67 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->
# internal
## Purpose
核心业务代码目录，包含服务器、配置、处理器、中间件、日志等模块。Go 的 internal 包机制确保这些代码不可被外部项目导入。
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息、nginx 配置导入） |
| `benchmark/` | 基准测试基础设施（Mock 后端、负载生成器、回归检测） |
| `cache/` | 文件缓存模块（缓存存储、过期管理、stale 回退） |
| `config/` | 配置解析、验证和默认值生成 |
| `converter/` | 配置转换器（nginx 配置导入） |
| `e2e/` | 端到端测试（完整功能验证、容器化测试） |
| `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile、ETag） |
| `http2/` | HTTP/2 协议支持（ALPN 协商、fasthttp 适配） |
| `http3/` | HTTP/3 (QUIC) 协议支持（fasthttp 适配、0-RTT） |
| `integration/` | 集成测试（多模块端到端协作验证） |
| `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） |
| `logging/` | 日志系统（zerolog 初始化、访问日志） |
| `lua/` | Lua 脚本引擎（OpenResty 风格沙箱、ngx API） |
| `matcher/` | 路径匹配器（精确、前缀、正则匹配） |
| `middleware/` | 中间件框架（接口定义、链式组合） |
| `mimeutil/` | MIME 类型检测（扩展名映射、类型推断） |
| `netutil/` | 网络工具函数（客户端 IP 提取、URL 解析） |
| `proxy/` | 反向代理模块（HTTP/WebSocket 代理、DNS 解析） |
| `resolver/` | DNS 解析器（缓存、后台刷新、域名动态解析） |
| `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 |
| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling、Session Tickets） |
| `sslutil/` | SSL 工具函数（证书池加载、CA 信任链） |
| `stream/` | TCP/UDP Stream 代理模块 |
| `testutil/` | 测试工具函数（Mock、断言助手） |
| `utils/` | HTTP 错误处理（统一错误响应助手） |
| `variable/` | 变量系统（nginx 风格变量展开、日志格式模板） |
## For AI Agents
### Working In This Directory
- 所有包使用 `rua.plus/lolly/internal/{package}` 导入路径
- 各子包有独立职责，遵循 Go 包设计原则
- 添加新功能时应参考 `docs/plan.md` 确定所属模块
- 测试文件与源文件同目录，使用 `_test.go` 后缀
### Testing Requirements
- 每个包应有对应的测试文件
- 运行测试：`go test ./internal/...`
- 测试覆盖率目标 >80%
### Common Patterns
- 使用 fasthttp 的 `RequestHandler` 函数签名处理请求
- 配置结构体使用 `yaml` 标签
- 中间件通过 `Chain.Apply()` 逆序包装
- 服务器通过 `fasthttp.Server` 配置超时和连接限制
## Dependencies
### External
- `github.com/valyala/fasthttp` - HTTP 服务器框架
- `github.com/fasthttp/router` - 路由器
- `github.com/rs/zerolog` - 日志库
- `gopkg.in/yaml.v3` - YAML 解析
<!-- MANUAL: -->

43
internal/app/AGENTS.md
View File

@ -1,43 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->
# app
## Purpose
应用程序入口包，提供启动逻辑、信号处理、版本信息显示、配置生成和 nginx 配置导入功能。
## Key Files
| File | Description |
|------|-------------|
| `app.go` | 核心逻辑：Run 入口、startServer、printVersion、generateConfig |
| `import.go` | nginx 配置导入：ImportNginxConfig、转换警告处理 |
| `app_test.go` | 单元测试：版本显示、配置生成、服务器启动测试 |
## For AI Agents
### Working In This Directory
- 版本信息变量通过 `-ldflags` 在编译时注入，不要硬编码修改
- `Run()` 是程序入口函数，返回退出码
- 信号处理：SIGTERM/SIGINT 快速停止，SIGQUIT 优雅停止（等待 30s）
- `generateConfig()` 生成默认 YAML 配置，调用 `config.DefaultConfig()`
- `ImportNginxConfig()` 将 nginx 配置转换为 lolly YAML 格式
### Testing Requirements
- 测试文件 `app_test.go` 包含启动逻辑测试
- 运行测试：`go test ./internal/app/...`
- 测试覆盖率目标 >80%
### Common Patterns
- 使用 `os.Signal` 和 `signal.Notify` 处理系统信号
- 服务器启动在 goroutine 中执行，通过 channel 等待错误或信号
- `shutdownTimeout` 定义优雅停止超时时间
## Dependencies
### Internal
- `../config/` - 配置加载和验证
- `../server/` - HTTP 服务器创建和启动
- `../converter/nginx/` - nginx 配置转换器
<!-- MANUAL: -->

43
internal/benchmark/AGENTS.md
View File

@ -1,43 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
# benchmark
## Purpose
基准测试基础设施目录，提供负载生成、Mock 后端和测试数据生成工具，用于验证服务器性能和回归检测。
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `tools/` | 基准测试工具集（Mock 后端、负载生成器、测试数据生成） |
## For AI Agents
### Working In This Directory
- 基准测试使用 Go 的 testing.B 框架
- Mock 后端使用 fasthttputil.InmemoryListener 进行内存通信
- 负载生成器支持并发请求和延迟统计
### Testing Requirements
- 运行基准测试：`go test -bench=. ./internal/benchmark/...`
- 基准测试文件使用 `_bench_test.go` 后缀
- 使用 `make benchmark` 运行完整基准测试套件
### Common Patterns
- 使用 `fasthttputil.NewInmemoryListener` 避免网络开销
- 统计收集：QPS、P50/P90/P99 延迟、错误率
- 回归检测通过 `scripts/check_regression.py` 自动执行
## Dependencies
### Internal
- `rua.plus/lolly/internal/proxy` - 代理模块基准测试
- `rua.plus/lolly/internal/cache` - 缓存模块基准测试
- `rua.plus/lolly/internal/loadbalance` - 负载均衡基准测试
### External
- `github.com/valyala/fasthttp` - HTTP 客户端/服务器
- `github.com/valyala/fasthttp/fasthttputil` - 内存测试工具
<!-- MANUAL: -->

38
internal/cache/AGENTS.md vendored
View File

@ -1,38 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# cache
## Purpose
文件缓存模块，提供静态文件的内存缓存和过期管理功能。
## Key Files
| File | Description |
|------|-------------|
| `file_cache.go` | 文件缓存核心：FileCache 结构体、Get/Set/Delete、TTL 管理、LRU 淘汰 |
| `cache_test.go` | 缓存单元测试 |
## For AI Agents
### Working In This Directory
- 缓存项包含文件内容、MIME 类型、最后修改时间
- TTL 默认 5 分钟，可配置
- LRU 淘汰策略，最大缓存大小可配置
- 支持缓存失效和手动清除
### Testing Requirements
- 运行测试：`go test ./internal/cache/...`
- 测试缓存存取、过期淘汰、并发安全
### Common Patterns
- 使用 `sync.RWMutex` 保证并发安全
- 缓存键为文件路径的哈希值
- 缓存命中时直接返回内容，避免磁盘 I/O
## Dependencies
### Internal
- `../config/` - 缓存配置参数
<!-- MANUAL: -->

45
internal/config/AGENTS.md
View File

@ -1,45 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
# config
## Purpose
配置模块，提供 YAML 配置文件的解析、验证、默认值生成和序列化功能。是整个项目的核心依赖模块（高频访问）。
## Key Files
| File | Description |
|------|-------------|
| `config.go` | 配置结构体定义：Config、ServerConfig、ProxyConfig、SSLConfig 等 |
| `defaults.go` | 默认配置生成：DefaultConfig()、GenerateConfigYAML()（高频访问） |
| `validate.go` | 配置验证：validateServer、validateSSL、validateSecurity 等 |
| `config_test.go` | 配置解析测试 |
| `defaults_test.go` | 默认配置测试 |
| `validate_test.go` | 验证逻辑测试 |
## For AI Agents
### Working In This Directory
- 所有配置结构体使用 `yaml` 标签，支持 YAML 序列化/反序列化
- `Load()` 加载配置文件，自动调用验证
- `DefaultConfig()` 返回安全默认值（TLS 1.2+，安全头部等）
- `GenerateConfigYAML()` 生成带注释的配置模板
- `defaults.go` 是高频访问文件，修改需谨慎
### Testing Requirements
- 测试覆盖完整：结构体解析、默认值、验证逻辑
- 运行测试：`go test ./internal/config/...`
- 验证测试使用 table-driven 方式
### Common Patterns
- 使用 `gopkg.in/yaml.v3` 解析 YAML
- 验证函数按配置类型分组：validateServer、validateSSL、validateSecurity
- 时间配置使用 `time.Duration`，YAML 中用秒数或带单位字符串（如 "10s"）
- 安全配置强制要求：Basic Auth 启用时必须配置 SSL
## Dependencies
### External
- `gopkg.in/yaml.v3` - YAML 解析库
<!-- MANUAL: -->

35
internal/converter/AGENTS.md
View File

@ -1,35 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
# converter
## Purpose
配置转换器模块，提供外部配置格式到 lolly YAML 配置的转换能力。
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `nginx/` | nginx 配置转换器（nginx.conf → lolly.yaml） |
## For AI Agents
### Working In This Directory
- 转换器将外部配置格式解析为 `config.Config` 结构体
- 转换过程中可能产生警告（不支持的指令），需要收集并展示给用户
- 每种外部格式有独立的子包实现
### Testing Requirements
- 运行测试：`go test ./internal/converter/...`
- 测试应覆盖各种配置场景和边界情况
### Common Patterns
- 转换器返回 `(*config.Config, []Warning, error)` 三元组
- 警告信息包含文件名、行号和描述
## Dependencies
### Internal
- `../config/` - 配置结构体定义
<!-- MANUAL: -->

70
internal/converter/nginx/AGENTS.md
View File

@ -1,70 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
# nginx
## Purpose
nginx 配置转换器，将 nginx.conf 格式转换为 lolly YAML 配置。支持 server、location、upstream、proxy_pass 等核心指令。
## Key Files
| File | Description |
|------|-------------|
| `parser.go` | nginx 配置解析器：词法分析、语法树构建 |
| `converter.go` | 配置转换器：nginx AST → lolly Config |
| `parser_test.go` | 解析器测试：各种 nginx 配置格式 |
| `converter_test.go` | 转换器测试：指令映射、警告生成 |
## For AI Agents
### Working In This Directory
- 解析器将 nginx 配置文本解析为 `NginxConfig` AST
- 转换器遍历 AST 生成 `config.Config` 结构体
- 不支持的指令会生成 `Warning` 而非错误，允许部分转换
- location 匹配类型映射：`=` → `exact`，`^~` → `prefix_priority`，`~` → `regex`，`~*` → `regex_caseless`
### Testing Requirements
- 运行测试：`go test ./internal/converter/nginx/...`
- 测试覆盖：完整配置、部分配置、错误处理
### Common Patterns
```go
// 解析 nginx 配置
parser := nginx.NewParser(content)
cfg, err := parser.Parse()
// 转换为 lolly 配置
result, err := nginx.Convert(cfg)
// result.Config - 转换后的配置
// result.Warnings - 转换警告
```
### 支持的 nginx 指令
| 指令 | 转换说明 |
|------|----------|
| `server` | 转换为 `ServerConfig` |
| `listen` | 转换为 `listen` 字段 |
| `server_name` | 转换为 `name`/`server_names` |
| `location` | 转换为 `ProxyConfig` 或 `StaticConfig` |
| `proxy_pass` | 转换为代理目标 |
| `root`/`alias` | 转换为静态文件根目录 |
| `upstream` | 转换为负载均衡目标列表 |
| `gzip` | 转换为压缩配置 |
| `ssl_certificate` | 转换为 SSL 证书配置 |
| `rewrite` | 转换为 URL 重写规则 |
| `return 301/302` | 转换为重定向规则 |
### 不支持的指令（生成警告）
- `if`、`map`、`set` - 条件逻辑不支持
- `limit_req`、`limit_conn` - 使用 `rate_limit` 配置替代
- `add_header` - 使用 `security.headers` 配置替代
- `auth_request` - 使用 `security.auth_request` 配置替代
## Dependencies
### Internal
- `../../config/` - 配置结构体定义
<!-- MANUAL: -->

72
internal/e2e/AGENTS.md
View File

@ -1,72 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
# e2e
## Purpose
端到端测试模块，验证完整功能的集成测试。使用 testcontainers 启动真实后端服务进行测试。
## Key Files
| File | Description |
|------|-------------|
| `e2e_test.go` | 测试入口和通用测试辅助函数 |
| `cache_e2e_test.go` | 代理缓存端到端测试 |
| `healthcheck_e2e_test.go` | 健康检查端到端测试 |
| `http2_e2e_test.go` | HTTP/2 端到端测试 |
| `loadbalance_e2e_test.go` | 负载均衡端到端测试 |
| `proxy_e2e_test.go` | 反向代理端到端测试 |
| `ssl_e2e_test.go` | SSL/TLS 端到端测试 |
| `static_e2e_test.go` | 静态文件服务端到端测试 |
| `websocket_e2e_test.go` | WebSocket 代理端到端测试 |
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `testutil/` | 测试工具函数（容器、配置、证书） |
| `certs/` | 测试用 TLS 证书 |
| `configs/` | 测试用配置文件 |
## For AI Agents
### Working In This Directory
- 端到端测试需要 Docker 环境运行 testcontainers
- 测试启动真实 lolly 服务器和 mock 后端
- 使用 `testutil` 包提供的辅助函数创建测试环境
- 测试名称遵循 `TestE2E_<功能>_<场景>` 格式
### Testing Requirements
- 运行测试：`go test ./internal/e2e/... -tags=e2e`
- 需要 Docker 运行
- 测试可能需要较长时间（启动容器）
### Common Patterns
```go
// 创建测试环境
env := testutil.NewTestEnv(t)
defer env.Cleanup()
// 启动 lolly 服务器
env.StartServer(config)
defer env.StopServer()
// 启动 mock 后端
backend := env.StartMockBackend()
defer backend.Close()
// 发送测试请求
resp := env.Request("GET", "/api/test", nil)
```
## Dependencies
### Internal
- `./testutil/` - 测试工具函数
- `../server/` - HTTP 服务器
- `../config/` - 配置加载
### External
- `github.com/testcontainers/testcontainers-go` - 容器化测试
<!-- MANUAL: -->

60
internal/e2e/testutil/AGENTS.md
View File

@ -1,60 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
# testutil
## Purpose
端到端测试工具包，提供测试环境搭建、容器管理、证书生成、配置辅助等功能。
## Key Files
| File | Description |
|------|-------------|
| `setup.go` | 测试环境初始化：NewTestEnv、Cleanup |
| `config.go` | 配置辅助：创建测试配置、临时文件 |
| `constants.go` | 测试常量：默认端口、超时时间 |
| `container.go` | 容器管理：启动 mock 后端、清理容器 |
| `container_test.go` | 容器管理测试 |
| `certs.go` | 证书生成：自签名证书、CA 证书 |
| `ssl.go` | SSL 辅助：TLS 配置、证书验证 |
| `websocket.go` | WebSocket 辅助：WS 客户端、消息收发 |
| `concurrent.go` | 并发测试辅助：并发请求、结果收集 |
## For AI Agents
### Working In This Directory
- `NewTestEnv(t)` 创建测试环境，返回清理函数
- 测试环境自动管理临时文件和端口分配
- 容器化测试需要 Docker 运行
- 证书生成用于 TLS 测试
### Testing Requirements
- 运行测试：`go test ./internal/e2e/testutil/...`
- 部分测试需要 Docker
### Common Patterns
```go
// 创建测试环境
env := testutil.NewTestEnv(t)
defer env.Cleanup()
// 创建临时配置文件
cfgPath := env.CreateConfig(serverConfig)
// 启动容器化后端
container := env.StartContainer(containerConfig)
defer container.Terminate()
// 生成测试证书
cert, key := env.GenerateCertificate()
```
## Dependencies
### Internal
- `../../config/` - 配置结构体
### External
- `github.com/testcontainers/testcontainers-go` - 容器管理
<!-- MANUAL: -->

40
internal/handler/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->
# handler
## Purpose
HTTP 请求处理器，包含路由管理和静态文件服务功能。
## Key Files
| File | Description |
|------|-------------|
| `router.go` | 路由器封装：基于 fasthttp/router，支持 GET/POST/PUT/DELETE/HEAD |
| `static.go` | 静态文件处理器：文件路径安全检查、索引文件支持 |
| `sendfile.go` | Sendfile 支持：X-Sendfile 头处理、高效文件传输 |
## For AI Agents
### Working In This Directory
- 使用 `fasthttp/router` 进行路由匹配，基于 radix tree 高效查找
- 路径参数语法：`{name}` 命名参数，`{name?}` 可选参数，`{filepath:*}` 捕获所有
- 静态文件处理器包含目录遍历安全检查（拒绝 ".."）
- 索引文件默认为 index.html、index.htm，可配置
### Testing Requirements
- 运行测试：`go test ./internal/handler/...`
- 测试路由匹配、路径安全检查、索引文件逻辑
### Common Patterns
- 使用 `github.com/valyala/fasthttp` 的 `RequestCtx` 处理请求
- `fasthttp.ServeFile()` 用于静态文件响应
- 路由参数通过 `ctx.UserValue("name")` 获取
## Dependencies
### External
- `github.com/fasthttp/router` - 路由器
- `github.com/valyala/fasthttp` - HTTP 框架
<!-- MANUAL: -->

50
internal/http2/AGENTS.md
View File

@ -1,50 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-09 | Updated: 2026-04-24 -->
# http2
## Purpose
HTTP/2 协议支持模块，基于 golang.org/x/net/http2 实现，提供 ALPN 协议协商、与 fasthttp handler 的集成、优雅关闭支持。
## Key Files
| File | Description |
|------|-------------|
| `server.go` | HTTP/2 服务器核心：Server 结构、NewServer、Start、GracefulStop |
| `adapter.go` | fasthttp 适配层：FastHTTPHandlerAdapter、零拷贝头部转换、流式请求体处理 |
| `server_test.go` | 服务器测试：创建、启动、关闭测试 |
| `adapter_test.go` | 适配器测试：头部转换、请求体处理测试 |
| `integration_test.go` | 集成测试：端到端 HTTP/2 请求处理 |
| `integration_tls_test.go` | TLS 集成测试：HTTPS 连接测试 |
## For AI Agents
### Working In This Directory
- HTTP/2 服务器使用标准库 http.Handler 接口
- 通过适配层转换 fasthttp.RequestHandler → http.Handler
- 需要 TLS 配置进行 ALPN 协商（h2 协议标识）
- 使用 sync.Pool 复用缓冲区实现零拷贝优化
- 预估每请求 5-10µs 适配开销
### Testing Requirements
- 运行测试：`go test ./internal/http2/...`
- 测试需要 TLS 配置（部分测试）
- 集成测试验证完整请求流程
### Common Patterns
- NewServer(cfg, handler, tlsConfig) 创建服务器
- Start() 在现有 TCP 监听器上启动
- GracefulStop() 优雅关闭等待请求完成
- FastHTTPHandlerAdapter.ServeHTTP 实现标准库接口
## Dependencies
### Internal
- `../config/` - HTTP2Config 配置结构体
- `../logging/` - 日志模块
### External
- `golang.org/x/net/http2` - HTTP/2 协议实现
- `github.com/valyala/fasthttp` - fasthttp handler 类型
<!-- MANUAL: -->

44
internal/http3/AGENTS.md
View File

@ -1,44 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# http3
## Purpose
HTTP/3 (QUIC) 协议支持模块，提供基于 quic-go 的 HTTP/3 服务器实现，与现有 fasthttp handler 集成。
## Key Files
| File | Description |
|------|-------------|
| `server.go` | HTTP/3 服务器核心实现（启动、停止、优雅关闭、统计） |
| `adapter.go` | fasthttp.RequestHandler 与 http.Handler 适配层 |
## For AI Agents
### Working In This Directory
- HTTP/3 需要 TLS 配置，必须与 `internal/ssl/` 模块配合使用
- 使用 quic-go 库实现 QUIC 协议
- 通过 Adapter 将 fasthttp handler 转换为标准库 http.Handler
- 配置结构体定义在 `internal/config/config.go` 的 `HTTP3Config`
### Testing Requirements
- 测试需要模拟 QUIC 连接
- 运行测试：`go test ./internal/http3/...`
### Common Patterns
- 使用 `sync.Pool` 复用 RequestCtx 对象
- 使用 `quic.ListenEarly` 创建 0-RTT 支持的监听器
- Alt-Svc 头用于告知客户端可使用 HTTP/3
## Dependencies
### Internal
- `rua.plus/lolly/internal/config` - HTTP3Config 配置结构
- `rua.plus/lolly/internal/logging` - 日志输出
### External
- `github.com/quic-go/quic-go` - QUIC 协议实现
- `github.com/quic-go/quic-go/http3` - HTTP/3 服务器
- `github.com/valyala/fasthttp` - HTTP 处理器接口
<!-- MANUAL: -->

43
internal/integration/AGENTS.md
View File

@ -1,43 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
# integration
## Purpose
集成测试目录，测试多个模块之间的端到端协作，验证组件间的正确集成。
## Key Files
| File | Description |
|------|-------------|
| `resolver_test.go` | DNS 解析器集成测试：基本解析、缓存功能、网络依赖测试 |
| `variable_test.go` | 变量系统集成测试：变量在日志、代理、重写中的端到端使用 |
## For AI Agents
### Working In This Directory
- 集成测试验证多模块协作，不同于单元测试
- 测试依赖真实网络环境（DNS 解析测试）
- 测试可能因网络原因跳过（Skip）
- 变量系统测试覆盖 nginx 风格格式展开
### Testing Requirements
- 运行测试：`go test ./internal/integration/...`
- 网络测试可能需要外部环境支持
- 测试验证端到端流程而非单个函数
### Common Patterns
- 使用真实配置结构体初始化测试
- 模拟 fasthttp.RequestCtx 进行请求测试
- Skip 处理网络不可用情况
## Dependencies
### Internal
- `../resolver/` - DNS 解析器模块
- `../variable/` - 变量系统模块
- `../config/` - 配置模块
- `../logging/` - 日志模块
- `../middleware/rewrite/` - URL 重写中间件
<!-- MANUAL: -->

44
internal/loadbalance/AGENTS.md
View File

@ -1,44 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# loadbalance
## Purpose
负载均衡模块，提供多种负载均衡策略和健康检查功能。
## Key Files
| File | Description |
|------|-------------|
| `balancer.go` | 负载均衡核心：Balancer 接口、Upstream、Target 管理 |
| `algorithms.go` | 负载均衡算法：RoundRobin、LeastConn、Weighted |
| `health.go` | 健康检查：HealthChecker、被动/主动检查 |
| `balancer_test.go` | 负载均衡测试 |
| `health_test.go` | 健康检查测试 |
## For AI Agents
### Working In This Directory
- `Balancer` 接口定义：Select()、AddTarget()、RemoveTarget()
- 支持 RoundRobin（轮询）、LeastConn（最少连接）、Weighted（加权）
- 健康检查支持被动（请求失败计数）和主动（定期探测）
- 不健康 Target 自动剔除，恢复后自动加入
### Testing Requirements
- 运行测试：`go test ./internal/loadbalance/...`
- 测试各算法的正确性、健康检查逻辑
### Common Patterns
- Target 权重默认为 1
- 健康检查间隔默认 10 秒
- 不健康阈值：连续 3 次失败
## Dependencies
### Internal
- `../config/` - 负载均衡配置
### External
- `github.com/valyala/fasthttp` - HTTP 客户端用于健康探测
<!-- MANUAL: -->

38
internal/logging/AGENTS.md
View File

@ -1,38 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
# logging
## Purpose
日志模块，使用 zerolog 提供零分配的 JSON 日志输出和访问日志记录。
## Key Files
| File | Description |
|------|-------------|
| `logging.go` | 日志初始化和访问日志记录：Init()、LogAccess()、parseLevel() |
## For AI Agents
### Working In This Directory
- 使用 zerolog 的链式 API 记录日志
- `Init(level, pretty)` 初始化：pretty=true 使用 ConsoleWriter（开发模式）
- `LogAccess()` 记录请求日志：method、path、status、size、duration、remote_addr
- 日志级别：debug、info、warn、error（默认 info）
### Testing Requirements
- 运行测试：`go test ./internal/logging/...`
- 测试日志级别解析和格式化输出
### Common Patterns
- 全局日志实例 `log`，通过 `Init()` 初始化
- zerolog 的零分配设计适合高并发场景
- 生产模式输出 JSON 格式，便于日志采集系统解析
## Dependencies
### External
- `github.com/rs/zerolog` - 零分配 JSON 日志库
- `github.com/valyala/fasthttp` - 获取请求信息
<!-- MANUAL: -->

67
internal/lua/AGENTS.md
View File

@ -1,67 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-24 -->
# lua
## Purpose
Lua 脚本嵌入引擎，提供类似 OpenResty 的 Lua 沙箱环境，支持请求处理、定时器、共享字典等 API。
## Key Files
| File | Description |
|------|-------------|
| `engine.go` | LuaEngine 核心：协程池、代码缓存、调度器 |
| `config.go` | 引擎配置：超时、并发限制、库开关 |
| `context.go` | LuaContext：请求上下文 Lua 绑定 |
| `coroutine.go` | LuaCoroutine：协程生命周期管理 |
| `middleware.go` | 中间件集成：access_by_lua、content_by_lua |
| `middleware_config.go` | 中间件配置解析和验证 |
| `shared_dict.go` | 共享字典：线程安全的键值存储 |
| `socket_manager.go` | cosocket 管理：TCP 连接池 |
| `timer_manager.go` | 定时器管理：ngx.timer.at 实现 |
| `cache.go` | 字节码缓存：预编译脚本缓存 |
| `register.go` | API 注册：ngx 表初始化 |
| `filter_writer.go` | 响应过滤器：body_filter_by_lua |
| `boundary_test.go` | 边界条件测试：错误处理、资源限制 |
| `scheduler_test.go` | 调度器测试：定时器、协程调度 |
| `api_*.go` | ngx API 实现：req、resp、ctx、var、log、timer、socket、location、shared_dict |
## For AI Agents
### Working In This Directory
- LuaEngine 是 HTTP Server 实例级单例，通过 `NewEngine(config)` 创建
- 协程通过 `engine.NewCoroutine(req)` 创建，使用后自动释放回池
- 定时器回调在专用调度器 LState 中执行，不能捕获闭包变量（使用 shared_dict 传递数据）
- API 分为安全（timer 可用）和不安全（仅请求协程可用）两类
### Testing Requirements
- 运行测试：`go test ./internal/lua/...`
- 基准测试：`go test -bench=. ./internal/lua/...`
- 测试覆盖：协程生命周期、API 限制、并发安全
### Common Patterns
```go
// 创建引擎
engine, err := lua.NewEngine(config)
engine.InitSchedulerLState() // 启用定时器
// 创建共享字典
engine.CreateSharedDict("cache", 1000)
// 中间件配置
mw := lua.NewMiddleware(mwConfig, engine)
handler = mw.Wrap(handler)
```
## Dependencies
### Internal
- `internal/config` - Lua 中间件配置结构
- `internal/logging` - 日志输出
- `internal/middleware` - 中间件接口
### External
- `github.com/yuin/gopher-lua` - Lua 解释器
- `github.com/valyala/fasthttp` - HTTP 请求上下文
<!-- MANUAL: -->

48
internal/middleware/AGENTS.md
View File

@ -1,48 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-07 -->
# middleware
## Purpose
中间件框架，定义统一的中间件接口和链式组合机制，包含多个具体中间件实现。
## Key Files
| File | Description |
|------|-------------|
| `middleware.go` | 中间件接口和链：Middleware 接口、Chain 结构体、Apply 方法 |
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `accesslog/` | 访问日志中间件（请求记录、响应统计） |
| `bodylimit/` | 请求体大小限制中间件（超限返回 413） |
| `compression/` | 响应压缩中间件（Gzip、Deflate） |
| `errorintercept/` | 错误拦截中间件（自定义错误页面） |
| `rewrite/` | URL 重写中间件（正则替换、路径转换） |
| `security/` | 安全中间件（访问控制、认证、限流、安全头部） |
## For AI Agents
### Working In This Directory
- `Middleware` 接口定义：`Name() string` 和 `Process(next) RequestHandler`
- `Chain` 用于组合多个中间件，按注册顺序逆序包装
- `Apply()` 从最后一个中间件开始包装，确保执行顺序正确
- 后续阶段将添加具体中间件实现（安全、压缩、重写等）
### Testing Requirements
- 运行测试：`go test ./internal/middleware/...`
- 测试链式组合和执行顺序
### Common Patterns
- 中间件使用 `fasthttp.RequestHandler` 函数签名
- 包装模式：`func(ctx) { preProcess(); next(ctx); postProcess() }`
- 空 Chain 的 `Apply()` 直接返回原始 handler
## Dependencies
### External
- `github.com/valyala/fasthttp` - HTTP 框架
<!-- MANUAL: -->

43
internal/middleware/accesslog/AGENTS.md
View File

@ -1,43 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# accesslog
## Purpose
访问日志中间件，记录每个请求的详细信息，包括方法、路径、状态码、响应时间和客户端地址。
## Key Files
| File | Description |
|------|-------------|
| `accesslog.go` | 访问日志中间件：AccessLog 结构体、Process() 方法、日志格式化 |
| `accesslog_test.go` | 访问日志测试 |
## For AI Agents
### Working In This Directory
- 记录请求信息：method、path、status、size、duration、remote_addr
- 支持自定义日志格式
- 响应时间单位为毫秒
- 日志级别为 info
### Testing Requirements
- 运行测试：`go test ./internal/middleware/accesslog/...`
- 测试日志格式化、字段提取
### Common Patterns
- 使用 zerolog 的链式 API
- duration 通过 ctx.Time() 获取
- 可配置排除路径（如健康检查）
## Dependencies
### Internal
- `../` - 中间件接口定义
- `../../logging/` - 日志实例
### External
- `github.com/rs/zerolog` - 日志库
- `github.com/valyala/fasthttp` - HTTP 框架
<!-- MANUAL: -->

40
internal/middleware/bodylimit/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
# bodylimit
## Purpose
HTTP 请求体大小限制中间件，防止客户端通过发送超大请求体导致服务器资源耗尽，支持全局配置和路径级别覆盖。
## Key Files
| File | Description |
|------|-------------|
| `bodylimit.go` | 请求体限制中间件实现，支持大小解析、路径级别配置 |
| `bodylimit_test.go` | 中间件单元测试 |
## For AI Agents
### Working In This Directory
- 使用 `io.LimitReader` 强制限制实际读取的字节数
- 支持路径级别配置覆盖全局配置（最长匹配优先）
- 大小字符串解析支持 b、kb、mb、gb 单位（不区分大小写）
- 超限返回 413 Request Entity Too Large
### Testing Requirements
- 运行测试：`go test ./internal/middleware/bodylimit/...`
- 测试覆盖：大小解析、路径匹配、超限处理
### Common Patterns
- 创建中间件：`bodylimit.New("10mb")`
- 添加路径配置：`bl.AddPathLimit("/upload", "100mb")`
- 获取路径限制：`bl.GetLimit(path)`
- 解析大小：`ParseSize("1kb")` → 1024
- 格式化大小：`FormatSize(1024)` → "1kb"
## Dependencies
### External
- `github.com/valyala/fasthttp` - HTTP 框架
<!-- MANUAL: -->

42
internal/middleware/compression/AGENTS.md
View File

@ -1,42 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# compression
## Purpose
响应压缩中间件，支持 Gzip 和 Deflate 压缩，自动根据 Accept-Encoding 头选择压缩方式。
## Key Files
| File | Description |
|------|-------------|
| `compression.go` | 压缩中间件：Compression 结构体、Process() 方法、压缩级别配置 |
| `compression_test.go` | 压缩测试 |
## For AI Agents
### Working In This Directory
- 支持 Gzip 和 Deflate 压缩
- 自动检测 Accept-Encoding 头选择压缩方式
- 压缩级别可配置（1-9，默认 6）
- 小于 1KB 的响应不压缩
### Testing Requirements
- 运行测试：`go test ./internal/middleware/compression/...`
- 测试压缩检测、响应处理、级别配置
### Common Patterns
- 使用 fasthttp 的内置压缩支持
- Content-Type 过滤：仅压缩 text/* 和 application/json
- Vary: Accept-Encoding 头自动添加
## Dependencies
### Internal
- `../` - 中间件接口定义
- `../../config/` - 压缩配置
### External
- `github.com/valyala/fasthttp` - HTTP 框架（内置压缩）
<!-- MANUAL: -->

40
internal/middleware/errorintercept/AGENTS.md
View File

@ -1,40 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
# errorintercept
## Purpose
HTTP 错误拦截中间件，用于应用自定义错误页面。拦截 4xx/5xx 响应并替换为预加载的错误页面内容。
## Key Files
| File | Description |
|------|-------------|
| `errorintercept.go` | 错误拦截中间件实现，与 ErrorPageManager 配合使用 |
## For AI Agents
### Working In This Directory
- 错误页面在启动时预加载，运行时不进行文件 I/O
- 只拦截 4xx 和 5xx 错误状态码
- 支持可选的响应状态码覆盖
- 与 `internal/handler.ErrorPageManager` 配合使用
### Testing Requirements
- 运行测试：`go test ./internal/middleware/errorintercept/...`
- 测试需模拟 ErrorPageManager 和错误响应
### Common Patterns
- 创建中间件：`errorintercept.New(errorPageManager)`
- 检查配置状态：`ei.manager.IsConfigured()`
- 获取管理器：`ei.GetManager()`
## Dependencies
### Internal
- `rua.plus/lolly/internal/handler` - ErrorPageManager 错误页面管理
### External
- `github.com/valyala/fasthttp` - HTTP 框架
<!-- MANUAL: -->

39
internal/middleware/rewrite/AGENTS.md
View File

@ -1,39 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# rewrite
## Purpose
URL 重写中间件，支持正则表达式匹配和替换，实现 URL 路径转换。
## Key Files
| File | Description |
|------|-------------|
| `rewrite.go` | 重写中间件：Rewrite 结构体、Rule 定义、正则匹配替换 |
| `rewrite_test.go` | 重写测试 |
## For AI Agents
### Working In This Directory
- 使用正则表达式匹配 URL 路径
- 支持捕获组替换（$1、$2 等）
- 重写后继续处理，不终止请求
- 可配置多条规则，按顺序匹配
### Testing Requirements
- 运行测试：`go test ./internal/middleware/rewrite/...`
- 测试正则匹配、捕获组替换、多规则处理
### Common Patterns
- 规则格式：Pattern（正则）→ Replacement（替换字符串）
- 重写后更新 ctx.Path()，不影响路由匹配
- 匹配失败时跳过该规则
## Dependencies
### Internal
- `../` - 中间件接口定义
- `../../config/` - 重写规则配置
<!-- MANUAL: -->

46
internal/middleware/security/AGENTS.md
View File

@ -1,46 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# security
## Purpose
安全中间件集合，提供访问控制、认证、限流和安全头部功能，保护服务器免受常见攻击。
## Key Files
| File | Description |
|------|-------------|
| `access.go` | 访问控制：IP 白名单/黑名单、地理位置限制、allow/deny 规则 |
| `auth.go` | 认证中间件：Basic Auth、Bearer Token、JWT 验证 |
| `ratelimit.go` | 限流中间件：请求限流、连接限流、令牌桶算法 |
| `headers.go` | 安全头部：X-Frame-Options、X-Content-Type-Options、CSP、HSTS |
| `*_test.go` | 各模块单元测试 |
## For AI Agents
### Working In This Directory
- 访问控制支持 CIDR 格式 IP 范围
- Basic Auth 使用 bcrypt 密码哈希
- 限流使用令牌桶算法，支持按 IP/全局限流
- 安全头部可配置启用/禁用
### Testing Requirements
- 运行测试：`go test ./internal/middleware/security/...`
- 测试 IP 匹配、密码验证、限流逻辑、头部设置
### Common Patterns
- 访问控制按顺序匹配：先检查黑名单，再检查白名单
- 限流阈值：请求速率（req/s）、并发连接数
- 认证失败返回 401，限流触发返回 429
## Dependencies
### Internal
- `../` - 中间件接口定义
- `../../config/` - 安全配置
### External
- `golang.org/x/crypto/bcrypt` - 密码哈希
- `github.com/valyala/fasthttp` - HTTP 框架
<!-- MANUAL: -->

42
internal/mimeutil/AGENTS.md
View File

@ -1,42 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
# mimeutil
## Purpose
MIME 类型检测工具包，提供文件内容类型检测功能，补充 Go 标准库缺失或错误的 MIME 类型映射。
## Key Files
| File | Description |
|------|-------------|
| `detect.go` | MIME 类型检测函数和扩展名映射表 |
| `detect_test.go` | 检测函数单元测试 |
## For AI Agents
### Working In This Directory
- `DetectContentType(filePath)` 根据扩展名返回 MIME 类型
- 使用包本地映射而非全局 `mime.AddExtensionType`，避免副作用
- 未知类型返回空字符串，调用方应使用默认值
### Testing Requirements
- 运行测试：`go test ./internal/mimeutil/...`
- 测试覆盖扩展名大小写处理和覆盖映射
### Common Patterns
```go
contentType := mimeutil.DetectContentType(filePath)
if contentType == "" {
contentType = "application/octet-stream"
}
```
## Dependencies
### External
- `mime` - Go 标准库 MIME 类型检测
- `path/filepath` - 扩展名提取
- `strings` - 大小写处理
<!-- MANUAL: -->

41
internal/netutil/AGENTS.md
View File

@ -1,41 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
# netutil
## Purpose
网络相关的通用工具函数包，提供客户端 IP 提取、URL 解析等功能，供 proxy、middleware、server 等模块共享使用。
## Key Files
| File | Description |
|------|-------------|
| `ip.go` | 客户端 IP 提取函数，支持 X-Forwarded-For、X-Real-IP 头 |
| `url.go` | URL 解析函数，提取主机地址和 TLS 标志 |
| `ip_test.go` | IP 提取函数单元测试 |
| `url_test.go` | URL 解析函数单元测试 |
## For AI Agents
### Working In This Directory
- IP 提取顺序：X-Forwarded-For 第一个 IP → X-Real-IP → RemoteAddr
- `ExtractClientIP` 返回字符串，适用于日志记录
- `ExtractClientIPNet` 返回 net.IP，适用于 CIDR 匹配等网络操作
- URL 解析支持 http:// 和 https:// 前缀，自动添加默认端口
### Testing Requirements
- 运行测试：`go test ./internal/netutil/...`
- 测试覆盖：各种代理头组合、URL 格式解析
### Common Patterns
- 提取客户端 IP：`ExtractClientIP(ctx)` → "192.168.1.1"
- 提取 net.IP：`ExtractClientIPNet(ctx)` → net.IP 对象
- 解析 URL：`ParseTargetURL("https://api.example.com", true)` → ("api.example.com:443", true)
- 提取主机：`ExtractHost("http://backend:8080/path")` → "backend:8080"
## Dependencies
### External
- `github.com/valyala/fasthttp` - HTTP 请求上下文
<!-- MANUAL: -->

45
internal/proxy/AGENTS.md
View File

@ -1,45 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# proxy
## Purpose
反向代理模块，提供 HTTP 和 WebSocket 代理功能，支持连接池和超时控制。
## Key Files
| File | Description |
|------|-------------|
| `proxy.go` | HTTP 反向代理核心：Proxy 结构体、Forward()、请求/响应处理 |
| `websocket.go` | WebSocket 代理：握手升级、双向数据转发、连接管理 |
| `health.go` | 健康检查集成：与 loadbalance 模块协作 |
| `proxy_test.go` | HTTP 代理测试 |
| `health_test.go` | 健康检查测试 |
## For AI Agents
### Working In This Directory
- HTTP 代理使用 fasthttp 的 HostClient 进行转发
- WebSocket 代理支持双向数据流，处理 Upgrade 请求
- 连接池配置：MaxConns、MaxIdleConnDuration
- 超时配置：ReadTimeout、WriteTimeout、IdleTimeout
### Testing Requirements
- 运行测试：`go test ./internal/proxy/...`
- 测试请求转发、WebSocket 升级、超时处理
### Common Patterns
- 代理请求时复制原始头部，添加 X-Forwarded-For
- WebSocket 使用 goroutine 双向转发
- 错误响应返回 502（Bad Gateway）或 504（Gateway Timeout）
## Dependencies
### Internal
- `../loadbalance/` - 目标选择和健康检查
- `../config/` - 代理配置
### External
- `github.com/valyala/fasthttp` - HTTP 客户端/服务器
<!-- MANUAL: -->

47
internal/resolver/AGENTS.md
View File

@ -1,47 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
# resolver
## Purpose
DNS 解析器模块，提供带缓存的 DNS 解析功能，支持动态解析后端服务域名、TTL 缓存、后台刷新。
## Key Files
| File | Description |
|------|-------------|
| `resolver.go` | DNS 解析器核心：Resolver 接口、DNSResolver 实现、LookupHost 方法 |
| `cache.go` | DNS 缓存管理：缓存条目结构、TTL 过期、缓存命中统计 |
| `stats.go` | 统计信息：ResolverStats 结构、缓存命中率、解析延迟追踪 |
| `resolver_test.go` | 单元测试：解析功能、缓存行为、错误处理测试 |
## For AI Agents
### Working In This Directory
- Resolver 接口定义：LookupHost、LookupHostWithCache、Refresh、Start、Stop
- 使用 sync.Map 实现并发安全缓存
- 后台刷新需要调用 Start() 启动
- 停止使用时应调用 Stop() 释放资源
- 用于代理模块动态解析 upstream 域名
### Testing Requirements
- 运行测试：`go test ./internal/resolver/...`
- 测试覆盖缓存逻辑和错误处理
- 集成测试在 `../integration/` 目录
### Common Patterns
- 接口设计支持多种解析器实现
- 缓存条目包含 TTL 和过期时间
- 统计信息使用 atomic 计数器
## Dependencies
### Internal
- `../config/` - ResolverConfig 配置结构体
### External
- `net` - Go 标准库 DNS 解析
- `sync` - 并发安全
- `context` - 上下文超时控制
<!-- MANUAL: -->

49
internal/server/AGENTS.md
View File

@ -1,49 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->
# server
## Purpose
HTTP 服务器核心，提供服务器创建、启动、停止和虚拟主机管理功能。
## Key Files
| File | Description |
|------|-------------|
| `server.go` | 服务器核心：Server 结构体、Start()、Stop()、GracefulStop() |
| `vhost.go` | 虚拟主机管理：VHostManager、VirtualHost、按 Host 头匹配 |
| `pool.go` | 连接池管理：Worker 池、连接复用、并发控制 |
| `upgrade.go` | 热升级：UpgradeManager、USR2 信号处理、平滑交接 |
| `status.go` | 状态监控：健康端点、统计信息、Prometheus 格式 |
## For AI Agents
### Working In This Directory
- 使用 `fasthttp.Server` 配置超时和连接限制
- `Start()` 初始化日志、创建路由、注册静态处理器、应用中间件
- 默认超时：ReadTimeout 30s、WriteTimeout 30s、IdleTimeout 120s
- `Stop()` 快速停止，`GracefulStop()` 等待请求完成
- `VHostManager` 支持多虚拟主机，按 Host 头匹配，有默认 fallback
### Testing Requirements
- 运行测试：`go test ./internal/server/...`
- 测试服务器启动/停止、虚拟主机匹配
### Common Patterns
- 服务器配置从 `config.Config` 读取
- 路由使用 `handler.NewRouter()` 创建
- 中间件通过 `middleware.NewChain().Apply()` 应用
- Host 头匹配时去除端口号
## Dependencies
### Internal
- `../config/` - 服务器配置
- `../handler/` - 路由和静态处理器
- `../logging/` - 日志初始化
- `../middleware/` - 中间件链
### External
- `github.com/valyala/fasthttp` - HTTP 服务器框架
<!-- MANUAL: -->

44
internal/ssl/AGENTS.md
View File

@ -1,44 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# ssl
## Purpose
SSL/TLS 模块，提供证书加载、OCSP Stapling 和 TLS 配置管理功能。
## Key Files
| File | Description |
|------|-------------|
| `ssl.go` | SSL/TLS 核心：证书加载、TLS 配置、SNI 支持、会话缓存 |
| `ocsp.go` | OCSP Stapling：在线证书状态查询、缓存、自动刷新 |
| `ssl_test.go` | SSL/TLS 测试 |
| `ocsp_test.go` | OCSP 测试 |
## For AI Agents
### Working In This Directory
- 支持多证书加载，按 SNI 匹配
- OCSP Stapling 提升 TLS 握手性能
- TLS 配置强制使用安全参数（TLS 1.2+、强密码套件）
- 会话缓存减少握手开销
### Testing Requirements
- 运行测试：`go test ./internal/ssl/...`
- 测试证书加载、OCSP 查询、TLS 配置
### Common Patterns
- 证书格式支持 PEM
- OCSP 响应缓存 1 小时
- 会话票据自动轮换
## Dependencies
### Internal
- `../config/` - SSL 配置
### External
- `crypto/tls` - Go 标准库 TLS 实现
- `golang.org/x/crypto/ocsp` - OCSP 协议支持
<!-- MANUAL: -->

38
internal/sslutil/AGENTS.md
View File

@ -1,38 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
# sslutil
## Purpose
SSL/TLS 工具函数包，提供证书池加载功能，用于配置 SSL 客户端验证和 CA 证书信任链。
## Key Files
| File | Description |
|------|-------------|
| `certpool.go` | 证书池加载函数，支持 PEM 格式 |
## For AI Agents
### Working In This Directory
- `LoadCertPool(certFile, _)` 加载 PEM 格式证书池（参数二为历史兼容占位）
- `LoadCACertPool(caFile)` 加载 CA 证书池的便捷函数
- 返回 `*x509.CertPool` 用于 `TLSConfig.RootCAs` 或 `ClientCAs`
### Testing Requirements
- 无独立测试文件，证书加载在 SSL 模块集成测试中覆盖
### Common Patterns
```go
// 加载 CA 证书池用于客户端验证
caPool, err := sslutil.LoadCACertPool("/path/to/ca.crt")
tlsConfig.ClientCAs = caPool
```
## Dependencies
### External
- `crypto/x509` - 证书池类型
- `os` - 文件读取
<!-- MANUAL: -->

39
internal/stream/AGENTS.md
View File

@ -1,39 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
# stream
## Purpose
TCP/UDP Stream 代理模块，支持四层代理和会话管理。
## Key Files
| File | Description |
|------|-------------|
| `stream.go` | Stream 代理核心：TCP/UDP 服务器、连接转发、会话管理 |
| `stream_test.go` | Stream 代理测试 |
## For AI Agents
### Working In This Directory
- TCP 代理：监听端口、转发连接、支持多上游
- UDP 代理：会话管理、超时控制、NAT 穿透
- 会话跟踪：源地址+端口作为键
- 超时配置：连接超时、空闲超时
### Testing Requirements
- 运行测试：`go test ./internal/stream/...`
- 测试 TCP/UDP 监听、连接转发、会话管理
### Common Patterns
- TCP 使用 net.Conn 进行双向数据拷贝
- UDP 使用会话映射表管理客户端连接
- 负载均衡策略与 HTTP 代理共享
## Dependencies
### Internal
- `../loadbalance/` - 目标选择
- `../config/` - Stream 配置
<!-- MANUAL: -->

39
internal/utils/AGENTS.md
View File

@ -1,39 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
# utils
## Purpose
HTTP 错误处理工具包，提供统一的错误响应助手函数，减少代码库中散落的 `ctx.Error` 调用模式。
## Key Files
| File | Description |
|------|-------------|
| `httperror.go` | HTTP 错误类型定义和发送助手函数 |
## For AI Agents
### Working In This Directory
- 使用预定义的 `HTTPError` 变量（如 `ErrNotFound`, `ErrForbidden`）而不是手动构造
- 通过 `SendError(ctx, err)` 发送标准错误响应
- 需要额外详情时使用 `SendErrorWithDetail(ctx, err, detail)`
### Testing Requirements
- 无独立测试文件，错误处理在其他模块测试中覆盖
### Common Patterns
```go
// 发送标准错误
utils.SendError(ctx, utils.ErrNotFound)
// 发送带详情的错误
utils.SendErrorWithDetail(ctx, utils.ErrBadGateway, "backend timeout")
```
## Dependencies
### External
- `github.com/valyala/fasthttp` - HTTP 状态码定义
<!-- MANUAL: -->

48
internal/variable/AGENTS.md
View File

@ -1,48 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
# variable
## Purpose
高性能变量系统，提供 nginx 风格的变量展开功能。用于访问日志格式模板、代理请求头设置、URL 重写规则。
## Key Files
| File | Description |
|------|-------------|
| `variable.go` | 变量系统核心：Context 结构、Expand 方法、变量存储接口 |
| `builtin.go` | 内置变量定义：$remote_addr、$request_uri、$status、$time_local 等nginx 风格变量 |
| `pool.go` | sync.Pool 复用：PoolGet、PoolPut、池统计信息 |
| `ssl.go` | SSL 相关变量：$ssl_protocol、$ssl_cipher、$ssl_client_sni 等 |
| `variable_test.go` | 单元测试：变量展开、内置变量获取、自定义变量 |
| `variable_bench_test.go` | 基准测试：展开性能、池性能 |
## For AI Agents
### Working In This Directory
- 支持两种变量格式：$var 和 ${var}（用于变量后有字符）
- 使用快速字符串扫描（非正则表达式）提升性能
- sync.Pool 复用 Context 减少 GC 压力
- 内置变量惰性求值并缓存结果
- 自定义变量通过 Set 方法设置
### Testing Requirements
- 运行测试：`go test ./internal/variable/...`
- 基准测试验证展开性能：`go test -bench=. ./internal/variable/...`
- 集成测试在 `../integration/` 目录
### Common Patterns
- Context 绑定到单个请求
- 从池获取：PoolGet(ctx)，放回：PoolPut(vc)
- 全局变量通过 SetGlobalVariables 设置
- 上游变量：$upstream_addr、$upstream_status、$upstream_response_time
## Dependencies
### Internal
- 无内部依赖，底层模块
### External
- `github.com/valyala/fasthttp` - RequestCtx 类型
<!-- MANUAL: -->

39
scripts/AGENTS.md
View File

@ -1,39 +0,0 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
# scripts
## Purpose
构建和测试辅助脚本目录，包含回归检测、CI/CD 相关的自动化脚本。
## Key Files
| File | Description |
|------|-------------|
| `check_regression.py` | 基准测试回归检测脚本，比较新旧结果检测性能退化 |
## For AI Agents
### Working In This Directory
- 回归检测脚本用于 CI/CD 流程中自动检测性能退化
- Python 脚本需要依赖环境配置
- 脚本通过 Makefile 命令调用
### Testing Requirements
- 无独立测试，作为 CI/CD 工具使用
- 通过 `make benchmark-regression` 执行回归检测
### Common Patterns
- 回归检测比较基准测试结果的 QPS 和延迟变化
- 配置阈值定义可接受的性能波动范围
- 输出报告用于 PR 审核和决策
## Dependencies
### Internal
- `../internal/benchmark/` - 基准测试结果数据源
### External
- Python 3.x - 脚本运行环境
<!-- MANUAL: -->