xfy
ad177e9640
为所有 Lua API 文件添加完整的包级和函数级文档注释： - api_balancer: 负载均衡 API（set_current_peer, set_more_tries 等） - api_ctx: 请求上下文存储 API（ngx.ctx） - api_location: 子请求捕获 API（ngx.location.capture） - api_log: 日志输出 API（ngx.log） - api_req: 请求对象 API - api_resp: 响应对象 API - api_shared_dict: 共享字典 API - api_socket_tcp: TCP socket API - api_timer: 定时器 API - api_var: 变量 API - engine: Lua 引擎核心 - context: 请求上下文管理 - coroutine: 协程调度器 - middleware: 中间件集成 - filter_writer: 响应过滤器 - cache: Lua 脚本缓存 - shared_dict: 共享字典实现 - socket_manager: socket 连接管理 注释格式遵循 Go 官方风格，包含功能说明、参数说明和注意事项。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
60 lines
1.8 KiB
Go
60 lines
1.8 KiB
Go
// Package lua 提供 ngx.ctx API 实现。
|
||
//
|
||
// 该文件实现 ngx.ctx 子模块，提供每请求独立的 Lua table 存储。
|
||
// ngx.ctx 是 OpenResty/ngx_lua 中的标准 API，允许在请求生命周期内
|
||
// 跨不同阶段（rewrite、access、content、log）共享数据。
|
||
//
|
||
// 注意事项：
|
||
// - ngx.ctx 在 timer callback 上下文中不可用（通过 RegisterSchedulerUnsafeCtxAPI 拦截）
|
||
//
|
||
// 作者：xfy
|
||
package lua
|
||
|
||
import (
|
||
glua "github.com/yuin/gopher-lua"
|
||
)
|
||
|
||
// RegisterNgxCtxAPI 在 Lua 状态机中注册 ngx.ctx API。
|
||
//
|
||
// ngx.ctx 是一个每请求独立的 Lua table，可通过 ngx.ctx.key 或 ngx.ctx[key]
|
||
// 读写任意 Lua 值类型（字符串、数字、table 等）。
|
||
//
|
||
// 参数：
|
||
// - L: Lua 状态
|
||
// - ngxTable: ngx 全局表
|
||
func RegisterNgxCtxAPI(L *glua.LState, ngxTable *glua.LTable) {
|
||
// 创建请求级的 ctx table
|
||
ctxTable := L.NewTable()
|
||
|
||
// 将 ngx.ctx 添加到 ngx 表
|
||
ngxTable.RawSetString("ctx", ctxTable)
|
||
}
|
||
|
||
// RegisterSchedulerUnsafeCtxAPI 为 Scheduler LState 注册不可用的 ngx.ctx API。
|
||
//
|
||
// 在 timer callback 等受限上下文中，ngx.ctx 不可用（无请求上下文）。
|
||
// 此函数将 ngx.ctx 的所有读写操作替换为返回错误的桩函数。
|
||
//
|
||
// 参数：
|
||
// - L: Lua 状态
|
||
// - ngx: ngx 全局表
|
||
func RegisterSchedulerUnsafeCtxAPI(L *glua.LState, ngx *glua.LTable) {
|
||
ctxTable := L.NewTable()
|
||
mt := L.NewTable()
|
||
|
||
methods := []APIMethod{
|
||
{Name: "__index", Func: luaSchedulerUnsafeCtx},
|
||
{Name: "__newindex", Func: luaSchedulerUnsafeCtx},
|
||
}
|
||
RegisterAPIMethods(L, mt, methods)
|
||
|
||
L.SetMetatable(ctxTable, mt)
|
||
ngx.RawSetString("ctx", ctxTable)
|
||
}
|
||
|
||
// luaSchedulerUnsafeCtx 返回 scheduler 模式下 ngx.ctx 不可用的错误。
|
||
func luaSchedulerUnsafeCtx(L *glua.LState) int {
|
||
L.RaiseError("API ngx.ctx not available in timer callback context")
|
||
return 0
|
||
}
|