OpenResty之ngx.var.VARIABLE
1. ngx.var.VARIABLE
syntax: ngx.var.VAR_NAME
context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua*
读或者写 Nginx 变量值：
value = ngx.var.some_nginx_variable_name
ngx.var.some_nginx_variable_name = value
注：仅仅是已经定义了的 Nginx 变量可以被写入：
location /foo {
set $my_var ''; # this line is required to create $my_var at config time
content_by_lua_block {
ngx.var.my_var = 123
...
}
}
也就是说，无法动态创建 Nginx 变量。
一些特殊的变量（如 $args 和 $limit_rate）可以被分配一个值，其他许多变量不是，如 $query_string, $arg_PARAMETER, $http_NAME。
Nginx 正则组捕获变量 $1, $2, $3 等等，也可以通过编写 ngx.var[1], ngx.var[2], ngx.var[3] 等来读取此接口。
设置 ngx.var.Foo 为 nil 值将会删除 $Foo Nginx 变量:
ngx.var.args = nil
警告：当读取 Nginx 变量时，Nginx 将在每个请求的内存池中分配内存，在请求结束时才释放。因此当需要在 Lua 代码中重复读取 Nginx 变量时，缓存该 Nginx 变量到你自己的 Lua 变量中，如下：
local val = ngx.var.some_var
--- use the val repeatedly later
为了防止在当前请求的生命周期内发生内存泄露，缓存结果的另一种方法是使用 ngx.ctx 表。
未定义的 Nginx 变量值为 nil，而定义了但没初始化的 Nginx 变量值为 Lua 的空字符串。
该 API 需要相对昂贵的元方法调用，建议避免在 hot 代码路径中使用它。
2. 源码实现
2.1 ngx_http_lua_inject_variable_api
在 OpenResty 中，通过该函数将 ngx.var 相关函数注册进来。
void
ngx_http_lua_inject_variable_api(lua_State *L)
{
/* {{{ regoster reference maps */
/* 创建一张空表，并将其压栈。等价于 lua_createtable(L, 0, 0) */
lua_newtable(L); /* ngx.var */
/* 创建一张新的空表并压栈。
* 第二个参数建议了这张表作为数组使用时会有多少个元素；
* 第三个参数建议了这张表可能拥有多少数组之外的元素，即元方法。
* Lua 会使用这些建议来分配这张表。如果你知道这张表用途的更多信息，预分配
* 可以提高性能。否则，你可以使用函数 lua_newtable */
lua_createtable(L, 0, 2 /* nrec */); /* metatable for .var */
/* 将一个 C 函数压栈。这个函数接收一个 C 函数指针，并将一个类型为 function 的 Lua 值
* 压栈。当这个栈顶的值被调用时，将触发对应的 C 函数。
* 注册到 Lua 中的任何函数都必须遵循正确的协议来接收参数和返回值(参见 lua_CFunction) */
lua_pushcfunction(L, ngx_http_lua_var_get);
/* 做一个等价于 t[k] = v 的操作，这里的 t 是给出的索引处的值，而 v 是栈顶的那个值。
* 这个函数将把这个值弹出栈。跟在 lua 中一样，这个函数可能触发一个 "newindex" 事件的元方法 */
lua_setfield(L, -2, "__index");
lua_pushcfunction(L, ngx_http_lua_var_set);
lua_setfield(L, -2, "__newindex");
/* 把一张表弹出栈，并将其设为给定索引处(这个为-2)的值的元表 */
lua_setmetatable(L, -2);
lua_setfield(L, -2, "var");
}
2.2 ngx_http_lua_var_get
当 ngx.var 表中不存在 key 对应的值时，则会调用该函数。
/**
* Get nginx internal variables content
*
* @retval Always return a string or nil on Lua stack. Return nil when failed
* to get content, and actual content string when found the specified variable.
* @seealso ngx_http_lua_var_set
*/
static int
ngx_http_lua_var_get(lua_State *L)
{
ngx_http_request_t *r;
u_char *p, *lowcase;
size_t len;
ngx_uint_t hash;
ngx_str_t name;
ngx_http_variable_value_t *vv;
#if (NGX_PCRE)
u_char *val;
ngx_uint_t n;
LUA_NUMBER index;
int *cap;
#endif
/* 获取当前请求上下文结构体 */
r = ngx_http_lua_get_req(L);
if (r == NULL) {
/* 抛出一个错误。错误消息的格式由 fmt 给出。后面需提供若干参数，这些参数
* 遵循 lua_pushfstring 中的规则。如果能获得相关信息，它还会在消息前面
* 加上错误发生时的文件名及行号。
* 这个函数永远不会返回。但是在 C 函数中通常遵循惯用法：
* return luaL_error(args) */
return luaL_error(L, "no request object found");
}
/* 检测当前请求的 socket 套接字是否有效 */
ngx_http_lua_check_fake_request(L, r);
#if (NGX_PCRE)
/* 返回给定有效索引处值的类型，当索引无效（或无法访问）时返回 LUA_TNONE。
* lua_type 返回的类型被编码为一些在 lua.h 中定义的常量: LUA_TNIL, LUA_TNUMBER,
* LUA_TBOOLEAN, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA,
* LUA_TTHREAD, LUA_TLIGHTUSERDATA */
if (lua_type(L, -1) == LUA_TNUMBER) {
/* it is a regex capturing variable */
/* 把给定索引处的 Lua 值转换为 lua_Number 这样一个 C 类型。这个 Lua 值
* 必须是一个数字或是一个可转换为数字的字符串；否则，lua_tonumber 返回 0 */
index = lua_tonumber(L, -1);
if (index <= 0) {
/* 将空值压栈 */
lua_pushnil(L);
return 1;
}
n = (ngx_uint_t) index * 2;
dd("n = %d, ncaptures = %d", (int) n, (int) r->ncaptures);
if (r->captures == NULL
|| r->captures_data == NULL
|| n >= r->ncaptures)
{
lua_pushnil(L);
return 1;
}
/* n >= 0 && n < r->ncaptures */
cap = r->captures;
p = r->captures_data;
val = &p[cap[n]];
/* 把指针 val 指向的长度为 len 的字符串压栈。Lua 对这个字符串做一个内部副本
* （或是复用一个副本），因此 val 处的内存在函数返回后，可以释放掉或是立刻
* 重用于其他用途。字符串内可以是任意二进制数据，包括零字符。
* 返回内部副本的指针 */
lua_pushlstring(L, (const char *) val, (size_t) (cap[n + 1] - cap[n]));
return 1;
}
#endif
if (lua_type(L, -1) != LUA_TSTRING) {
return luaL_error(L, "bad variable name");
}
/* 把给定索引处的 Lua 值转换为一个 C 字符串。如果 len 不为 NULL，它还把字符串
* 长度设到 *len 中。这个 Lua 值必须是一个字符串或是一个数字；否则返回 NULL。
* 如果值是一个数字，lua_tolstring 还会把堆栈中的那个值的实际类型转换为一个
* 字符串。（当遍历一张表的时候，若把 lua_tolstring 作用在键上，这个转换有可能
* 导致 lua_next 弄错）
* lua_tolstring 返回一个已对齐指针指向 Lua 状态机中的字符串。这个字符串总能
* 保证（C 要求的）最后一个字符为零('\0')，而且它允许在字符串内包含多个这样的零
* 因为 Lua 中可能发生垃圾收集，所以不保证 lua_tolstring 返回的指针，在对应的值
* 从堆栈中移除后依然有效 */
p = (u_char *) lua_tolstring(L, -1, &len);
/* 这个函数分配一块指定大小的内存块，把内存块地址作为一个完全用户数据压栈，
* 并返回这个地址。宿主程序可以随意使用这块内存 */
lowcase = lua_newuserdata(L, len);
/* 将 p 指向 len 长度字符串拷贝到 lowcase，同时转为小写，并返回一个hash值 */
hash = ngx_hash_strlow(lowcase, p, len);
/* 设置该 Nginx 内部变量的长度和名称 */
name.len = len;
name.data = lowcase;
/* 根据 name 获取对应的值 */
vv = ngx_http_get_variable(r, &name, hash);
if (vv == NULL || vv->not_found) {
lua_pushnil(L);
return 1;
}
lua_pushlstring(L, (const char *) vv->data, (size_t) vv->len);
return 1;
}
ngx_http_lua_get_req
获取当前请求上下文结构体。
#define ngx_http_lua_req_key "__ngx_req"
static ngx_inline ngx_http_request_t *
ngx_http_lua_get_req(lua_State *L)
{
ngx_http_request_t *r;
/* 把全局变量 name(这里为 ngx_http_lua_req_key) 里的值压栈，返回该值的类型 */
lua_getglobal(L, ngx_http_lua_req_key);
/* 如果给定索引处的值是一个完全用户数据，函数返回其内存块的地址。如果只是一个
* 轻量用户数据，那么就返回它表示的指针。否则，返回 NULL */
r = lua_touserdata(L, -1);
/* 从栈中弹出 n 个元素（这里为 1 个） */
lua_pop(L, 1);
return r;
}
ngx_http_lua_check_fake_request
检测当前连接的 socket 套接字是否有效。
#define ngx_http_lua_check_fake_request(L, r) \
if ((r)->connection->fd == (ngx_socket_t) -1) { \
return luaL_error(L, "API disabled in the current context"); \
}
ngx_http_get_variable
根据变量名获取该变量对应的值。
ngx_http_variable_value_t *
ngx_http_get_variable(ngx_http_request_t *r, ngx_str_t *name, ngx_uint_t key)
{
size_t len;
ngx_uint_t i, n;
ngx_http_variable_t *v;
ngx_http_variable_value-t *vv;
ngx_http_core_main_conf_t *cmcf;
cmcf = ngx_http_get_module_main_conf(r, ngx_http_core_module);
v = ngx_hash_find(&cmcf->variable_hash, key, name->data, name->len);
if (v) {
if (v->flags & NGX_HTTP_VAR_INDEXED) {
return ngx_http_get_flushed_variable(r, v->index);
}
if (ngx_http_variable_depth == 0) {
ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
"cycle while evaluating variable \"%V\"", name);
return NULL;
}
ngx_http_variable_depth--;
vv = ngx_palloc(r->pool, sizeof(ngx_http_variable_value_t));
if (vv && v->get_handler(r, vv, v->data) == NGX_OK) {
ngx_http_variable_depth++;
return vv;
}
ngx_http_variable_depth++;
return NULL;
}
vv = ngx_palloc(r->pool, sizeof(ngx_http_variable_value_t));
if (vv == NULL) {
return NULL;
}
len = 0;
v = cmcf->prefix_variables.elts;
n = cmcf->prefix_variables.nelts;
for (i = 0; i < cmcf->prefix_variables.nelts; i++) {
if (name->len >= v[i].name.len && name->len > len
&& ngx_strncmp(name->data, v[i].name.data, v[i].name.len) == 0)
{
len = v[i].name.len;
n = i;
}
}
if (n != cmcf->prefix_variables.nelts) {
if (v[n].get_handler(r, vv, (uintptr_t) name) == NGX_OK) {
return v;
}
return NULL;
}
vv->not_found = 1;
return vv;
}
2.3 ngx_http_lua_var_set
/**
* Set nginx internal variable content
*
* @retval Always return a boolean on Lua stack. Return true when variable
* content was modified successfully, false otherwise.
* @seealso ngx_http_lua_var_get
*/
static int
ngx_http_lua_var_set(lua_State *L)
{
ngx_http_variable_t *v;
ngx_http_variable_value_t *vv;
ngx_http_core_main_conf_t *cmcf;
u_char *p, *lowcase, *val;
size_t len;
ngx_str_t name;
ngx_uint_t hash;
ngx_http_request_t *r;
int value_type;
const char *msg;
r = ngx_http_lua_get_req(L);
if (r == NULL) {
return luaL_error(L, "no request object found");
}
ngx_http_lua_check_fake_request(L, r);
/* we skip the first argument that is the table */
/* we read the variable name */
if (lua_type(L, 2) != LUA_TSTRING) {
/* 抛出一个错误，该函数永不返回，以下是通常写法 */
return luaL_error(L, "bad variable name")
}
/* 将指定索引处的 Lua 值转换为一个 C 字符串，转换后的长度通过 len 返回
* 该 Lua 值必须是一个数字或字符串，否则返回 NULL */
p = (u_char *) lua_tolstring(L, 2, &len);
/* 分配一块指定大小的内存块，并把内存地址作为一个完全用户数据压栈，并返回这个地址 */
lowcase = lua_newuserdata(L, len + 1);
hash = ngx_hash_strlow(lowcase, p, len);
lowcase[len] = '\0';
name.len = len;
name.data = lowcase;
/* we read the variable new value */
/* 返回指定有效索引处的 Lua 值的类型，当索引无效（或无法访问）时返回 LUA_TNONE */
value_type = lua_type(L, 3);
switch (value_type) {
case LUA_TNUMBER:
case LUA_TSTRING:
/* 检查指定索引处的 Lua 值是否是一个字符串，并返回该字符串，长度值通过 len 返回 */
p = (u_char *) luaL_checklstring(L, 3, &len);
val = ngx_palloc(r->pool, len);
if (val == NULL) {
return luaL_error(L, "memory allocation error");
}
ngx_memcpy(val, p, len);
break;
case LUA_TNIL:
/* undef the variable */
val = NULL;
len = 0;
break;
default:
/* 将一个格式化后的字符串压栈，然后返回该字符串的指针。它和 C 函数 printf 比较像，
* 但有一些重要的区别:
* - 不需要为结果分配空间：其结果是一个 Lua 字符串，由 Lua 来关心其内存分配
* （通过 gc 释放内存）
* - 该转换非常的受限。不支持符号、宽度、精度。转换符只支持 '%%'(插入一个字符'%')，
* '%s'(插入一个带零终止符的字符串，没有长度限制)，'%f'(插入一个 lua_Nubmer)，
* '%L'(插入一个 lua_Integer)，'%p'(插入一个指针或一个十六进制数)，
* '%d'(插入一个 int)，'%c'(插入一个用 int 表示的单字节字符)，
* '%U'(插入一个用 long int 表示的 UTF-8 字) */
msg = lua_pushfstring(L, "string, number, or nil expected, "
"but got %s", lua_typename(L, value_type));
/* 抛出上一个函数压栈的错误报告。使用下列标准信息并包含了一段 extramsg 作为注解:
* bad argument #arg to 'funcname' (extramsg)
* 该函数永不返回 */
return luaL_argerror(L, 1, msg);
}
/* we fetch the variable itself */
cmcf = ngx_http_get_module_main_conf(r, ngx_http_core_module);
v = ngx_hash_find(&cmcf->variable_hash, hash, name.data, name.len);
if (v) {
if (!(v->flags & NGX_HTTP_VAR_CHANGEABLE)) {
return luaL_error(L, "variable \"%s\" not changeable", lowcase);
}
if (v->set_handler) {
dd("set variable with set_handler");
vv = ngx_palloc(r->pool, sizeof(ngx_http_variable_value_t));
if (vv == NULL) {
return luaL_error(L, "no memory");
}
if (value_type == LUA_TNIL) {
vv->valid = 0;
vv->not_found = 1;
vv->no_cacheable = 0;
vv->data = NULL;
vv->len = 0;
} else {
vv->valid = 1;
vv->not_found = 0;
vv->no_cacheable = 0;
vv->data = val;
vv->len = len;
}
v->set_handler(r, vv, v->data);
return 0;
}
if (v->flags & NGX_HTTP_VAR_INDEXED) {
vv = &r->variables[v->index];
dd("set indexed variable");
if (value_type == LUA_TNIL) {
vv->valid = 0;
vv->not_found = 1;
vv->no_cacheable = 0;
vv->data = NULL;
vv->len = 0;
} else {
vv->valid = 1;
vv->not_found = 0;
vv->no_cacheable = 0;
vv->data = val;
vv->len = len;
}
return 0;
}
return luaL_error(L, "variable \"%s\" cannot be assigned a value",
lowcase);
}
/* variable not found */
return luaL_error(L, "variable \"%s\" not found for writing; "
"maybe it is a built-in variable that is not changeable "
"or you forgot to use \"set $%s '';\" "
"in the config file to define it first",
lowcase, lowcase);
}
