diff --git a/AGENTS.md b/AGENTS.md index 04c0b8a..d95c9f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - + # lolly @@ -24,6 +24,8 @@ | `internal/` | 核心业务代码（不可被外部导入） | | `bin/` | 编译输出目录 | | `docs/` | 项目文档和实现计划 | +| `examples/` | Lua 脚本示例 | +| `html/` | 静态 HTML 文件（测试/示例） | | `scripts/` | 构建/测试辅助脚本（回归检测） | | `.github/` | CI/CD 工作流定义 | diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 0c6fc16..69997e0 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,5 +1,5 @@ - + # 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 | diff --git a/docs/config/AGENTS.md b/docs/config/AGENTS.md new file mode 100644 index 0000000..704438a --- /dev/null +++ b/docs/config/AGENTS.md @@ -0,0 +1,47 @@ + + + +# 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 配置解析实现 + + \ No newline at end of file diff --git a/docs/lua/AGENTS.md b/docs/lua/AGENTS.md new file mode 100644 index 0000000..2fa5f0e --- /dev/null +++ b/docs/lua/AGENTS.md @@ -0,0 +1,48 @@ + + + +# 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` - 脚本示例 + + \ No newline at end of file diff --git a/docs/prompts.md b/docs/prompts.md index 111f526..6d0e2a7 100644 --- a/docs/prompts.md +++ b/docs/prompts.md @@ -36,3 +36,5 @@ ulw 运行 make lint，并修复 ulw 深度分析下当前项目的性能 ulw 完善性能基准测试 + +ulw 深度分析下代码质量 \ No newline at end of file diff --git a/examples/AGENTS.md b/examples/AGENTS.md new file mode 100644 index 0000000..71cc481 --- /dev/null +++ b/examples/AGENTS.md @@ -0,0 +1,25 @@ + + + +# 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` 测试间接验证 + + \ No newline at end of file diff --git a/examples/lua-scripts/AGENTS.md b/examples/lua-scripts/AGENTS.md new file mode 100644 index 0000000..1d53aa2 --- /dev/null +++ b/examples/lua-scripts/AGENTS.md @@ -0,0 +1,50 @@ + + + +# 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 引擎实现 + + \ No newline at end of file diff --git a/internal/AGENTS.md b/internal/AGENTS.md index dac2b27..0a00f53 100644 --- a/internal/AGENTS.md +++ b/internal/AGENTS.md @@ -1,5 +1,5 @@ - + # 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 diff --git a/internal/lua/AGENTS.md b/internal/lua/AGENTS.md new file mode 100644 index 0000000..246608c --- /dev/null +++ b/internal/lua/AGENTS.md @@ -0,0 +1,65 @@ + + + +# 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 请求上下文 + + \ No newline at end of file diff --git a/internal/mimeutil/AGENTS.md b/internal/mimeutil/AGENTS.md new file mode 100644 index 0000000..8e79e4b --- /dev/null +++ b/internal/mimeutil/AGENTS.md @@ -0,0 +1,42 @@ + + + +# 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` - 大小写处理 + + \ No newline at end of file diff --git a/internal/sslutil/AGENTS.md b/internal/sslutil/AGENTS.md new file mode 100644 index 0000000..72de2e6 --- /dev/null +++ b/internal/sslutil/AGENTS.md @@ -0,0 +1,38 @@ + + + +# 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` - 文件读取 + + \ No newline at end of file diff --git a/internal/utils/AGENTS.md b/internal/utils/AGENTS.md new file mode 100644 index 0000000..0d5347e --- /dev/null +++ b/internal/utils/AGENTS.md @@ -0,0 +1,39 @@ + + + +# 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 状态码定义 + + \ No newline at end of file