test: register a custom variable in a custom Lua file and source it with extra_lua_path

docs/en/latest/plugin-develop.md

@@ -1,5 +1,5 @@
 ---
-title: Plugin Develop
+title: Develop Plugin
 ---
 
 <!--
@@ -71,8 +71,7 @@ apisix:
     lua_module_hook: "my_hook"
 ```
 
-The `example/my_hook.lua` will be loaded when APISIX starts, and you can use this hook to replace a method in APISIX.
-The example of [my_hook.lua](https://github.com/apache/apisix/blob/master/example/my_hook.lua) can be found under the `example` directory of this project.
+The `example/my_hook.lua` will be loaded when APISIX starts, and you can use this hook to replace a method in APISIX. The example of [my_hook.lua](https://github.com/apache/apisix/blob/master/example/my_hook.lua) can be found under the `example` directory of this project.
 
 ## check dependencies
 
@@ -488,25 +487,33 @@ curl -i -X GET "http://127.0.0.1:9090/v1/plugin/example-plugin/hello"
 
 ## register custom variable
 
-We can use variables in many places of APISIX. For example, customizing log format in http-logger, using it as the key of `limit-*` plugins. In some situations, the builtin variables are not enough. Therefore, APISIX allows developers to register their variables globally, and use them as normal builtin variables.
+You can also register your own variables and use them as built-in variables, for use cases such as customizing log format in logging plugins, or using built-in variables as keys in rate limiting plugins.
 
-For instance, let's register a variable called `a6_labels_zone` to fetch the value of the `zone` label in a route:
+For example, you can register a variable called `a6_route_labels` to obtain `labels` from a route:
 
-```
+```lua
 local core = require "apisix.core"
 
-core.ctx.register_var("a6_labels_zone", function(ctx)
+core.ctx.register_var("a6_route_labels", function(ctx)
     local route = ctx.matched_route and ctx.matched_route.value
     if route and route.labels then
-        return route.labels.zone
+      return route.labels
     end
     return nil
 end)
 ```
 
-After that, any get operation to `$a6_labels_zone` will call the registered getter to fetch the value.
+If you are developing a new plugin, the snippet could be added directly to your plugin source file.
+
+::: info
+
+If you are not doing development and would like to register a custom variable at runtime, you can run the snippet in serverless functions with the [`serverless`](plugins/serverless.md) plugins.
+
+:::
+
+Upon a successful registration, you can use the variable `$a6_route_labels` in configurations.
 
-Note that the custom variables can't be used in features that depend on the Nginx directive, like `access_log_format`.
+Note that the custom variables cannot be used in static configuration files, for example, to configure `access_log_format`.
 
 ## write test case
 

example/register_custom_var.lua

@@ -0,0 +1,42 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements.  See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License.  You may obtain a copy of the License at
+--
+--     http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local apisix = require "apisix"
+local core = require "apisix.core"
+
+local register_custom_var = function()
+    core.ctx.register_var("a6_route_labels", function(ctx)
+        local route = ctx.matched_route and ctx.matched_route.value
+        if route and route.labels then
+            return route.labels
+        end
+        return nil
+    end)
+end
+
+local old_http_init = apisix.http_init
+apisix.http_init = function(...)
+    register_custom_var()
+    ngx.log(ngx.EMERG, "my hook works in http")
+    old_http_init(...)
+end
+
+local old_stream_init = apisix.stream_init
+apisix.stream_init = function(...)
+    register_custom_var()
+    ngx.log(ngx.EMERG, "my hook works in stream")
+    old_stream_init(...)
+end

t/cli/test_main.sh

@@ -654,7 +654,7 @@ fi
 
 echo "passed: detect invalid extra_lua_path"
 
-# support hooking into APISIX methods
+# validate lua_module_hook
 echo '
 apisix:
     lua_module_hook: "example/my_hook"
@@ -668,6 +668,7 @@ fi
 
 echo "passed: bad lua_module_hook should be rejected"
 
+# support hooking into APISIX methods
 echo '
 apisix:
     proxy_mode: http&stream
@@ -697,6 +698,36 @@ fi
 
 echo "passed: hook can take effect"
 
+# register custom variable with the hook
+echo '
+apisix:
+    proxy_mode: http&stream
+    extra_lua_path: "\$prefix/example/?.lua"
+    lua_module_hook: "register_custom_var"
+    stream_proxy:
+        tcp:
+            - addr: 9100
+' > conf/config.yaml
+
+rm logs/error.log
+make init
+make run
+
+sleep 0.5
+make stop
+
+if ! grep "my hook works in http" logs/error.log > /dev/null; then
+    echo "failed: hook can take effect"
+    exit 1
+fi
+
+if ! grep "my hook works in stream" logs/error.log > /dev/null; then
+    echo "failed: hook can take effect"
+    exit 1
+fi
+
+echo "passed: register custom variable with hook"
+
 # check the keepalive related parameter settings in the upstream
 git checkout conf/config.yaml