# 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 请求上下文