chore: remove stale AGENTS.md files, rewrite root AGENTS.md
This commit is contained in:
parent
29752f62bd
commit
6612819f3a
98
AGENTS.md
98
AGENTS.md
@ -1,60 +1,64 @@
|
|||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# lolly
|
# lolly
|
||||||
|
|
||||||
## Purpose
|
高性能 HTTP 服务器，类似 nginx 的纯 Go 实现。YAML 配置，单二进制，支持反向代理、负载均衡、SSL/TLS、HTTP/2、HTTP/3、Lua 脚本。
|
||||||
高性能 HTTP 服务器，类似 nginx 的纯 Go 实现。使用 YAML 配置，单二进制运行，支持静态文件服务、反向代理、负载均衡、SSL/TLS、安全控制等功能。
|
|
||||||
|
|
||||||
## Key Files
|
Module: `rua.plus/lolly` | Go 1.26+ | CGO disabled (static builds)
|
||||||
|
|
||||||
| File | Description |
|
## Commands
|
||||||
|------|-------------|
|
|
||||||
| `main.go` | 程序入口，CLI 参数解析和启动逻辑 |
|
|
||||||
| `go.mod` | Go 模块定义，依赖 fasthttp、zerolog、yaml.v3 |
|
|
||||||
| `go.sum` | 依赖版本锁定 |
|
|
||||||
| `Makefile` | 构建脚本，支持多平台编译、测试、覆盖率 |
|
|
||||||
| `lolly.yaml` | 默认配置文件示例 |
|
|
||||||
| `.gitignore` | Git 忽略规则 |
|
|
||||||
|
|
||||||
## 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 |
|
Run a single test or package:
|
||||||
|-----------|---------|
|
```
|
||||||
| `internal/` | 核心业务代码（不可被外部导入） |
|
go test -v -run TestName ./internal/config/...
|
||||||
| `bin/` | 编译输出目录 |
|
go test -v ./internal/server/...
|
||||||
| `docs/` | 项目文档和实现计划 |
|
```
|
||||||
| `examples/` | Lua 脚本示例 |
|
|
||||||
| `html/` | 静态 HTML 文件（测试/示例） |
|
|
||||||
| `scripts/` | 构建/测试辅助脚本（回归检测） |
|
|
||||||
|
|
||||||
## 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
|
## Architecture
|
||||||
- 这是 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 输出）
|
|
||||||
|
|
||||||
### Testing Requirements
|
- `main.go` → `internal/app` — CLI entry; `app.Run()` owns lifecycle
|
||||||
- 运行测试前确保依赖已下载：`go mod download`
|
- `internal/config` — YAML config structs; `config.go` is the root, split into `server_config.go`, `ssl_config.go`, `proxy_config.go`, etc.
|
||||||
- 测试覆盖率目标 >80%
|
- `internal/server` — HTTP server core: routing, middleware chain, vhosts, upgrade/reload, connection pool
|
||||||
- 使用 `make check` 运行完整检查（fmt + lint + test）
|
- `internal/proxy` — reverse proxy + load balancing
|
||||||
- 使用 `lolly --generate-config` 生成完整配置文件模板
|
- `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
|
## Key Conventions
|
||||||
- 配置结构体使用 `yaml` 标签，通过 `gopkg.in/yaml.v3` 解析
|
|
||||||
- 中间件使用 `fasthttp.RequestHandler` 函数签名
|
|
||||||
- 版本信息通过 `-ldflags` 在编译时注入
|
|
||||||
- 信号处理：SIGTERM/SIGINT 快速停止，SIGQUIT 优雅停止
|
|
||||||
|
|
||||||
## 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
|
## Gotchas
|
||||||
- `github.com/valyala/fasthttp` - 高性能 HTTP 服务器
|
|
||||||
- `github.com/fasthttp/router` - 基于 radix tree 的路由器
|
|
||||||
- `github.com/rs/zerolog` - 零分配 JSON 日志库
|
|
||||||
- `gopkg.in/yaml.v3` - YAML 解析库
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
- fasthttp uses `[]byte` strings, NOT `string`. Use `[]byte("literal")` or `fasthttp.AcquireRequest()` patterns. Don't mix net/http types.
|
||||||
|
- E2E tests need Docker running (testcontainers-go). If Docker is unavailable, run `make test-e2e-short` for testutil-only tests.
|
||||||
|
- Config file path defaults to `lolly.yaml` in CWD. Use `-c path` or `--config path`.
|
||||||
|
- `--generate-config` outputs a full config template; `-o file` writes to file.
|
||||||
|
- `--import nginx.conf` converts nginx config to lolly YAML.
|
||||||
|
|||||||
@ -1,76 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-13 -->
|
|
||||||
|
|
||||||
# docs
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
项目文档目录，包含实现计划、nginx 功能参考文档、代码规范和开发指南。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `plan.md` | 实现计划，定义 6 个开发阶段和任务列表（关键文件，高频访问） |
|
|
||||||
| `README.md` | 项目概述文档 |
|
|
||||||
| `prompts.md` | 开发提示和 AI 交互指南 |
|
|
||||||
| `comments.md` | 代码注释规范（必须遵循） |
|
|
||||||
| `13-git-commit-guide.md` | Git 提交规范指南 |
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `config/` | nginx 配置示例和功能对照表 |
|
|
||||||
| `lua/` | Lua 功能文档和 API 参考 |
|
|
||||||
| `lua-nginx-module/` | lua-nginx-module 文档 |
|
|
||||||
|
|
||||||
### nginx 功能参考文档
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `01-nginx-overview.md` | nginx 概述和架构介绍 |
|
|
||||||
| `02-nginx-installation.md` | nginx 安装指南 |
|
|
||||||
| `03-nginx-http-core.md` | HTTP 核心功能参考 |
|
|
||||||
| `04-nginx-proxy-loadbalancing.md` | 反向代理和负载均衡参考 |
|
|
||||||
| `05-nginx-ssl-https.md` | SSL/HTTPS 配置参考 |
|
|
||||||
| `06-nginx-rewrite.md` | URL 重写规则参考 |
|
|
||||||
| `07-nginx-compression-caching.md` | 压缩和缓存配置参考 |
|
|
||||||
| `08-nginx-logging-monitoring.md` | 日志和监控配置参考 |
|
|
||||||
| `09-nginx-security.md` | 安全控制参考 |
|
|
||||||
| `10-nginx-stream-tcp-udp.md` | TCP/UDP Stream 代理参考 |
|
|
||||||
| `11-nginx-mail-proxy.md` | 邮件代理参考 |
|
|
||||||
| `12-nginx-performance-tuning.md` | 性能调优参考 |
|
|
||||||
| `14-nginx-grpc-uwsgi.md` | gRPC/uWSGI/SCGI 代理参考 |
|
|
||||||
| `15-nginx-advanced-features.md` | 高级特性参考 |
|
|
||||||
| `16-nginx-internal-redirect.md` | 内部重定向参考 |
|
|
||||||
| `17-nginx-mirror-slice.md` | 镜像与切片参考 |
|
|
||||||
| `18-nginx-memcached.md` | Memcached 集成参考 |
|
|
||||||
| `19-nginx-http-modules-detail.md` | HTTP 功能模块详解 |
|
|
||||||
| `20-nginx-rate-limiting.md` | 限流与连接控制参考 |
|
|
||||||
| `21-nginx-http2-http3.md` | HTTP/2 与 HTTP/3 参考 |
|
|
||||||
| `22-nginx-third-party-modules.md` | 第三方扩展模块参考 |
|
|
||||||
| `23-nginx-special-modules.md` | 特殊功能模块参考 |
|
|
||||||
| `24-nginx-core-events.md` | 核心与事件模块参考 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- `plan.md` 是开发的核心参考，定义了各阶段的任务和验证方法
|
|
||||||
- 修改代码前应先查阅对应的 nginx 参考文档了解功能需求
|
|
||||||
- 代码注释必须遵循 `comments.md` 规范
|
|
||||||
- Git 提交格式遵循 `13-git-commit-guide.md`
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 文档无测试要求，但修改代码后需按 `plan.md` 中的验证方法测试
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 参考文档采用 nginx 配置对比方式说明功能
|
|
||||||
- plan.md 使用阶段划分（Phase 1-6）组织任务
|
|
||||||
- 每个阶段有明确的任务列表和验证方法
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../internal/` - 实现代码目录，文档描述的功能在此实现
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,47 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
|
|
||||||
|
|
||||||
# config
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
nginx 配置示例目录，展示 lolly 需要兼容的功能特性，用于功能对照和迁移参考。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 目录结构和功能对照表（关键参考文件） |
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `basic/` | 基础配置：静态服务器、反向代理、虚拟主机 |
|
|
||||||
| `ssl/` | SSL/TLS 配置：HTTPS、mTLS、OCSP、HSTS |
|
|
||||||
| `load-balancing/` | 负载均衡：轮询、加权、最少连接、IP 哈希、一致性哈希 |
|
|
||||||
| `advanced/` | 高级功能：WebSocket、gRPC、HTTP/2、HTTP/3、Stream |
|
|
||||||
| `security/` | 安全配置：限流、连接限制、访问控制、认证、安全头 |
|
|
||||||
| `caching/` | 缓存配置：代理缓存、Gzip、Brotli |
|
|
||||||
| `rewriting/` | URL 重写：rewrite 规则、重定向 |
|
|
||||||
| `lua/` | Lua 配置：基础 Lua、access_by_lua、content_by_lua、balancer_by_lua |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- `README.md` 包含 nginx 指令与 lolly 配置对照表（关键参考）
|
|
||||||
- 每个子目录包含 nginx 配置文件和对应的 lolly YAML 注释
|
|
||||||
- 修改功能时应先查阅对应目录了解 nginx 兼容需求
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 配置示例通过集成测试验证功能兼容性
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 配置对照格式：nginx 指令 ↔ lolly YAML 配置项
|
|
||||||
- 功能覆盖：负载均衡、SSL、安全、代理、缓存、重写、Lua
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../internal/config` - lolly 配置解析实现
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,44 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# advanced
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
高级功能配置示例目录，包含 WebSocket、gRPC、HTTP/2、HTTP/3、Stream 代理等高级协议配置。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `websocket.conf` | WebSocket 代理配置：Upgrade 头处理、长连接支持 |
|
|
||||||
| `grpc.conf` | gRPC 代理配置：HTTP/2 透传、超时设置 |
|
|
||||||
| `http2.conf` | HTTP/2 配置：多路复用、服务器推送、流控制 |
|
|
||||||
| `http3.conf` | HTTP/3 (QUIC) 配置：UDP 传输、0-RTT 连接 |
|
|
||||||
| `stream-tcp.conf` | TCP Stream 代理：四层负载均衡、连接复用 |
|
|
||||||
| `stream-udp.conf` | UDP Stream 代理：DNS 负载均衡、无状态转发 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- HTTP/2 需要 HTTPS，HTTP/3 需要 QUIC 支持
|
|
||||||
- Stream 代理工作在四层（TCP/UDP），不解析 HTTP
|
|
||||||
- WebSocket 需要正确处理 Upgrade 和 Connection 头
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 高级协议通过集成测试验证
|
|
||||||
- HTTP/3 测试需要 QUIC 客户端支持
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- WebSocket：`proxy_set_header Upgrade $http_upgrade`
|
|
||||||
- gRPC：`grpc_pass grpc://upstream`
|
|
||||||
- Stream：`listen 12345` 在 stream 块中
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/http2/` - HTTP/2 实现
|
|
||||||
- `../../../internal/http3/` - HTTP/3 (QUIC) 实现
|
|
||||||
- `../../../internal/stream/` - Stream 代理实现
|
|
||||||
- `../../../internal/proxy/websocket.go` - WebSocket 代理
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,38 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# basic
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
基础配置示例目录，包含静态文件服务器、反向代理、虚拟主机等核心功能的 nginx 配置示例。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `static-server.conf` | 静态文件服务器配置：sendfile、try_files、缓存策略 |
|
|
||||||
| `reverse-proxy.conf` | 反向代理配置：proxy_pass、超时设置、缓冲配置 |
|
|
||||||
| `virtual-host.conf` | 虚拟主机配置：多域名、server_name 匹配 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 每个配置文件包含 Lolly YAML 对照注释
|
|
||||||
- 修改基础功能时应参考这些配置了解 nginx 兼容需求
|
|
||||||
- 配置文件使用 nginx 指令风格，注释说明 Lolly 对应项
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 配置示例通过集成测试验证功能兼容性
|
|
||||||
- 运行测试：`go test ./internal/integration/...`
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 配置对照格式：nginx 指令 ↔ Lolly YAML 配置项
|
|
||||||
- 注释使用 `# Lolly 对应:` 标记映射关系
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/config/` - Lolly 配置解析实现
|
|
||||||
- `../../../internal/handler/` - 静态文件处理器
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# caching
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
缓存配置示例目录，包含代理缓存、Gzip 压缩、Brotli 压缩等性能优化配置。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `proxy-cache.conf` | 代理缓存：响应缓存、缓存键、过期策略 |
|
|
||||||
| `gzip.conf` | Gzip 压缩：文本压缩、压缩级别、MIME 类型 |
|
|
||||||
| `brotli.conf` | Brotli 压缩：更高压缩率、现代浏览器支持 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 代理缓存适用于后端响应不频繁变化的场景
|
|
||||||
- Gzip 是通用压缩方案，所有浏览器支持
|
|
||||||
- Brotli 压缩率更高，但需要浏览器支持
|
|
||||||
- 压缩级别建议 4-6，平衡 CPU 和压缩率
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 缓存配置通过集成测试验证
|
|
||||||
- 压缩测试验证 Content-Encoding 头
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 缓存键：`$scheme$host$request_uri`
|
|
||||||
- 缓存控制：`X-Cache-Status` 头
|
|
||||||
- 压缩条件：`gzip_types text/plain text/css application/json`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/cache/` - 文件缓存实现
|
|
||||||
- `../../../internal/middleware/compression/` - 压缩中间件
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,43 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# load-balancing
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
负载均衡配置示例目录，包含轮询、加权、最少连接、IP 哈希、一致性哈希等负载均衡策略配置。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `round-robin.conf` | 轮询负载均衡：默认策略、均匀分配 |
|
|
||||||
| `weighted.conf` | 加权轮询：按权重分配流量、服务器能力差异 |
|
|
||||||
| `least-conn.conf` | 最少连接：动态分配到连接最少的服务器 |
|
|
||||||
| `ip-hash.conf` | IP 哈希：会话保持、同一客户端固定后端 |
|
|
||||||
| `consistent-hash.conf` | 一致性哈希：分布式缓存、节点增减影响最小化 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 默认策略是轮询（round-robin）
|
|
||||||
- 加权适用于服务器性能差异场景
|
|
||||||
- 最少连接适用于长连接场景
|
|
||||||
- IP 哈希适用于需要会话保持的场景
|
|
||||||
- 一致性哈希适用于分布式缓存场景
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 负载均衡策略通过单元测试和集成测试验证
|
|
||||||
- 运行测试：`go test ./internal/loadbalance/...`
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 权重配置：`weight=N` 参数
|
|
||||||
- 健康检查：`max_fails`, `fail_timeout`
|
|
||||||
- 备用服务器：`backup` 标记
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/loadbalance/` - 负载均衡策略实现
|
|
||||||
- `../../../internal/resolver/` - 动态 DNS 解析
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,45 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# lua
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
Lua 配置示例目录，包含 Lua 脚本集成、各阶段钩子、共享字典等 Lua 功能配置。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `basic-lua.conf` | 基础 Lua 配置：脚本加载、基本语法 |
|
|
||||||
| `access-by-lua.conf` | access 阶段 Lua：访问控制、认证检查 |
|
|
||||||
| `content-by-lua.conf` | content 阶段 Lua：动态内容生成 |
|
|
||||||
| `balancer-by-lua.conf` | 负载均衡 Lua：动态上游选择 |
|
|
||||||
| `shared-dict.conf` | 共享字典：进程间数据共享、缓存 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- Lua 钩子按 nginx 处理阶段执行：rewrite → access → content
|
|
||||||
- 共享字典用于进程间数据共享，适合缓存场景
|
|
||||||
- Lua 代码在沙箱中执行，有安全限制
|
|
||||||
- 参考 OpenResty 风格的 ngx API
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- Lua 脚本通过集成测试验证
|
|
||||||
- 运行测试：`go test ./internal/lua/...`
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 访问控制：`access_by_lua_block { ... }`
|
|
||||||
- 动态内容：`content_by_lua_block { ngx.say(...) }`
|
|
||||||
- 共享字典：`lua_shared_dict cache 10m`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎实现
|
|
||||||
- `../../../docs/lua-nginx-module/` - lua-nginx-module 文档参考
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/yuin/gopher-lua` - Go Lua 解释器
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,39 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# rewriting
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
URL 重写配置示例目录，包含 rewrite 规则、重定向等 URL 处理配置。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `rewrite-rules.conf` | URL 重写规则：正则匹配、变量替换、内部重定向 |
|
|
||||||
| `redirect.conf` | 重定向配置：301/302 跳转、域名迁移 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- rewrite 使用正则表达式匹配 URL
|
|
||||||
- last 表示重写后重新匹配 location
|
|
||||||
- break 表示重写后直接处理，不再匹配
|
|
||||||
- redirect 返回 302，permanent 返回 301
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 重写规则通过单元测试验证
|
|
||||||
- 测试正则匹配和变量替换正确性
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 正则捕获：`rewrite ^/user/(\d+)$ /profile?id=$1 last`
|
|
||||||
- 域名迁移：`return 301 https://new.domain.com$request_uri`
|
|
||||||
- HTTP 转 HTTPS：`return 301 https://$host$request_uri`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/middleware/rewrite/` - 重写中间件实现
|
|
||||||
- `../../../internal/handler/` - 请求处理器
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,43 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# security
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
安全配置示例目录，包含访问控制、认证、限流、连接限制、安全头部等安全防护配置。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `access-control.conf` | 访问控制：IP 白名单/黑名单、allow/deny 规则 |
|
|
||||||
| `basic-auth.conf` | Basic 认证：用户名密码保护、htpasswd 文件 |
|
|
||||||
| `auth-request.conf` | 子请求认证：外部认证服务集成 |
|
|
||||||
| `rate-limit.conf` | 请求限流：令牌桶、漏桶、请求速率控制 |
|
|
||||||
| `conn-limit.conf` | 连接限制：并发连接数、单 IP 连接限制 |
|
|
||||||
| `security-headers.conf` | 安全头部：X-Frame-Options、CSP、HSTS |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 访问控制按顺序匹配：先检查黑名单，再检查白名单
|
|
||||||
- Basic Auth 使用 bcrypt 密码哈希
|
|
||||||
- 限流使用令牌桶算法，支持按 IP/全局限流
|
|
||||||
- 安全头部建议全部启用
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 安全配置通过单元测试验证
|
|
||||||
- 运行测试：`go test ./internal/middleware/security/...`
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 认证失败返回 401 Unauthorized
|
|
||||||
- 限流触发返回 429 Too Many Requests
|
|
||||||
- 访问拒绝返回 403 Forbidden
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/middleware/security/` - 安全中间件实现
|
|
||||||
- `../../../internal/config/` - 安全配置解析
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# ssl
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
SSL/TLS 配置示例目录，包含 HTTPS、mTLS、OCSP Stapling、HSTS 等安全传输配置示例。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `basic-ssl.conf` | 基础 HTTPS 配置：证书、TLS 协议、加密套件、HTTP/2 |
|
|
||||||
| `hsts.conf` | HSTS 配置：Strict-Transport-Security、预加载 |
|
|
||||||
| `mtls.conf` | 双向 TLS 认证：客户端证书验证、CA 配置 |
|
|
||||||
| `ocsp-stapling.conf` | OCSP Stapling：在线证书状态验证、缓存配置 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- TLS 1.0/1.1 已弃用，推荐使用 TLS 1.2/1.3
|
|
||||||
- 加密套件推荐使用 AEAD（AES-GCM、CHACHA20-POLY1305）
|
|
||||||
- Session Tickets 禁用更安全，但会影响会话恢复性能
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- SSL 配置通过集成测试验证
|
|
||||||
- 测试证书位于 `internal/ssl/testdata/`
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 证书路径：`ssl.cert`, `ssl.key`, `ssl.cert_chain`
|
|
||||||
- 协议配置：`ssl.protocols: ["TLSv1.2", "TLSv1.3"]`
|
|
||||||
- HTTP/2 启用：`ssl.http2.enabled: true`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/ssl/` - SSL 证书加载和管理
|
|
||||||
- `../../../internal/sslutil/` - SSL 工具函数
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,48 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
|
|
||||||
|
|
||||||
# lua
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
Lua 功能文档目录，包含 API 参考、使用指南和最佳实践示例。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `API.md` | Lua Engine API 参考（定时器限制、安全/不安全 API 区分） |
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `api-gateway/` | API 网关使用示例 |
|
|
||||||
| `authentication/` | 认证功能示例 |
|
|
||||||
| `caching/` | 缓存使用示例 |
|
|
||||||
| `dynamic-routing/` | 动态路由示例 |
|
|
||||||
| `logging-monitoring/` | 日志和监控示例 |
|
|
||||||
| `middleware/` | 中间件使用示例 |
|
|
||||||
| `rate-limiting/` | 限流功能示例 |
|
|
||||||
| `websocket/` | WebSocket 功能示例 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- `API.md` 是关键参考，说明定时器回调限制和 API 可用性
|
|
||||||
- 定时器回调不能捕获闭包变量，必须使用 `ngx.shared.DICT` 传递数据
|
|
||||||
- Request-scoped API（ngx.req、ngx.resp、ngx.var、ngx.ctx）在定时器回调中不可用
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- Lua 功能通过 `../../internal/lua` 测试验证
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 安全 API（timer 可用）：`ngx.shared.DICT.*`, `ngx.log`, `ngx.timer.*`
|
|
||||||
- 不安全 API（仅请求协程）：`ngx.req.*`, `ngx.resp.*`, `ngx.var.*`, `ngx.ctx.*`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../internal/lua` - Lua 引擎实现
|
|
||||||
- `../../examples/lua-scripts` - 脚本示例
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,44 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# api-gateway
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
API 网关示例项目，演示如何使用 Lua 脚本实现动态路由、认证、限流、健康检查等网关核心功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 项目说明：功能特性、快速开始、配置示例 |
|
|
||||||
| `gateway.lua` | 网关主逻辑：路由、认证、限流、错误处理 |
|
|
||||||
| `upstream.lua` | 上游服务管理：健康检查、故障剔除、动态负载均衡 |
|
|
||||||
| `nginx.conf` | NGINX 配置示例：Lua 脚本集成方式 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 基于 OpenResty / lua-nginx-module 风格
|
|
||||||
- 路由规则在 `gateway.lua` 的 `routes` 表中定义
|
|
||||||
- 上游节点在 `upstream.lua` 的 `upstreams` 表中配置
|
|
||||||
- 生产环境建议使用 Redis 替代共享字典存储
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- Lua 脚本通过集成测试验证
|
|
||||||
- 测试框架：`internal/lua/` 模块测试
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 路由匹配：路径 + 方法 + Header 组合
|
|
||||||
- 限流算法：令牌桶滑动窗口
|
|
||||||
- 健康检查：被动探测 + 故障剔除
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎实现
|
|
||||||
- `../../../internal/loadbalance/` - 负载均衡策略
|
|
||||||
|
|
||||||
### External
|
|
||||||
- OpenResty / lua-nginx-module - Lua 运行环境
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,41 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# authentication
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
认证示例目录，演示如何使用 Lua 实现 Basic Auth、JWT 验证等认证功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 功能说明和使用指南 |
|
|
||||||
| `basic_auth.lua` | Basic Auth 认证：用户名密码验证、bcrypt 哈希 |
|
|
||||||
| `jwt_validate.lua` | JWT 验证：令牌解析、签名验证、过期检查 |
|
|
||||||
| `nginx.conf` | NGINX 配置示例：认证钩子集成 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- Basic Auth 使用 bcrypt 密码哈希存储
|
|
||||||
- JWT 验证支持 HS256、RS256 算法
|
|
||||||
- 认证失败返回 401 Unauthorized
|
|
||||||
- 可与外部认证服务集成
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 认证逻辑通过单元测试验证
|
|
||||||
- 测试密码验证、令牌解析正确性
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- Basic Auth：解析 Authorization 头，验证用户名密码
|
|
||||||
- JWT：解析 Bearer 令牌，验证签名和有效期
|
|
||||||
- 错误响应：`ngx.exit(401)`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎
|
|
||||||
- `../../../internal/middleware/security/auth.go` - 认证中间件
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# caching
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
缓存示例目录，演示如何使用 Lua 实现响应缓存、缓存失效等缓存功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 功能说明和使用指南 |
|
|
||||||
| `cache_handler.lua` | 缓存处理器：缓存键生成、存储/读取、过期管理 |
|
|
||||||
| `nginx.conf` | NGINX 配置示例：共享字典缓存配置 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 使用共享字典（shared dict）存储缓存数据
|
|
||||||
- 缓存键通常基于 URL、请求头、参数组合
|
|
||||||
- 支持缓存过期时间配置
|
|
||||||
- 缓存失效策略：TTL、主动清除
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 缓存逻辑通过单元测试验证
|
|
||||||
- 测试缓存命中/未命中、过期清理
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 缓存键：`local key = ngx.md5(ngx.var.uri .. ngx.var.args)`
|
|
||||||
- 缓存读取：`local data = shared_dict:get(key)`
|
|
||||||
- 缓存写入：`shared_dict:set(key, data, ttl)`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎
|
|
||||||
- `../../../internal/cache/` - 文件缓存实现
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# dynamic-routing
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
动态路由示例目录，演示如何使用 Lua 实现基于路径、方法、Header 的动态路由。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 功能说明和使用指南 |
|
|
||||||
| `router.lua` | 路由器实现：路由规则匹配、上游选择 |
|
|
||||||
| `nginx.conf` | NGINX 配置示例：动态路由集成 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 路由规则支持正则表达式匹配
|
|
||||||
- 支持按路径、方法、Header 组合匹配
|
|
||||||
- 动态上游选择支持负载均衡
|
|
||||||
- 路由规则可热更新
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 路由逻辑通过单元测试验证
|
|
||||||
- 测试路由匹配、上游选择正确性
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 路由表：`local routes = { ["/api/*"] = "api_upstream" }`
|
|
||||||
- 匹配逻辑：遍历路由表，正则匹配请求路径
|
|
||||||
- 上游设置：`ngx.var.upstream = matched_upstream`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎
|
|
||||||
- `../../../internal/loadbalance/` - 负载均衡实现
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,41 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# logging-monitoring
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
日志和监控示例目录，演示如何使用 Lua 实现自定义日志格式、指标收集等监控功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 功能说明和使用指南 |
|
|
||||||
| `log_formatter.lua` | 日志格式化器：自定义日志格式、字段提取 |
|
|
||||||
| `metrics.lua` | 指标收集：请求计数、延迟统计、Prometheus 格式 |
|
|
||||||
| `nginx.conf` | NGINX 配置示例：日志钩子集成 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 日志格式支持 JSON、文本格式
|
|
||||||
- 指标可导出为 Prometheus 格式
|
|
||||||
- 支持请求级别的详细日志
|
|
||||||
- 监控数据可存储到共享字典
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 日志和指标逻辑通过单元测试验证
|
|
||||||
- 测试日志格式、指标计算正确性
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 日志字段：`ngx.log(ngx.INFO, json.encode(log_entry))`
|
|
||||||
- 指标计数：`metrics_dict:incr("request_count")`
|
|
||||||
- Prometheus 格式：`# TYPE http_requests_total counter`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎
|
|
||||||
- `../../../internal/logging/` - 日志系统实现
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,38 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# middleware
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
中间件示例目录，演示 Lua 中间件的概念和用法。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 中间件概念说明和使用指南 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 中间件按处理阶段执行：rewrite → access → content → log
|
|
||||||
- 中间件可链式组合
|
|
||||||
- 支持请求修改和响应拦截
|
|
||||||
- 参考 OpenResty 风格的中间件模式
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 中间件逻辑通过集成测试验证
|
|
||||||
- 测试中间件链执行顺序
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 链式调用：按注册顺序执行
|
|
||||||
- 请求修改：`ngx.req.set_header()`
|
|
||||||
- 响应拦截：`ngx.exit()` 提前返回
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎
|
|
||||||
- `../../../internal/middleware/` - 中间件框架实现
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# rate-limiting
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
限流示例目录，演示如何使用 Lua 实现请求限流、令牌桶算法等限流功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 功能说明和使用指南 |
|
|
||||||
| `access.lua` | 限流实现：令牌桶、滑动窗口、请求计数 |
|
|
||||||
| `nginx.conf` | NGINX 配置示例：限流钩子集成 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 令牌桶算法：固定速率生成令牌，请求消耗令牌
|
|
||||||
- 滑动窗口：统计时间窗口内请求数
|
|
||||||
- 支持按 IP、全局限流
|
|
||||||
- 限流触发返回 429 Too Many Requests
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 限流逻辑通过单元测试验证
|
|
||||||
- 测试令牌桶、滑动窗口算法正确性
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 令牌桶：`local tokens = min(max_tokens, tokens + rate * elapsed)`
|
|
||||||
- 限流检查：`if tokens < 1 then ngx.exit(429) end`
|
|
||||||
- 滑动窗口：使用共享字典存储请求时间戳
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎
|
|
||||||
- `../../../internal/middleware/security/ratelimit.go` - 限流中间件
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-23 | Updated: 2026-04-23 -->
|
|
||||||
|
|
||||||
# websocket
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
WebSocket 示例目录，演示如何使用 Lua 实现 WebSocket 服务器和客户端功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `README.md` | 功能说明和使用指南 |
|
|
||||||
| `ws_handler.lua` | WebSocket 处理器：握手、消息收发、连接管理 |
|
|
||||||
| `nginx.conf` | NGINX 配置示例：WebSocket 代理配置 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- WebSocket 需要正确处理 Upgrade 和 Connection 头
|
|
||||||
- 支持双向消息传递
|
|
||||||
- 需要处理连接保活（ping/pong）
|
|
||||||
- 错误处理：连接断开、协议错误
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- WebSocket 逻辑通过集成测试验证
|
|
||||||
- 测试握手、消息收发、连接关闭
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 握手验证：检查 `Upgrade: websocket` 头
|
|
||||||
- 消息循环：`while true do local data = ws:recv() end`
|
|
||||||
- 心跳：定期发送 ping 帧
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../../internal/lua/` - Lua 脚本引擎
|
|
||||||
- `../../../internal/proxy/websocket.go` - WebSocket 代理实现
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,25 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
|
|
||||||
|
|
||||||
# examples
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
示例目录，包含 Lua 脚本示例展示 lolly 的脚本嵌入能力。
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `lua-scripts/` | Lua 脚本示例（认证、日志、定时器等） |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 示例脚本用于演示功能，不参与生产运行
|
|
||||||
- 脚本遵循 OpenResty API 兼容风格
|
|
||||||
- 修改示例时参考 `docs/lua/API.md` 了解 API 限制
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 示例脚本通过 `internal/lua` 测试间接验证
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,50 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
|
|
||||||
|
|
||||||
# lua-scripts
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
Lua 脚本示例集合，展示 lolly Lua 沙箱的各种用法。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `auth.lua` | Access 阶段认证检查示例（token 验证） |
|
|
||||||
| `content.lua` | Content 阶段内容生成示例 |
|
|
||||||
| `log.lua` | Log 阶段日志记录示例 |
|
|
||||||
| `timer.lua` | 定时器使用示例（ngx.timer.at） |
|
|
||||||
| `shared_dict.lua` | 共享字典使用示例 |
|
|
||||||
| `subrequest.lua` | 子请求示例（ngx.location.capture） |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 示例脚本演示典型用法，可作为配置参考
|
|
||||||
- 脚本使用 OpenResty 兼容的 `ngx.*` API
|
|
||||||
- 定时器回调不能捕获闭包变量，需使用 `ngx.shared.DICT` 传递数据
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 示例脚本通过集成测试验证功能
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
```lua
|
|
||||||
-- Access 阶段认证
|
|
||||||
local auth_header = ngx.req.get_headers()["Authorization"]
|
|
||||||
if not auth_header then
|
|
||||||
ngx.exit(401)
|
|
||||||
end
|
|
||||||
|
|
||||||
-- 定时器（使用 shared_dict 传递数据）
|
|
||||||
ngx.shared.timer_data:set("key", ngx.var.request_id)
|
|
||||||
ngx.timer.at(5, function()
|
|
||||||
ngx.log(ngx.INFO, ngx.shared.timer_data:get("key"))
|
|
||||||
end)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../internal/lua` - Lua 引擎实现
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,67 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# internal
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
核心业务代码目录，包含服务器、配置、处理器、中间件、日志等模块。Go 的 internal 包机制确保这些代码不可被外部项目导入。
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息、nginx 配置导入） |
|
|
||||||
| `benchmark/` | 基准测试基础设施（Mock 后端、负载生成器、回归检测） |
|
|
||||||
| `cache/` | 文件缓存模块（缓存存储、过期管理、stale 回退） |
|
|
||||||
| `config/` | 配置解析、验证和默认值生成 |
|
|
||||||
| `converter/` | 配置转换器（nginx 配置导入） |
|
|
||||||
| `e2e/` | 端到端测试（完整功能验证、容器化测试） |
|
|
||||||
| `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile、ETag） |
|
|
||||||
| `http2/` | HTTP/2 协议支持（ALPN 协商、fasthttp 适配） |
|
|
||||||
| `http3/` | HTTP/3 (QUIC) 协议支持（fasthttp 适配、0-RTT） |
|
|
||||||
| `integration/` | 集成测试（多模块端到端协作验证） |
|
|
||||||
| `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） |
|
|
||||||
| `logging/` | 日志系统（zerolog 初始化、访问日志） |
|
|
||||||
| `lua/` | Lua 脚本引擎（OpenResty 风格沙箱、ngx API） |
|
|
||||||
| `matcher/` | 路径匹配器（精确、前缀、正则匹配） |
|
|
||||||
| `middleware/` | 中间件框架（接口定义、链式组合） |
|
|
||||||
| `mimeutil/` | MIME 类型检测（扩展名映射、类型推断） |
|
|
||||||
| `netutil/` | 网络工具函数（客户端 IP 提取、URL 解析） |
|
|
||||||
| `proxy/` | 反向代理模块（HTTP/WebSocket 代理、DNS 解析） |
|
|
||||||
| `resolver/` | DNS 解析器（缓存、后台刷新、域名动态解析） |
|
|
||||||
| `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 |
|
|
||||||
| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling、Session Tickets） |
|
|
||||||
| `sslutil/` | SSL 工具函数（证书池加载、CA 信任链） |
|
|
||||||
| `stream/` | TCP/UDP Stream 代理模块 |
|
|
||||||
| `testutil/` | 测试工具函数（Mock、断言助手） |
|
|
||||||
| `utils/` | HTTP 错误处理（统一错误响应助手） |
|
|
||||||
| `variable/` | 变量系统（nginx 风格变量展开、日志格式模板） |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 所有包使用 `rua.plus/lolly/internal/{package}` 导入路径
|
|
||||||
- 各子包有独立职责，遵循 Go 包设计原则
|
|
||||||
- 添加新功能时应参考 `docs/plan.md` 确定所属模块
|
|
||||||
- 测试文件与源文件同目录，使用 `_test.go` 后缀
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 每个包应有对应的测试文件
|
|
||||||
- 运行测试：`go test ./internal/...`
|
|
||||||
- 测试覆盖率目标 >80%
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 fasthttp 的 `RequestHandler` 函数签名处理请求
|
|
||||||
- 配置结构体使用 `yaml` 标签
|
|
||||||
- 中间件通过 `Chain.Apply()` 逆序包装
|
|
||||||
- 服务器通过 `fasthttp.Server` 配置超时和连接限制
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 服务器框架
|
|
||||||
- `github.com/fasthttp/router` - 路由器
|
|
||||||
- `github.com/rs/zerolog` - 日志库
|
|
||||||
- `gopkg.in/yaml.v3` - YAML 解析
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,43 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# app
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
应用程序入口包，提供启动逻辑、信号处理、版本信息显示、配置生成和 nginx 配置导入功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `app.go` | 核心逻辑：Run 入口、startServer、printVersion、generateConfig |
|
|
||||||
| `import.go` | nginx 配置导入：ImportNginxConfig、转换警告处理 |
|
|
||||||
| `app_test.go` | 单元测试：版本显示、配置生成、服务器启动测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 版本信息变量通过 `-ldflags` 在编译时注入，不要硬编码修改
|
|
||||||
- `Run()` 是程序入口函数，返回退出码
|
|
||||||
- 信号处理：SIGTERM/SIGINT 快速停止，SIGQUIT 优雅停止（等待 30s）
|
|
||||||
- `generateConfig()` 生成默认 YAML 配置，调用 `config.DefaultConfig()`
|
|
||||||
- `ImportNginxConfig()` 将 nginx 配置转换为 lolly YAML 格式
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 测试文件 `app_test.go` 包含启动逻辑测试
|
|
||||||
- 运行测试：`go test ./internal/app/...`
|
|
||||||
- 测试覆盖率目标 >80%
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 `os.Signal` 和 `signal.Notify` 处理系统信号
|
|
||||||
- 服务器启动在 goroutine 中执行，通过 channel 等待错误或信号
|
|
||||||
- `shutdownTimeout` 定义优雅停止超时时间
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../config/` - 配置加载和验证
|
|
||||||
- `../server/` - HTTP 服务器创建和启动
|
|
||||||
- `../converter/nginx/` - nginx 配置转换器
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,43 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
|
|
||||||
|
|
||||||
# benchmark
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
基准测试基础设施目录，提供负载生成、Mock 后端和测试数据生成工具，用于验证服务器性能和回归检测。
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `tools/` | 基准测试工具集（Mock 后端、负载生成器、测试数据生成） |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 基准测试使用 Go 的 testing.B 框架
|
|
||||||
- Mock 后端使用 fasthttputil.InmemoryListener 进行内存通信
|
|
||||||
- 负载生成器支持并发请求和延迟统计
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行基准测试：`go test -bench=. ./internal/benchmark/...`
|
|
||||||
- 基准测试文件使用 `_bench_test.go` 后缀
|
|
||||||
- 使用 `make benchmark` 运行完整基准测试套件
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 `fasthttputil.NewInmemoryListener` 避免网络开销
|
|
||||||
- 统计收集：QPS、P50/P90/P99 延迟、错误率
|
|
||||||
- 回归检测通过 `scripts/check_regression.py` 自动执行
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `rua.plus/lolly/internal/proxy` - 代理模块基准测试
|
|
||||||
- `rua.plus/lolly/internal/cache` - 缓存模块基准测试
|
|
||||||
- `rua.plus/lolly/internal/loadbalance` - 负载均衡基准测试
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 客户端/服务器
|
|
||||||
- `github.com/valyala/fasthttp/fasthttputil` - 内存测试工具
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
38
internal/cache/AGENTS.md
vendored
38
internal/cache/AGENTS.md
vendored
@ -1,38 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# cache
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
文件缓存模块，提供静态文件的内存缓存和过期管理功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `file_cache.go` | 文件缓存核心：FileCache 结构体、Get/Set/Delete、TTL 管理、LRU 淘汰 |
|
|
||||||
| `cache_test.go` | 缓存单元测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 缓存项包含文件内容、MIME 类型、最后修改时间
|
|
||||||
- TTL 默认 5 分钟，可配置
|
|
||||||
- LRU 淘汰策略，最大缓存大小可配置
|
|
||||||
- 支持缓存失效和手动清除
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/cache/...`
|
|
||||||
- 测试缓存存取、过期淘汰、并发安全
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 `sync.RWMutex` 保证并发安全
|
|
||||||
- 缓存键为文件路径的哈希值
|
|
||||||
- 缓存命中时直接返回内容，避免磁盘 I/O
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../config/` - 缓存配置参数
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,45 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
|
|
||||||
|
|
||||||
# config
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
配置模块，提供 YAML 配置文件的解析、验证、默认值生成和序列化功能。是整个项目的核心依赖模块（高频访问）。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `config.go` | 配置结构体定义：Config、ServerConfig、ProxyConfig、SSLConfig 等 |
|
|
||||||
| `defaults.go` | 默认配置生成：DefaultConfig()、GenerateConfigYAML()（高频访问） |
|
|
||||||
| `validate.go` | 配置验证：validateServer、validateSSL、validateSecurity 等 |
|
|
||||||
| `config_test.go` | 配置解析测试 |
|
|
||||||
| `defaults_test.go` | 默认配置测试 |
|
|
||||||
| `validate_test.go` | 验证逻辑测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 所有配置结构体使用 `yaml` 标签，支持 YAML 序列化/反序列化
|
|
||||||
- `Load()` 加载配置文件，自动调用验证
|
|
||||||
- `DefaultConfig()` 返回安全默认值（TLS 1.2+，安全头部等）
|
|
||||||
- `GenerateConfigYAML()` 生成带注释的配置模板
|
|
||||||
- `defaults.go` 是高频访问文件，修改需谨慎
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 测试覆盖完整：结构体解析、默认值、验证逻辑
|
|
||||||
- 运行测试：`go test ./internal/config/...`
|
|
||||||
- 验证测试使用 table-driven 方式
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 `gopkg.in/yaml.v3` 解析 YAML
|
|
||||||
- 验证函数按配置类型分组：validateServer、validateSSL、validateSecurity
|
|
||||||
- 时间配置使用 `time.Duration`，YAML 中用秒数或带单位字符串（如 "10s"）
|
|
||||||
- 安全配置强制要求：Basic Auth 启用时必须配置 SSL
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `gopkg.in/yaml.v3` - YAML 解析库
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,35 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# converter
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
配置转换器模块，提供外部配置格式到 lolly YAML 配置的转换能力。
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `nginx/` | nginx 配置转换器（nginx.conf → lolly.yaml） |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 转换器将外部配置格式解析为 `config.Config` 结构体
|
|
||||||
- 转换过程中可能产生警告（不支持的指令），需要收集并展示给用户
|
|
||||||
- 每种外部格式有独立的子包实现
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/converter/...`
|
|
||||||
- 测试应覆盖各种配置场景和边界情况
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 转换器返回 `(*config.Config, []Warning, error)` 三元组
|
|
||||||
- 警告信息包含文件名、行号和描述
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../config/` - 配置结构体定义
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,70 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# nginx
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
nginx 配置转换器，将 nginx.conf 格式转换为 lolly YAML 配置。支持 server、location、upstream、proxy_pass 等核心指令。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `parser.go` | nginx 配置解析器：词法分析、语法树构建 |
|
|
||||||
| `converter.go` | 配置转换器：nginx AST → lolly Config |
|
|
||||||
| `parser_test.go` | 解析器测试：各种 nginx 配置格式 |
|
|
||||||
| `converter_test.go` | 转换器测试：指令映射、警告生成 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 解析器将 nginx 配置文本解析为 `NginxConfig` AST
|
|
||||||
- 转换器遍历 AST 生成 `config.Config` 结构体
|
|
||||||
- 不支持的指令会生成 `Warning` 而非错误，允许部分转换
|
|
||||||
- location 匹配类型映射：`=` → `exact`，`^~` → `prefix_priority`，`~` → `regex`，`~*` → `regex_caseless`
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/converter/nginx/...`
|
|
||||||
- 测试覆盖：完整配置、部分配置、错误处理
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
```go
|
|
||||||
// 解析 nginx 配置
|
|
||||||
parser := nginx.NewParser(content)
|
|
||||||
cfg, err := parser.Parse()
|
|
||||||
|
|
||||||
// 转换为 lolly 配置
|
|
||||||
result, err := nginx.Convert(cfg)
|
|
||||||
// result.Config - 转换后的配置
|
|
||||||
// result.Warnings - 转换警告
|
|
||||||
```
|
|
||||||
|
|
||||||
### 支持的 nginx 指令
|
|
||||||
|
|
||||||
| 指令 | 转换说明 |
|
|
||||||
|------|----------|
|
|
||||||
| `server` | 转换为 `ServerConfig` |
|
|
||||||
| `listen` | 转换为 `listen` 字段 |
|
|
||||||
| `server_name` | 转换为 `name`/`server_names` |
|
|
||||||
| `location` | 转换为 `ProxyConfig` 或 `StaticConfig` |
|
|
||||||
| `proxy_pass` | 转换为代理目标 |
|
|
||||||
| `root`/`alias` | 转换为静态文件根目录 |
|
|
||||||
| `upstream` | 转换为负载均衡目标列表 |
|
|
||||||
| `gzip` | 转换为压缩配置 |
|
|
||||||
| `ssl_certificate` | 转换为 SSL 证书配置 |
|
|
||||||
| `rewrite` | 转换为 URL 重写规则 |
|
|
||||||
| `return 301/302` | 转换为重定向规则 |
|
|
||||||
|
|
||||||
### 不支持的指令（生成警告）
|
|
||||||
|
|
||||||
- `if`、`map`、`set` - 条件逻辑不支持
|
|
||||||
- `limit_req`、`limit_conn` - 使用 `rate_limit` 配置替代
|
|
||||||
- `add_header` - 使用 `security.headers` 配置替代
|
|
||||||
- `auth_request` - 使用 `security.auth_request` 配置替代
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../config/` - 配置结构体定义
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,72 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# e2e
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
端到端测试模块，验证完整功能的集成测试。使用 testcontainers 启动真实后端服务进行测试。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `e2e_test.go` | 测试入口和通用测试辅助函数 |
|
|
||||||
| `cache_e2e_test.go` | 代理缓存端到端测试 |
|
|
||||||
| `healthcheck_e2e_test.go` | 健康检查端到端测试 |
|
|
||||||
| `http2_e2e_test.go` | HTTP/2 端到端测试 |
|
|
||||||
| `loadbalance_e2e_test.go` | 负载均衡端到端测试 |
|
|
||||||
| `proxy_e2e_test.go` | 反向代理端到端测试 |
|
|
||||||
| `ssl_e2e_test.go` | SSL/TLS 端到端测试 |
|
|
||||||
| `static_e2e_test.go` | 静态文件服务端到端测试 |
|
|
||||||
| `websocket_e2e_test.go` | WebSocket 代理端到端测试 |
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `testutil/` | 测试工具函数（容器、配置、证书） |
|
|
||||||
| `certs/` | 测试用 TLS 证书 |
|
|
||||||
| `configs/` | 测试用配置文件 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 端到端测试需要 Docker 环境运行 testcontainers
|
|
||||||
- 测试启动真实 lolly 服务器和 mock 后端
|
|
||||||
- 使用 `testutil` 包提供的辅助函数创建测试环境
|
|
||||||
- 测试名称遵循 `TestE2E_<功能>_<场景>` 格式
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/e2e/... -tags=e2e`
|
|
||||||
- 需要 Docker 运行
|
|
||||||
- 测试可能需要较长时间（启动容器）
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
```go
|
|
||||||
// 创建测试环境
|
|
||||||
env := testutil.NewTestEnv(t)
|
|
||||||
defer env.Cleanup()
|
|
||||||
|
|
||||||
// 启动 lolly 服务器
|
|
||||||
env.StartServer(config)
|
|
||||||
defer env.StopServer()
|
|
||||||
|
|
||||||
// 启动 mock 后端
|
|
||||||
backend := env.StartMockBackend()
|
|
||||||
defer backend.Close()
|
|
||||||
|
|
||||||
// 发送测试请求
|
|
||||||
resp := env.Request("GET", "/api/test", nil)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `./testutil/` - 测试工具函数
|
|
||||||
- `../server/` - HTTP 服务器
|
|
||||||
- `../config/` - 配置加载
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/testcontainers/testcontainers-go` - 容器化测试
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,60 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-24 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# testutil
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
端到端测试工具包，提供测试环境搭建、容器管理、证书生成、配置辅助等功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `setup.go` | 测试环境初始化：NewTestEnv、Cleanup |
|
|
||||||
| `config.go` | 配置辅助：创建测试配置、临时文件 |
|
|
||||||
| `constants.go` | 测试常量：默认端口、超时时间 |
|
|
||||||
| `container.go` | 容器管理：启动 mock 后端、清理容器 |
|
|
||||||
| `container_test.go` | 容器管理测试 |
|
|
||||||
| `certs.go` | 证书生成：自签名证书、CA 证书 |
|
|
||||||
| `ssl.go` | SSL 辅助：TLS 配置、证书验证 |
|
|
||||||
| `websocket.go` | WebSocket 辅助：WS 客户端、消息收发 |
|
|
||||||
| `concurrent.go` | 并发测试辅助：并发请求、结果收集 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- `NewTestEnv(t)` 创建测试环境，返回清理函数
|
|
||||||
- 测试环境自动管理临时文件和端口分配
|
|
||||||
- 容器化测试需要 Docker 运行
|
|
||||||
- 证书生成用于 TLS 测试
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/e2e/testutil/...`
|
|
||||||
- 部分测试需要 Docker
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
```go
|
|
||||||
// 创建测试环境
|
|
||||||
env := testutil.NewTestEnv(t)
|
|
||||||
defer env.Cleanup()
|
|
||||||
|
|
||||||
// 创建临时配置文件
|
|
||||||
cfgPath := env.CreateConfig(serverConfig)
|
|
||||||
|
|
||||||
// 启动容器化后端
|
|
||||||
container := env.StartContainer(containerConfig)
|
|
||||||
defer container.Terminate()
|
|
||||||
|
|
||||||
// 生成测试证书
|
|
||||||
cert, key := env.GenerateCertificate()
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../../config/` - 配置结构体
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/testcontainers/testcontainers-go` - 容器管理
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# handler
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
HTTP 请求处理器，包含路由管理和静态文件服务功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `router.go` | 路由器封装：基于 fasthttp/router，支持 GET/POST/PUT/DELETE/HEAD |
|
|
||||||
| `static.go` | 静态文件处理器：文件路径安全检查、索引文件支持 |
|
|
||||||
| `sendfile.go` | Sendfile 支持：X-Sendfile 头处理、高效文件传输 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 使用 `fasthttp/router` 进行路由匹配，基于 radix tree 高效查找
|
|
||||||
- 路径参数语法：`{name}` 命名参数，`{name?}` 可选参数，`{filepath:*}` 捕获所有
|
|
||||||
- 静态文件处理器包含目录遍历安全检查（拒绝 ".."）
|
|
||||||
- 索引文件默认为 index.html、index.htm，可配置
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/handler/...`
|
|
||||||
- 测试路由匹配、路径安全检查、索引文件逻辑
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 `github.com/valyala/fasthttp` 的 `RequestCtx` 处理请求
|
|
||||||
- `fasthttp.ServeFile()` 用于静态文件响应
|
|
||||||
- 路由参数通过 `ctx.UserValue("name")` 获取
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/fasthttp/router` - 路由器
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 框架
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,50 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-09 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# http2
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
HTTP/2 协议支持模块，基于 golang.org/x/net/http2 实现，提供 ALPN 协议协商、与 fasthttp handler 的集成、优雅关闭支持。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `server.go` | HTTP/2 服务器核心：Server 结构、NewServer、Start、GracefulStop |
|
|
||||||
| `adapter.go` | fasthttp 适配层：FastHTTPHandlerAdapter、零拷贝头部转换、流式请求体处理 |
|
|
||||||
| `server_test.go` | 服务器测试：创建、启动、关闭测试 |
|
|
||||||
| `adapter_test.go` | 适配器测试：头部转换、请求体处理测试 |
|
|
||||||
| `integration_test.go` | 集成测试：端到端 HTTP/2 请求处理 |
|
|
||||||
| `integration_tls_test.go` | TLS 集成测试：HTTPS 连接测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- HTTP/2 服务器使用标准库 http.Handler 接口
|
|
||||||
- 通过适配层转换 fasthttp.RequestHandler → http.Handler
|
|
||||||
- 需要 TLS 配置进行 ALPN 协商（h2 协议标识）
|
|
||||||
- 使用 sync.Pool 复用缓冲区实现零拷贝优化
|
|
||||||
- 预估每请求 5-10µs 适配开销
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/http2/...`
|
|
||||||
- 测试需要 TLS 配置（部分测试）
|
|
||||||
- 集成测试验证完整请求流程
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- NewServer(cfg, handler, tlsConfig) 创建服务器
|
|
||||||
- Start() 在现有 TCP 监听器上启动
|
|
||||||
- GracefulStop() 优雅关闭等待请求完成
|
|
||||||
- FastHTTPHandlerAdapter.ServeHTTP 实现标准库接口
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../config/` - HTTP2Config 配置结构体
|
|
||||||
- `../logging/` - 日志模块
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `golang.org/x/net/http2` - HTTP/2 协议实现
|
|
||||||
- `github.com/valyala/fasthttp` - fasthttp handler 类型
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,44 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# http3
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
HTTP/3 (QUIC) 协议支持模块，提供基于 quic-go 的 HTTP/3 服务器实现，与现有 fasthttp handler 集成。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `server.go` | HTTP/3 服务器核心实现（启动、停止、优雅关闭、统计） |
|
|
||||||
| `adapter.go` | fasthttp.RequestHandler 与 http.Handler 适配层 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- HTTP/3 需要 TLS 配置，必须与 `internal/ssl/` 模块配合使用
|
|
||||||
- 使用 quic-go 库实现 QUIC 协议
|
|
||||||
- 通过 Adapter 将 fasthttp handler 转换为标准库 http.Handler
|
|
||||||
- 配置结构体定义在 `internal/config/config.go` 的 `HTTP3Config`
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 测试需要模拟 QUIC 连接
|
|
||||||
- 运行测试：`go test ./internal/http3/...`
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 `sync.Pool` 复用 RequestCtx 对象
|
|
||||||
- 使用 `quic.ListenEarly` 创建 0-RTT 支持的监听器
|
|
||||||
- Alt-Svc 头用于告知客户端可使用 HTTP/3
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `rua.plus/lolly/internal/config` - HTTP3Config 配置结构
|
|
||||||
- `rua.plus/lolly/internal/logging` - 日志输出
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/quic-go/quic-go` - QUIC 协议实现
|
|
||||||
- `github.com/quic-go/quic-go/http3` - HTTP/3 服务器
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 处理器接口
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,43 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
|
|
||||||
|
|
||||||
# integration
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
集成测试目录，测试多个模块之间的端到端协作，验证组件间的正确集成。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `resolver_test.go` | DNS 解析器集成测试：基本解析、缓存功能、网络依赖测试 |
|
|
||||||
| `variable_test.go` | 变量系统集成测试：变量在日志、代理、重写中的端到端使用 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 集成测试验证多模块协作，不同于单元测试
|
|
||||||
- 测试依赖真实网络环境（DNS 解析测试）
|
|
||||||
- 测试可能因网络原因跳过（Skip）
|
|
||||||
- 变量系统测试覆盖 nginx 风格格式展开
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/integration/...`
|
|
||||||
- 网络测试可能需要外部环境支持
|
|
||||||
- 测试验证端到端流程而非单个函数
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用真实配置结构体初始化测试
|
|
||||||
- 模拟 fasthttp.RequestCtx 进行请求测试
|
|
||||||
- Skip 处理网络不可用情况
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../resolver/` - DNS 解析器模块
|
|
||||||
- `../variable/` - 变量系统模块
|
|
||||||
- `../config/` - 配置模块
|
|
||||||
- `../logging/` - 日志模块
|
|
||||||
- `../middleware/rewrite/` - URL 重写中间件
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,44 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# loadbalance
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
负载均衡模块，提供多种负载均衡策略和健康检查功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `balancer.go` | 负载均衡核心：Balancer 接口、Upstream、Target 管理 |
|
|
||||||
| `algorithms.go` | 负载均衡算法：RoundRobin、LeastConn、Weighted |
|
|
||||||
| `health.go` | 健康检查：HealthChecker、被动/主动检查 |
|
|
||||||
| `balancer_test.go` | 负载均衡测试 |
|
|
||||||
| `health_test.go` | 健康检查测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- `Balancer` 接口定义：Select()、AddTarget()、RemoveTarget()
|
|
||||||
- 支持 RoundRobin（轮询）、LeastConn（最少连接）、Weighted（加权）
|
|
||||||
- 健康检查支持被动（请求失败计数）和主动（定期探测）
|
|
||||||
- 不健康 Target 自动剔除，恢复后自动加入
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/loadbalance/...`
|
|
||||||
- 测试各算法的正确性、健康检查逻辑
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- Target 权重默认为 1
|
|
||||||
- 健康检查间隔默认 10 秒
|
|
||||||
- 不健康阈值：连续 3 次失败
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../config/` - 负载均衡配置
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 客户端用于健康探测
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,38 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
|
|
||||||
|
|
||||||
# logging
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
日志模块，使用 zerolog 提供零分配的 JSON 日志输出和访问日志记录。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `logging.go` | 日志初始化和访问日志记录：Init()、LogAccess()、parseLevel() |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 使用 zerolog 的链式 API 记录日志
|
|
||||||
- `Init(level, pretty)` 初始化：pretty=true 使用 ConsoleWriter（开发模式）
|
|
||||||
- `LogAccess()` 记录请求日志：method、path、status、size、duration、remote_addr
|
|
||||||
- 日志级别：debug、info、warn、error（默认 info）
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/logging/...`
|
|
||||||
- 测试日志级别解析和格式化输出
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 全局日志实例 `log`，通过 `Init()` 初始化
|
|
||||||
- zerolog 的零分配设计适合高并发场景
|
|
||||||
- 生产模式输出 JSON 格式，便于日志采集系统解析
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/rs/zerolog` - 零分配 JSON 日志库
|
|
||||||
- `github.com/valyala/fasthttp` - 获取请求信息
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,67 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-13 | Updated: 2026-04-24 -->
|
|
||||||
|
|
||||||
# lua
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
Lua 脚本嵌入引擎，提供类似 OpenResty 的 Lua 沙箱环境，支持请求处理、定时器、共享字典等 API。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `engine.go` | LuaEngine 核心：协程池、代码缓存、调度器 |
|
|
||||||
| `config.go` | 引擎配置：超时、并发限制、库开关 |
|
|
||||||
| `context.go` | LuaContext：请求上下文 Lua 绑定 |
|
|
||||||
| `coroutine.go` | LuaCoroutine：协程生命周期管理 |
|
|
||||||
| `middleware.go` | 中间件集成：access_by_lua、content_by_lua |
|
|
||||||
| `middleware_config.go` | 中间件配置解析和验证 |
|
|
||||||
| `shared_dict.go` | 共享字典：线程安全的键值存储 |
|
|
||||||
| `socket_manager.go` | cosocket 管理：TCP 连接池 |
|
|
||||||
| `timer_manager.go` | 定时器管理：ngx.timer.at 实现 |
|
|
||||||
| `cache.go` | 字节码缓存：预编译脚本缓存 |
|
|
||||||
| `register.go` | API 注册：ngx 表初始化 |
|
|
||||||
| `filter_writer.go` | 响应过滤器：body_filter_by_lua |
|
|
||||||
| `boundary_test.go` | 边界条件测试：错误处理、资源限制 |
|
|
||||||
| `scheduler_test.go` | 调度器测试：定时器、协程调度 |
|
|
||||||
| `api_*.go` | ngx API 实现：req、resp、ctx、var、log、timer、socket、location、shared_dict |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- LuaEngine 是 HTTP Server 实例级单例，通过 `NewEngine(config)` 创建
|
|
||||||
- 协程通过 `engine.NewCoroutine(req)` 创建，使用后自动释放回池
|
|
||||||
- 定时器回调在专用调度器 LState 中执行，不能捕获闭包变量（使用 shared_dict 传递数据）
|
|
||||||
- API 分为安全（timer 可用）和不安全（仅请求协程可用）两类
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/lua/...`
|
|
||||||
- 基准测试：`go test -bench=. ./internal/lua/...`
|
|
||||||
- 测试覆盖：协程生命周期、API 限制、并发安全
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
```go
|
|
||||||
// 创建引擎
|
|
||||||
engine, err := lua.NewEngine(config)
|
|
||||||
engine.InitSchedulerLState() // 启用定时器
|
|
||||||
|
|
||||||
// 创建共享字典
|
|
||||||
engine.CreateSharedDict("cache", 1000)
|
|
||||||
|
|
||||||
// 中间件配置
|
|
||||||
mw := lua.NewMiddleware(mwConfig, engine)
|
|
||||||
handler = mw.Wrap(handler)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `internal/config` - Lua 中间件配置结构
|
|
||||||
- `internal/logging` - 日志输出
|
|
||||||
- `internal/middleware` - 中间件接口
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/yuin/gopher-lua` - Lua 解释器
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 请求上下文
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,48 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-07 -->
|
|
||||||
|
|
||||||
# middleware
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
中间件框架，定义统一的中间件接口和链式组合机制，包含多个具体中间件实现。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `middleware.go` | 中间件接口和链：Middleware 接口、Chain 结构体、Apply 方法 |
|
|
||||||
|
|
||||||
## Subdirectories
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `accesslog/` | 访问日志中间件（请求记录、响应统计） |
|
|
||||||
| `bodylimit/` | 请求体大小限制中间件（超限返回 413） |
|
|
||||||
| `compression/` | 响应压缩中间件（Gzip、Deflate） |
|
|
||||||
| `errorintercept/` | 错误拦截中间件（自定义错误页面） |
|
|
||||||
| `rewrite/` | URL 重写中间件（正则替换、路径转换） |
|
|
||||||
| `security/` | 安全中间件（访问控制、认证、限流、安全头部） |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- `Middleware` 接口定义：`Name() string` 和 `Process(next) RequestHandler`
|
|
||||||
- `Chain` 用于组合多个中间件，按注册顺序逆序包装
|
|
||||||
- `Apply()` 从最后一个中间件开始包装，确保执行顺序正确
|
|
||||||
- 后续阶段将添加具体中间件实现（安全、压缩、重写等）
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/middleware/...`
|
|
||||||
- 测试链式组合和执行顺序
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 中间件使用 `fasthttp.RequestHandler` 函数签名
|
|
||||||
- 包装模式：`func(ctx) { preProcess(); next(ctx); postProcess() }`
|
|
||||||
- 空 Chain 的 `Apply()` 直接返回原始 handler
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 框架
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,43 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# accesslog
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
访问日志中间件，记录每个请求的详细信息，包括方法、路径、状态码、响应时间和客户端地址。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `accesslog.go` | 访问日志中间件：AccessLog 结构体、Process() 方法、日志格式化 |
|
|
||||||
| `accesslog_test.go` | 访问日志测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 记录请求信息：method、path、status、size、duration、remote_addr
|
|
||||||
- 支持自定义日志格式
|
|
||||||
- 响应时间单位为毫秒
|
|
||||||
- 日志级别为 info
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/middleware/accesslog/...`
|
|
||||||
- 测试日志格式化、字段提取
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 zerolog 的链式 API
|
|
||||||
- duration 通过 ctx.Time() 获取
|
|
||||||
- 可配置排除路径（如健康检查）
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../` - 中间件接口定义
|
|
||||||
- `../../logging/` - 日志实例
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/rs/zerolog` - 日志库
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 框架
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
|
|
||||||
|
|
||||||
# bodylimit
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
HTTP 请求体大小限制中间件，防止客户端通过发送超大请求体导致服务器资源耗尽，支持全局配置和路径级别覆盖。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `bodylimit.go` | 请求体限制中间件实现，支持大小解析、路径级别配置 |
|
|
||||||
| `bodylimit_test.go` | 中间件单元测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 使用 `io.LimitReader` 强制限制实际读取的字节数
|
|
||||||
- 支持路径级别配置覆盖全局配置（最长匹配优先）
|
|
||||||
- 大小字符串解析支持 b、kb、mb、gb 单位（不区分大小写）
|
|
||||||
- 超限返回 413 Request Entity Too Large
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/middleware/bodylimit/...`
|
|
||||||
- 测试覆盖：大小解析、路径匹配、超限处理
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 创建中间件：`bodylimit.New("10mb")`
|
|
||||||
- 添加路径配置：`bl.AddPathLimit("/upload", "100mb")`
|
|
||||||
- 获取路径限制：`bl.GetLimit(path)`
|
|
||||||
- 解析大小：`ParseSize("1kb")` → 1024
|
|
||||||
- 格式化大小：`FormatSize(1024)` → "1kb"
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 框架
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,42 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# compression
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
响应压缩中间件，支持 Gzip 和 Deflate 压缩，自动根据 Accept-Encoding 头选择压缩方式。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `compression.go` | 压缩中间件：Compression 结构体、Process() 方法、压缩级别配置 |
|
|
||||||
| `compression_test.go` | 压缩测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 支持 Gzip 和 Deflate 压缩
|
|
||||||
- 自动检测 Accept-Encoding 头选择压缩方式
|
|
||||||
- 压缩级别可配置（1-9，默认 6）
|
|
||||||
- 小于 1KB 的响应不压缩
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/middleware/compression/...`
|
|
||||||
- 测试压缩检测、响应处理、级别配置
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 使用 fasthttp 的内置压缩支持
|
|
||||||
- Content-Type 过滤：仅压缩 text/* 和 application/json
|
|
||||||
- Vary: Accept-Encoding 头自动添加
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../` - 中间件接口定义
|
|
||||||
- `../../config/` - 压缩配置
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 框架（内置压缩）
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
|
|
||||||
|
|
||||||
# errorintercept
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
HTTP 错误拦截中间件，用于应用自定义错误页面。拦截 4xx/5xx 响应并替换为预加载的错误页面内容。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `errorintercept.go` | 错误拦截中间件实现，与 ErrorPageManager 配合使用 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 错误页面在启动时预加载，运行时不进行文件 I/O
|
|
||||||
- 只拦截 4xx 和 5xx 错误状态码
|
|
||||||
- 支持可选的响应状态码覆盖
|
|
||||||
- 与 `internal/handler.ErrorPageManager` 配合使用
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/middleware/errorintercept/...`
|
|
||||||
- 测试需模拟 ErrorPageManager 和错误响应
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 创建中间件：`errorintercept.New(errorPageManager)`
|
|
||||||
- 检查配置状态：`ei.manager.IsConfigured()`
|
|
||||||
- 获取管理器：`ei.GetManager()`
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `rua.plus/lolly/internal/handler` - ErrorPageManager 错误页面管理
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 框架
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,39 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# rewrite
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
URL 重写中间件，支持正则表达式匹配和替换，实现 URL 路径转换。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `rewrite.go` | 重写中间件：Rewrite 结构体、Rule 定义、正则匹配替换 |
|
|
||||||
| `rewrite_test.go` | 重写测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 使用正则表达式匹配 URL 路径
|
|
||||||
- 支持捕获组替换（$1、$2 等）
|
|
||||||
- 重写后继续处理，不终止请求
|
|
||||||
- 可配置多条规则，按顺序匹配
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/middleware/rewrite/...`
|
|
||||||
- 测试正则匹配、捕获组替换、多规则处理
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 规则格式：Pattern（正则）→ Replacement（替换字符串）
|
|
||||||
- 重写后更新 ctx.Path()，不影响路由匹配
|
|
||||||
- 匹配失败时跳过该规则
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../` - 中间件接口定义
|
|
||||||
- `../../config/` - 重写规则配置
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,46 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# security
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
安全中间件集合，提供访问控制、认证、限流和安全头部功能，保护服务器免受常见攻击。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `access.go` | 访问控制：IP 白名单/黑名单、地理位置限制、allow/deny 规则 |
|
|
||||||
| `auth.go` | 认证中间件：Basic Auth、Bearer Token、JWT 验证 |
|
|
||||||
| `ratelimit.go` | 限流中间件：请求限流、连接限流、令牌桶算法 |
|
|
||||||
| `headers.go` | 安全头部：X-Frame-Options、X-Content-Type-Options、CSP、HSTS |
|
|
||||||
| `*_test.go` | 各模块单元测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 访问控制支持 CIDR 格式 IP 范围
|
|
||||||
- Basic Auth 使用 bcrypt 密码哈希
|
|
||||||
- 限流使用令牌桶算法，支持按 IP/全局限流
|
|
||||||
- 安全头部可配置启用/禁用
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/middleware/security/...`
|
|
||||||
- 测试 IP 匹配、密码验证、限流逻辑、头部设置
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 访问控制按顺序匹配：先检查黑名单，再检查白名单
|
|
||||||
- 限流阈值：请求速率（req/s）、并发连接数
|
|
||||||
- 认证失败返回 401，限流触发返回 429
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../` - 中间件接口定义
|
|
||||||
- `../../config/` - 安全配置
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `golang.org/x/crypto/bcrypt` - 密码哈希
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 框架
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,42 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
|
|
||||||
|
|
||||||
# mimeutil
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
MIME 类型检测工具包，提供文件内容类型检测功能，补充 Go 标准库缺失或错误的 MIME 类型映射。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `detect.go` | MIME 类型检测函数和扩展名映射表 |
|
|
||||||
| `detect_test.go` | 检测函数单元测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- `DetectContentType(filePath)` 根据扩展名返回 MIME 类型
|
|
||||||
- 使用包本地映射而非全局 `mime.AddExtensionType`，避免副作用
|
|
||||||
- 未知类型返回空字符串，调用方应使用默认值
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/mimeutil/...`
|
|
||||||
- 测试覆盖扩展名大小写处理和覆盖映射
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
```go
|
|
||||||
contentType := mimeutil.DetectContentType(filePath)
|
|
||||||
if contentType == "" {
|
|
||||||
contentType = "application/octet-stream"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `mime` - Go 标准库 MIME 类型检测
|
|
||||||
- `path/filepath` - 扩展名提取
|
|
||||||
- `strings` - 大小写处理
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,41 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
|
|
||||||
|
|
||||||
# netutil
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
网络相关的通用工具函数包，提供客户端 IP 提取、URL 解析等功能，供 proxy、middleware、server 等模块共享使用。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `ip.go` | 客户端 IP 提取函数，支持 X-Forwarded-For、X-Real-IP 头 |
|
|
||||||
| `url.go` | URL 解析函数，提取主机地址和 TLS 标志 |
|
|
||||||
| `ip_test.go` | IP 提取函数单元测试 |
|
|
||||||
| `url_test.go` | URL 解析函数单元测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- IP 提取顺序：X-Forwarded-For 第一个 IP → X-Real-IP → RemoteAddr
|
|
||||||
- `ExtractClientIP` 返回字符串，适用于日志记录
|
|
||||||
- `ExtractClientIPNet` 返回 net.IP，适用于 CIDR 匹配等网络操作
|
|
||||||
- URL 解析支持 http:// 和 https:// 前缀，自动添加默认端口
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/netutil/...`
|
|
||||||
- 测试覆盖：各种代理头组合、URL 格式解析
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 提取客户端 IP：`ExtractClientIP(ctx)` → "192.168.1.1"
|
|
||||||
- 提取 net.IP：`ExtractClientIPNet(ctx)` → net.IP 对象
|
|
||||||
- 解析 URL：`ParseTargetURL("https://api.example.com", true)` → ("api.example.com:443", true)
|
|
||||||
- 提取主机：`ExtractHost("http://backend:8080/path")` → "backend:8080"
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 请求上下文
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,45 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# proxy
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
反向代理模块，提供 HTTP 和 WebSocket 代理功能，支持连接池和超时控制。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `proxy.go` | HTTP 反向代理核心：Proxy 结构体、Forward()、请求/响应处理 |
|
|
||||||
| `websocket.go` | WebSocket 代理：握手升级、双向数据转发、连接管理 |
|
|
||||||
| `health.go` | 健康检查集成：与 loadbalance 模块协作 |
|
|
||||||
| `proxy_test.go` | HTTP 代理测试 |
|
|
||||||
| `health_test.go` | 健康检查测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- HTTP 代理使用 fasthttp 的 HostClient 进行转发
|
|
||||||
- WebSocket 代理支持双向数据流，处理 Upgrade 请求
|
|
||||||
- 连接池配置：MaxConns、MaxIdleConnDuration
|
|
||||||
- 超时配置：ReadTimeout、WriteTimeout、IdleTimeout
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/proxy/...`
|
|
||||||
- 测试请求转发、WebSocket 升级、超时处理
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 代理请求时复制原始头部，添加 X-Forwarded-For
|
|
||||||
- WebSocket 使用 goroutine 双向转发
|
|
||||||
- 错误响应返回 502（Bad Gateway）或 504（Gateway Timeout）
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../loadbalance/` - 目标选择和健康检查
|
|
||||||
- `../config/` - 代理配置
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 客户端/服务器
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,47 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
|
|
||||||
|
|
||||||
# resolver
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
DNS 解析器模块，提供带缓存的 DNS 解析功能，支持动态解析后端服务域名、TTL 缓存、后台刷新。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `resolver.go` | DNS 解析器核心：Resolver 接口、DNSResolver 实现、LookupHost 方法 |
|
|
||||||
| `cache.go` | DNS 缓存管理：缓存条目结构、TTL 过期、缓存命中统计 |
|
|
||||||
| `stats.go` | 统计信息：ResolverStats 结构、缓存命中率、解析延迟追踪 |
|
|
||||||
| `resolver_test.go` | 单元测试：解析功能、缓存行为、错误处理测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- Resolver 接口定义：LookupHost、LookupHostWithCache、Refresh、Start、Stop
|
|
||||||
- 使用 sync.Map 实现并发安全缓存
|
|
||||||
- 后台刷新需要调用 Start() 启动
|
|
||||||
- 停止使用时应调用 Stop() 释放资源
|
|
||||||
- 用于代理模块动态解析 upstream 域名
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/resolver/...`
|
|
||||||
- 测试覆盖缓存逻辑和错误处理
|
|
||||||
- 集成测试在 `../integration/` 目录
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 接口设计支持多种解析器实现
|
|
||||||
- 缓存条目包含 TTL 和过期时间
|
|
||||||
- 统计信息使用 atomic 计数器
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../config/` - ResolverConfig 配置结构体
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `net` - Go 标准库 DNS 解析
|
|
||||||
- `sync` - 并发安全
|
|
||||||
- `context` - 上下文超时控制
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,49 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# server
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
HTTP 服务器核心，提供服务器创建、启动、停止和虚拟主机管理功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `server.go` | 服务器核心：Server 结构体、Start()、Stop()、GracefulStop() |
|
|
||||||
| `vhost.go` | 虚拟主机管理：VHostManager、VirtualHost、按 Host 头匹配 |
|
|
||||||
| `pool.go` | 连接池管理：Worker 池、连接复用、并发控制 |
|
|
||||||
| `upgrade.go` | 热升级：UpgradeManager、USR2 信号处理、平滑交接 |
|
|
||||||
| `status.go` | 状态监控：健康端点、统计信息、Prometheus 格式 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 使用 `fasthttp.Server` 配置超时和连接限制
|
|
||||||
- `Start()` 初始化日志、创建路由、注册静态处理器、应用中间件
|
|
||||||
- 默认超时：ReadTimeout 30s、WriteTimeout 30s、IdleTimeout 120s
|
|
||||||
- `Stop()` 快速停止，`GracefulStop()` 等待请求完成
|
|
||||||
- `VHostManager` 支持多虚拟主机，按 Host 头匹配，有默认 fallback
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/server/...`
|
|
||||||
- 测试服务器启动/停止、虚拟主机匹配
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 服务器配置从 `config.Config` 读取
|
|
||||||
- 路由使用 `handler.NewRouter()` 创建
|
|
||||||
- 中间件通过 `middleware.NewChain().Apply()` 应用
|
|
||||||
- Host 头匹配时去除端口号
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../config/` - 服务器配置
|
|
||||||
- `../handler/` - 路由和静态处理器
|
|
||||||
- `../logging/` - 日志初始化
|
|
||||||
- `../middleware/` - 中间件链
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 服务器框架
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,44 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# ssl
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
SSL/TLS 模块，提供证书加载、OCSP Stapling 和 TLS 配置管理功能。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `ssl.go` | SSL/TLS 核心：证书加载、TLS 配置、SNI 支持、会话缓存 |
|
|
||||||
| `ocsp.go` | OCSP Stapling：在线证书状态查询、缓存、自动刷新 |
|
|
||||||
| `ssl_test.go` | SSL/TLS 测试 |
|
|
||||||
| `ocsp_test.go` | OCSP 测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 支持多证书加载，按 SNI 匹配
|
|
||||||
- OCSP Stapling 提升 TLS 握手性能
|
|
||||||
- TLS 配置强制使用安全参数（TLS 1.2+、强密码套件）
|
|
||||||
- 会话缓存减少握手开销
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/ssl/...`
|
|
||||||
- 测试证书加载、OCSP 查询、TLS 配置
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 证书格式支持 PEM
|
|
||||||
- OCSP 响应缓存 1 小时
|
|
||||||
- 会话票据自动轮换
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../config/` - SSL 配置
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `crypto/tls` - Go 标准库 TLS 实现
|
|
||||||
- `golang.org/x/crypto/ocsp` - OCSP 协议支持
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,38 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
|
|
||||||
|
|
||||||
# sslutil
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
SSL/TLS 工具函数包，提供证书池加载功能，用于配置 SSL 客户端验证和 CA 证书信任链。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `certpool.go` | 证书池加载函数，支持 PEM 格式 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- `LoadCertPool(certFile, _)` 加载 PEM 格式证书池（参数二为历史兼容占位）
|
|
||||||
- `LoadCACertPool(caFile)` 加载 CA 证书池的便捷函数
|
|
||||||
- 返回 `*x509.CertPool` 用于 `TLSConfig.RootCAs` 或 `ClientCAs`
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 无独立测试文件，证书加载在 SSL 模块集成测试中覆盖
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
```go
|
|
||||||
// 加载 CA 证书池用于客户端验证
|
|
||||||
caPool, err := sslutil.LoadCACertPool("/path/to/ca.crt")
|
|
||||||
tlsConfig.ClientCAs = caPool
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `crypto/x509` - 证书池类型
|
|
||||||
- `os` - 文件读取
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,39 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
|
|
||||||
|
|
||||||
# stream
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
TCP/UDP Stream 代理模块，支持四层代理和会话管理。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `stream.go` | Stream 代理核心：TCP/UDP 服务器、连接转发、会话管理 |
|
|
||||||
| `stream_test.go` | Stream 代理测试 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- TCP 代理：监听端口、转发连接、支持多上游
|
|
||||||
- UDP 代理：会话管理、超时控制、NAT 穿透
|
|
||||||
- 会话跟踪：源地址+端口作为键
|
|
||||||
- 超时配置：连接超时、空闲超时
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/stream/...`
|
|
||||||
- 测试 TCP/UDP 监听、连接转发、会话管理
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- TCP 使用 net.Conn 进行双向数据拷贝
|
|
||||||
- UDP 使用会话映射表管理客户端连接
|
|
||||||
- 负载均衡策略与 HTTP 代理共享
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../loadbalance/` - 目标选择
|
|
||||||
- `../config/` - Stream 配置
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,39 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-13 | Updated: 2026-04-13 -->
|
|
||||||
|
|
||||||
# utils
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
HTTP 错误处理工具包，提供统一的错误响应助手函数，减少代码库中散落的 `ctx.Error` 调用模式。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `httperror.go` | HTTP 错误类型定义和发送助手函数 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 使用预定义的 `HTTPError` 变量（如 `ErrNotFound`, `ErrForbidden`）而不是手动构造
|
|
||||||
- 通过 `SendError(ctx, err)` 发送标准错误响应
|
|
||||||
- 需要额外详情时使用 `SendErrorWithDetail(ctx, err, detail)`
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 无独立测试文件，错误处理在其他模块测试中覆盖
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
```go
|
|
||||||
// 发送标准错误
|
|
||||||
utils.SendError(ctx, utils.ErrNotFound)
|
|
||||||
|
|
||||||
// 发送带详情的错误
|
|
||||||
utils.SendErrorWithDetail(ctx, utils.ErrBadGateway, "backend timeout")
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - HTTP 状态码定义
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,48 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
|
|
||||||
|
|
||||||
# variable
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
高性能变量系统，提供 nginx 风格的变量展开功能。用于访问日志格式模板、代理请求头设置、URL 重写规则。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `variable.go` | 变量系统核心：Context 结构、Expand 方法、变量存储接口 |
|
|
||||||
| `builtin.go` | 内置变量定义：$remote_addr、$request_uri、$status、$time_local 等nginx 风格变量 |
|
|
||||||
| `pool.go` | sync.Pool 复用：PoolGet、PoolPut、池统计信息 |
|
|
||||||
| `ssl.go` | SSL 相关变量：$ssl_protocol、$ssl_cipher、$ssl_client_sni 等 |
|
|
||||||
| `variable_test.go` | 单元测试：变量展开、内置变量获取、自定义变量 |
|
|
||||||
| `variable_bench_test.go` | 基准测试：展开性能、池性能 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 支持两种变量格式：$var 和 ${var}（用于变量后有字符）
|
|
||||||
- 使用快速字符串扫描（非正则表达式）提升性能
|
|
||||||
- sync.Pool 复用 Context 减少 GC 压力
|
|
||||||
- 内置变量惰性求值并缓存结果
|
|
||||||
- 自定义变量通过 Set 方法设置
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 运行测试：`go test ./internal/variable/...`
|
|
||||||
- 基准测试验证展开性能：`go test -bench=. ./internal/variable/...`
|
|
||||||
- 集成测试在 `../integration/` 目录
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- Context 绑定到单个请求
|
|
||||||
- 从池获取：PoolGet(ctx)，放回：PoolPut(vc)
|
|
||||||
- 全局变量通过 SetGlobalVariables 设置
|
|
||||||
- 上游变量：$upstream_addr、$upstream_status、$upstream_response_time
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- 无内部依赖，底层模块
|
|
||||||
|
|
||||||
### External
|
|
||||||
- `github.com/valyala/fasthttp` - RequestCtx 类型
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
@ -1,39 +0,0 @@
|
|||||||
<!-- Parent: ../AGENTS.md -->
|
|
||||||
<!-- Generated: 2026-04-07 | Updated: 2026-04-07 -->
|
|
||||||
|
|
||||||
# scripts
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
构建和测试辅助脚本目录，包含回归检测、CI/CD 相关的自动化脚本。
|
|
||||||
|
|
||||||
## Key Files
|
|
||||||
|
|
||||||
| File | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `check_regression.py` | 基准测试回归检测脚本，比较新旧结果检测性能退化 |
|
|
||||||
|
|
||||||
## For AI Agents
|
|
||||||
|
|
||||||
### Working In This Directory
|
|
||||||
- 回归检测脚本用于 CI/CD 流程中自动检测性能退化
|
|
||||||
- Python 脚本需要依赖环境配置
|
|
||||||
- 脚本通过 Makefile 命令调用
|
|
||||||
|
|
||||||
### Testing Requirements
|
|
||||||
- 无独立测试，作为 CI/CD 工具使用
|
|
||||||
- 通过 `make benchmark-regression` 执行回归检测
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
- 回归检测比较基准测试结果的 QPS 和延迟变化
|
|
||||||
- 配置阈值定义可接受的性能波动范围
|
|
||||||
- 输出报告用于 PR 审核和决策
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- `../internal/benchmark/` - 基准测试结果数据源
|
|
||||||
|
|
||||||
### External
|
|
||||||
- Python 3.x - 脚本运行环境
|
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
|
||||||
Loading…
x
Reference in New Issue
Block a user