lolly/internal/lua/AGENTS.md

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

// 创建引擎
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 请求上下文