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

docs: 更新 AGENTS.md 项目文档

Browse Source 
- 更新各目录 AGENTS.md 的子目录信息
- 添加新增目录的 AGENTS.md 文件
- 更新 docs/prompts.md 添加新的提示词

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
xfy 2026-04-13 13:15:39 +08:00
parent 75b0d0758b
commit 4f6a7be44c
12 changed files with 373 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
AGENTS.md
View File

@ -1,4 +1,4 @@
<!-- Generated: 2026-04-02 | Updated: 2026-04-09 -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-13 -->
# lolly
@ -24,6 +24,8 @@
| `internal/` | 核心业务代码（不可被外部导入） |
| `bin/` | 编译输出目录 |
| `docs/` | 项目文档和实现计划 |
| `examples/` | Lua 脚本示例 |
| `html/` | 静态 HTML 文件（测试/示例） |
| `scripts/` | 构建/测试辅助脚本（回归检测） |
| `.github/` | CI/CD 工作流定义 |

10
docs/AGENTS.md
View File

@ -1,5 +1,5 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-13 -->
# docs
@ -16,6 +16,14 @@
| `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 |

47
docs/config/AGENTS.md Normal file
View File

@ -0,0 +1,47 @@
<!-- 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: -->

48
docs/lua/AGENTS.md Normal file
View File

@ -0,0 +1,48 @@
<!-- 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: -->

2
docs/prompts.md
View File

@ -36,3 +36,5 @@ ulw 运行 make lint，并修复
ulw 深度分析下当前项目的性能
ulw 完善性能基准测试
ulw 深度分析下代码质量

25
examples/AGENTS.md Normal file
View File

@ -0,0 +1,25 @@
<!-- 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 Normal file
View File

@ -0,0 +1,50 @@
<!-- 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: -->

6
internal/AGENTS.md
View File

@ -1,5 +1,5 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-09 -->
<!-- Generated: 2026-04-02 | Updated: 2026-04-13 -->
# internal
@ -20,13 +20,17 @@
| `integration/` | 集成测试（多模块端到端协作验证） |
| `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） |
| `logging/` | 日志系统（zerolog 初始化、访问日志） |
| `lua/` | Lua 脚本引擎（OpenResty 风格沙箱、ngx API） |
| `middleware/` | 中间件框架（接口定义、链式组合） |
| `mimeutil/` | MIME 类型检测（扩展名映射、类型推断） |
| `netutil/` | 网络工具函数（客户端 IP 提取、URL 解析） |
| `proxy/` | 反向代理模块（HTTP/WebSocket 代理） |
| `resolver/` | DNS 解析器（缓存、后台刷新、域名动态解析） |
| `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 |
| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling） |
| `sslutil/` | SSL 工具函数（证书池加载、CA 信任链） |
| `stream/` | TCP/UDP Stream 代理模块 |
| `utils/` | HTTP 错误处理（统一错误响应助手） |
| `variable/` | 变量系统（nginx 风格变量展开、日志格式模板） |
## For AI Agents

65
internal/lua/AGENTS.md Normal file
View File

@ -0,0 +1,65 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
# 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 |
| `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: -->

42
internal/mimeutil/AGENTS.md Normal file
View File

@ -0,0 +1,42 @@
<!-- 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: -->

38
internal/sslutil/AGENTS.md Normal file
View File

@ -0,0 +1,38 @@
<!-- 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/utils/AGENTS.md Normal file
View File

@ -0,0 +1,39 @@
<!-- 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: -->