From 6612819f3aeb31d2898ce6e49273642398ebeadf Mon Sep 17 00:00:00 2001 From: xfy Date: Wed, 3 Jun 2026 23:47:29 +0800 Subject: [PATCH] chore: remove stale AGENTS.md files, rewrite root AGENTS.md --- AGENTS.md | 98 ++++++++++---------- docs/AGENTS.md | 76 --------------- docs/config/AGENTS.md | 47 ---------- docs/config/advanced/AGENTS.md | 44 --------- docs/config/basic/AGENTS.md | 38 -------- docs/config/caching/AGENTS.md | 40 -------- docs/config/load-balancing/AGENTS.md | 43 --------- docs/config/lua/AGENTS.md | 45 --------- docs/config/rewriting/AGENTS.md | 39 -------- docs/config/security/AGENTS.md | 43 --------- docs/config/ssl/AGENTS.md | 40 -------- docs/lua/AGENTS.md | 48 ---------- docs/lua/api-gateway/AGENTS.md | 44 --------- docs/lua/authentication/AGENTS.md | 41 -------- docs/lua/caching/AGENTS.md | 40 -------- docs/lua/dynamic-routing/AGENTS.md | 40 -------- docs/lua/logging-monitoring/AGENTS.md | 41 -------- docs/lua/middleware/AGENTS.md | 38 -------- docs/lua/rate-limiting/AGENTS.md | 40 -------- docs/lua/websocket/AGENTS.md | 40 -------- examples/AGENTS.md | 25 ----- examples/lua-scripts/AGENTS.md | 50 ---------- internal/AGENTS.md | 67 ------------- internal/app/AGENTS.md | 43 --------- internal/benchmark/AGENTS.md | 43 --------- internal/cache/AGENTS.md | 38 -------- internal/config/AGENTS.md | 45 --------- internal/converter/AGENTS.md | 35 ------- internal/converter/nginx/AGENTS.md | 70 -------------- internal/e2e/AGENTS.md | 72 -------------- internal/e2e/testutil/AGENTS.md | 60 ------------ internal/handler/AGENTS.md | 40 -------- internal/http2/AGENTS.md | 50 ---------- internal/http3/AGENTS.md | 44 --------- internal/integration/AGENTS.md | 43 --------- internal/loadbalance/AGENTS.md | 44 --------- internal/logging/AGENTS.md | 38 -------- internal/lua/AGENTS.md | 67 ------------- internal/middleware/AGENTS.md | 48 ---------- internal/middleware/accesslog/AGENTS.md | 43 --------- internal/middleware/bodylimit/AGENTS.md | 40 -------- internal/middleware/compression/AGENTS.md | 42 --------- internal/middleware/errorintercept/AGENTS.md | 40 -------- internal/middleware/rewrite/AGENTS.md | 39 -------- internal/middleware/security/AGENTS.md | 46 --------- internal/mimeutil/AGENTS.md | 42 --------- internal/netutil/AGENTS.md | 41 -------- internal/proxy/AGENTS.md | 45 --------- internal/resolver/AGENTS.md | 47 ---------- internal/server/AGENTS.md | 49 ---------- internal/ssl/AGENTS.md | 44 --------- internal/sslutil/AGENTS.md | 38 -------- internal/stream/AGENTS.md | 39 -------- internal/utils/AGENTS.md | 39 -------- internal/variable/AGENTS.md | 48 ---------- scripts/AGENTS.md | 39 -------- 56 files changed, 51 insertions(+), 2517 deletions(-) delete mode 100644 docs/AGENTS.md delete mode 100644 docs/config/AGENTS.md delete mode 100644 docs/config/advanced/AGENTS.md delete mode 100644 docs/config/basic/AGENTS.md delete mode 100644 docs/config/caching/AGENTS.md delete mode 100644 docs/config/load-balancing/AGENTS.md delete mode 100644 docs/config/lua/AGENTS.md delete mode 100644 docs/config/rewriting/AGENTS.md delete mode 100644 docs/config/security/AGENTS.md delete mode 100644 docs/config/ssl/AGENTS.md delete mode 100644 docs/lua/AGENTS.md delete mode 100644 docs/lua/api-gateway/AGENTS.md delete mode 100644 docs/lua/authentication/AGENTS.md delete mode 100644 docs/lua/caching/AGENTS.md delete mode 100644 docs/lua/dynamic-routing/AGENTS.md delete mode 100644 docs/lua/logging-monitoring/AGENTS.md delete mode 100644 docs/lua/middleware/AGENTS.md delete mode 100644 docs/lua/rate-limiting/AGENTS.md delete mode 100644 docs/lua/websocket/AGENTS.md delete mode 100644 examples/AGENTS.md delete mode 100644 examples/lua-scripts/AGENTS.md delete mode 100644 internal/AGENTS.md delete mode 100644 internal/app/AGENTS.md delete mode 100644 internal/benchmark/AGENTS.md delete mode 100644 internal/cache/AGENTS.md delete mode 100644 internal/config/AGENTS.md delete mode 100644 internal/converter/AGENTS.md delete mode 100644 internal/converter/nginx/AGENTS.md delete mode 100644 internal/e2e/AGENTS.md delete mode 100644 internal/e2e/testutil/AGENTS.md delete mode 100644 internal/handler/AGENTS.md delete mode 100644 internal/http2/AGENTS.md delete mode 100644 internal/http3/AGENTS.md delete mode 100644 internal/integration/AGENTS.md delete mode 100644 internal/loadbalance/AGENTS.md delete mode 100644 internal/logging/AGENTS.md delete mode 100644 internal/lua/AGENTS.md delete mode 100644 internal/middleware/AGENTS.md delete mode 100644 internal/middleware/accesslog/AGENTS.md delete mode 100644 internal/middleware/bodylimit/AGENTS.md delete mode 100644 internal/middleware/compression/AGENTS.md delete mode 100644 internal/middleware/errorintercept/AGENTS.md delete mode 100644 internal/middleware/rewrite/AGENTS.md delete mode 100644 internal/middleware/security/AGENTS.md delete mode 100644 internal/mimeutil/AGENTS.md delete mode 100644 internal/netutil/AGENTS.md delete mode 100644 internal/proxy/AGENTS.md delete mode 100644 internal/resolver/AGENTS.md delete mode 100644 internal/server/AGENTS.md delete mode 100644 internal/ssl/AGENTS.md delete mode 100644 internal/sslutil/AGENTS.md delete mode 100644 internal/stream/AGENTS.md delete mode 100644 internal/utils/AGENTS.md delete mode 100644 internal/variable/AGENTS.md delete mode 100644 scripts/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index ff3487f..f524532 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,60 +1,64 @@ - - # 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 - \ No newline at end of file +- 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. diff --git a/docs/AGENTS.md b/docs/AGENTS.md deleted file mode 100644 index 69997e0..0000000 --- a/docs/AGENTS.md +++ /dev/null @@ -1,76 +0,0 @@ - - - -# 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/` - 实现代码目录，文档描述的功能在此实现 - - \ No newline at end of file diff --git a/docs/config/AGENTS.md b/docs/config/AGENTS.md deleted file mode 100644 index 704438a..0000000 --- a/docs/config/AGENTS.md +++ /dev/null @@ -1,47 +0,0 @@ - - - -# 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/config/advanced/AGENTS.md b/docs/config/advanced/AGENTS.md deleted file mode 100644 index aac78ac..0000000 --- a/docs/config/advanced/AGENTS.md +++ /dev/null @@ -1,44 +0,0 @@ - - - -# 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 代理 - - diff --git a/docs/config/basic/AGENTS.md b/docs/config/basic/AGENTS.md deleted file mode 100644 index c53016d..0000000 --- a/docs/config/basic/AGENTS.md +++ /dev/null @@ -1,38 +0,0 @@ - - - -# 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/` - 静态文件处理器 - - diff --git a/docs/config/caching/AGENTS.md b/docs/config/caching/AGENTS.md deleted file mode 100644 index 4a7b9d0..0000000 --- a/docs/config/caching/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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/` - 压缩中间件 - - diff --git a/docs/config/load-balancing/AGENTS.md b/docs/config/load-balancing/AGENTS.md deleted file mode 100644 index 186f6d0..0000000 --- a/docs/config/load-balancing/AGENTS.md +++ /dev/null @@ -1,43 +0,0 @@ - - - -# 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 解析 - - diff --git a/docs/config/lua/AGENTS.md b/docs/config/lua/AGENTS.md deleted file mode 100644 index 6180ad7..0000000 --- a/docs/config/lua/AGENTS.md +++ /dev/null @@ -1,45 +0,0 @@ - - - -# 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 解释器 - - diff --git a/docs/config/rewriting/AGENTS.md b/docs/config/rewriting/AGENTS.md deleted file mode 100644 index 29049c5..0000000 --- a/docs/config/rewriting/AGENTS.md +++ /dev/null @@ -1,39 +0,0 @@ - - - -# 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/` - 请求处理器 - - diff --git a/docs/config/security/AGENTS.md b/docs/config/security/AGENTS.md deleted file mode 100644 index 7b9ae30..0000000 --- a/docs/config/security/AGENTS.md +++ /dev/null @@ -1,43 +0,0 @@ - - - -# 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/` - 安全配置解析 - - diff --git a/docs/config/ssl/AGENTS.md b/docs/config/ssl/AGENTS.md deleted file mode 100644 index 1294f0c..0000000 --- a/docs/config/ssl/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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 工具函数 - - diff --git a/docs/lua/AGENTS.md b/docs/lua/AGENTS.md deleted file mode 100644 index 2fa5f0e..0000000 --- a/docs/lua/AGENTS.md +++ /dev/null @@ -1,48 +0,0 @@ - - - -# 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/lua/api-gateway/AGENTS.md b/docs/lua/api-gateway/AGENTS.md deleted file mode 100644 index 6e0bd79..0000000 --- a/docs/lua/api-gateway/AGENTS.md +++ /dev/null @@ -1,44 +0,0 @@ - - - -# 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 运行环境 - - diff --git a/docs/lua/authentication/AGENTS.md b/docs/lua/authentication/AGENTS.md deleted file mode 100644 index 0b1a64e..0000000 --- a/docs/lua/authentication/AGENTS.md +++ /dev/null @@ -1,41 +0,0 @@ - - - -# 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` - 认证中间件 - - diff --git a/docs/lua/caching/AGENTS.md b/docs/lua/caching/AGENTS.md deleted file mode 100644 index ff19902..0000000 --- a/docs/lua/caching/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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/` - 文件缓存实现 - - diff --git a/docs/lua/dynamic-routing/AGENTS.md b/docs/lua/dynamic-routing/AGENTS.md deleted file mode 100644 index 2243273..0000000 --- a/docs/lua/dynamic-routing/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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/` - 负载均衡实现 - - diff --git a/docs/lua/logging-monitoring/AGENTS.md b/docs/lua/logging-monitoring/AGENTS.md deleted file mode 100644 index e67e90c..0000000 --- a/docs/lua/logging-monitoring/AGENTS.md +++ /dev/null @@ -1,41 +0,0 @@ - - - -# 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/` - 日志系统实现 - - diff --git a/docs/lua/middleware/AGENTS.md b/docs/lua/middleware/AGENTS.md deleted file mode 100644 index 138e043..0000000 --- a/docs/lua/middleware/AGENTS.md +++ /dev/null @@ -1,38 +0,0 @@ - - - -# 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/` - 中间件框架实现 - - diff --git a/docs/lua/rate-limiting/AGENTS.md b/docs/lua/rate-limiting/AGENTS.md deleted file mode 100644 index ccffbc4..0000000 --- a/docs/lua/rate-limiting/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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` - 限流中间件 - - diff --git a/docs/lua/websocket/AGENTS.md b/docs/lua/websocket/AGENTS.md deleted file mode 100644 index 05475fc..0000000 --- a/docs/lua/websocket/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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 代理实现 - - diff --git a/examples/AGENTS.md b/examples/AGENTS.md deleted file mode 100644 index 71cc481..0000000 --- a/examples/AGENTS.md +++ /dev/null @@ -1,25 +0,0 @@ - - - -# 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 deleted file mode 100644 index 1d53aa2..0000000 --- a/examples/lua-scripts/AGENTS.md +++ /dev/null @@ -1,50 +0,0 @@ - - - -# 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 deleted file mode 100644 index 13f8b9e..0000000 --- a/internal/AGENTS.md +++ /dev/null @@ -1,67 +0,0 @@ - - - -# 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 解析 - - \ No newline at end of file diff --git a/internal/app/AGENTS.md b/internal/app/AGENTS.md deleted file mode 100644 index 2b5da1c..0000000 --- a/internal/app/AGENTS.md +++ /dev/null @@ -1,43 +0,0 @@ - - - -# 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 配置转换器 - - \ No newline at end of file diff --git a/internal/benchmark/AGENTS.md b/internal/benchmark/AGENTS.md deleted file mode 100644 index 0650768..0000000 --- a/internal/benchmark/AGENTS.md +++ /dev/null @@ -1,43 +0,0 @@ - - - -# 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` - 内存测试工具 - - \ No newline at end of file diff --git a/internal/cache/AGENTS.md b/internal/cache/AGENTS.md deleted file mode 100644 index c37a427..0000000 --- a/internal/cache/AGENTS.md +++ /dev/null @@ -1,38 +0,0 @@ - - - -# 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/` - 缓存配置参数 - - \ No newline at end of file diff --git a/internal/config/AGENTS.md b/internal/config/AGENTS.md deleted file mode 100644 index c0edc36..0000000 --- a/internal/config/AGENTS.md +++ /dev/null @@ -1,45 +0,0 @@ - - - -# 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 解析库 - - \ No newline at end of file diff --git a/internal/converter/AGENTS.md b/internal/converter/AGENTS.md deleted file mode 100644 index e86a040..0000000 --- a/internal/converter/AGENTS.md +++ /dev/null @@ -1,35 +0,0 @@ - - - -# 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/` - 配置结构体定义 - - diff --git a/internal/converter/nginx/AGENTS.md b/internal/converter/nginx/AGENTS.md deleted file mode 100644 index e5f12ec..0000000 --- a/internal/converter/nginx/AGENTS.md +++ /dev/null @@ -1,70 +0,0 @@ - - - -# 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/` - 配置结构体定义 - - diff --git a/internal/e2e/AGENTS.md b/internal/e2e/AGENTS.md deleted file mode 100644 index f469700..0000000 --- a/internal/e2e/AGENTS.md +++ /dev/null @@ -1,72 +0,0 @@ - - - -# 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` - 容器化测试 - - diff --git a/internal/e2e/testutil/AGENTS.md b/internal/e2e/testutil/AGENTS.md deleted file mode 100644 index de3fe0c..0000000 --- a/internal/e2e/testutil/AGENTS.md +++ /dev/null @@ -1,60 +0,0 @@ - - - -# 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` - 容器管理 - - diff --git a/internal/handler/AGENTS.md b/internal/handler/AGENTS.md deleted file mode 100644 index 3ab6ddc..0000000 --- a/internal/handler/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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 框架 - - \ No newline at end of file diff --git a/internal/http2/AGENTS.md b/internal/http2/AGENTS.md deleted file mode 100644 index db6dda8..0000000 --- a/internal/http2/AGENTS.md +++ /dev/null @@ -1,50 +0,0 @@ - - - -# 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 类型 - - \ No newline at end of file diff --git a/internal/http3/AGENTS.md b/internal/http3/AGENTS.md deleted file mode 100644 index d1633fa..0000000 --- a/internal/http3/AGENTS.md +++ /dev/null @@ -1,44 +0,0 @@ - - - -# 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 处理器接口 - - \ No newline at end of file diff --git a/internal/integration/AGENTS.md b/internal/integration/AGENTS.md deleted file mode 100644 index 892d01e..0000000 --- a/internal/integration/AGENTS.md +++ /dev/null @@ -1,43 +0,0 @@ - - - -# 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 重写中间件 - - \ No newline at end of file diff --git a/internal/loadbalance/AGENTS.md b/internal/loadbalance/AGENTS.md deleted file mode 100644 index bfb3496..0000000 --- a/internal/loadbalance/AGENTS.md +++ /dev/null @@ -1,44 +0,0 @@ - - - -# 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 客户端用于健康探测 - - \ No newline at end of file diff --git a/internal/logging/AGENTS.md b/internal/logging/AGENTS.md deleted file mode 100644 index 7517e6b..0000000 --- a/internal/logging/AGENTS.md +++ /dev/null @@ -1,38 +0,0 @@ - - - -# 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` - 获取请求信息 - - \ No newline at end of file diff --git a/internal/lua/AGENTS.md b/internal/lua/AGENTS.md deleted file mode 100644 index 37216ca..0000000 --- a/internal/lua/AGENTS.md +++ /dev/null @@ -1,67 +0,0 @@ - - - -# 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 请求上下文 - - \ No newline at end of file diff --git a/internal/middleware/AGENTS.md b/internal/middleware/AGENTS.md deleted file mode 100644 index 12460e5..0000000 --- a/internal/middleware/AGENTS.md +++ /dev/null @@ -1,48 +0,0 @@ - - - -# 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 框架 - - \ No newline at end of file diff --git a/internal/middleware/accesslog/AGENTS.md b/internal/middleware/accesslog/AGENTS.md deleted file mode 100644 index 82ce2ca..0000000 --- a/internal/middleware/accesslog/AGENTS.md +++ /dev/null @@ -1,43 +0,0 @@ - - - -# 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 框架 - - \ No newline at end of file diff --git a/internal/middleware/bodylimit/AGENTS.md b/internal/middleware/bodylimit/AGENTS.md deleted file mode 100644 index 0c275f1..0000000 --- a/internal/middleware/bodylimit/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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 框架 - - \ No newline at end of file diff --git a/internal/middleware/compression/AGENTS.md b/internal/middleware/compression/AGENTS.md deleted file mode 100644 index 4d074a5..0000000 --- a/internal/middleware/compression/AGENTS.md +++ /dev/null @@ -1,42 +0,0 @@ - - - -# 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 框架（内置压缩） - - \ No newline at end of file diff --git a/internal/middleware/errorintercept/AGENTS.md b/internal/middleware/errorintercept/AGENTS.md deleted file mode 100644 index c7c45e5..0000000 --- a/internal/middleware/errorintercept/AGENTS.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# 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 框架 - - \ No newline at end of file diff --git a/internal/middleware/rewrite/AGENTS.md b/internal/middleware/rewrite/AGENTS.md deleted file mode 100644 index 7987cbd..0000000 --- a/internal/middleware/rewrite/AGENTS.md +++ /dev/null @@ -1,39 +0,0 @@ - - - -# 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/` - 重写规则配置 - - \ No newline at end of file diff --git a/internal/middleware/security/AGENTS.md b/internal/middleware/security/AGENTS.md deleted file mode 100644 index 7c28a0c..0000000 --- a/internal/middleware/security/AGENTS.md +++ /dev/null @@ -1,46 +0,0 @@ - - - -# 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 框架 - - \ No newline at end of file diff --git a/internal/mimeutil/AGENTS.md b/internal/mimeutil/AGENTS.md deleted file mode 100644 index 8e79e4b..0000000 --- a/internal/mimeutil/AGENTS.md +++ /dev/null @@ -1,42 +0,0 @@ - - - -# 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/netutil/AGENTS.md b/internal/netutil/AGENTS.md deleted file mode 100644 index 50fb2e4..0000000 --- a/internal/netutil/AGENTS.md +++ /dev/null @@ -1,41 +0,0 @@ - - - -# 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 请求上下文 - - \ No newline at end of file diff --git a/internal/proxy/AGENTS.md b/internal/proxy/AGENTS.md deleted file mode 100644 index 19b9ae0..0000000 --- a/internal/proxy/AGENTS.md +++ /dev/null @@ -1,45 +0,0 @@ - - - -# 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 客户端/服务器 - - \ No newline at end of file diff --git a/internal/resolver/AGENTS.md b/internal/resolver/AGENTS.md deleted file mode 100644 index 5beda3b..0000000 --- a/internal/resolver/AGENTS.md +++ /dev/null @@ -1,47 +0,0 @@ - - - -# 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` - 上下文超时控制 - - \ No newline at end of file diff --git a/internal/server/AGENTS.md b/internal/server/AGENTS.md deleted file mode 100644 index 0dc054e..0000000 --- a/internal/server/AGENTS.md +++ /dev/null @@ -1,49 +0,0 @@ - - - -# 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 服务器框架 - - \ No newline at end of file diff --git a/internal/ssl/AGENTS.md b/internal/ssl/AGENTS.md deleted file mode 100644 index 91a88e5..0000000 --- a/internal/ssl/AGENTS.md +++ /dev/null @@ -1,44 +0,0 @@ - - - -# 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 协议支持 - - \ No newline at end of file diff --git a/internal/sslutil/AGENTS.md b/internal/sslutil/AGENTS.md deleted file mode 100644 index 72de2e6..0000000 --- a/internal/sslutil/AGENTS.md +++ /dev/null @@ -1,38 +0,0 @@ - - - -# 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/stream/AGENTS.md b/internal/stream/AGENTS.md deleted file mode 100644 index b18630f..0000000 --- a/internal/stream/AGENTS.md +++ /dev/null @@ -1,39 +0,0 @@ - - - -# 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 配置 - - \ No newline at end of file diff --git a/internal/utils/AGENTS.md b/internal/utils/AGENTS.md deleted file mode 100644 index 0d5347e..0000000 --- a/internal/utils/AGENTS.md +++ /dev/null @@ -1,39 +0,0 @@ - - - -# 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 diff --git a/internal/variable/AGENTS.md b/internal/variable/AGENTS.md deleted file mode 100644 index fa7a211..0000000 --- a/internal/variable/AGENTS.md +++ /dev/null @@ -1,48 +0,0 @@ - - - -# 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 类型 - - \ No newline at end of file diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md deleted file mode 100644 index ee21b26..0000000 --- a/scripts/AGENTS.md +++ /dev/null @@ -1,39 +0,0 @@ - - - -# 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 - 脚本运行环境 - - \ No newline at end of file