Awesome
Name
array-var-nginx-module - Add support for array-typed variables to nginx config files
This module is not distributed with the Nginx source. See the installation instructions.
Table of Contents
- Name
- Status
- Synopsis
- Description
- Directives
- Installation
- Compatibility
- Source Repository
- Getting involved
- Author
- Copyright & License
- See Also
Status
This module is production ready.
Synopsis
location /foo {
array_split ',' $arg_files to=$array;
# use the set_quote_sql_str directive in the ngx_set_misc
# module to map to each element in the array $array:
array_map_op set_quote_sql_str $array;
array_map "name = $array_it" $array;
array_join ' or ' $array to=$sql_condition;
# well, we could feed it to ngx_drizzle to talk to MySQL, for example ;)
echo "select * from files where $sql_condition";
}
Description
This module provides array typed nginx variables to nginx.conf
.
Under the hood, this module just "abuses" the nginx string values to hold binary pointers
to C data structures (NGINX core's ngx_array_t
struct on the C land).
The array type gives nginx.onf
wonderful capabilities of handling value lists. Nowadays, however,
you are highly recommended to use the ngx_lua module
so as to have the full scripting power provided by the Lua language in nginx.
Directives
array_split
syntax: array_split <separator> <subject> to=$target_variable
default: no
context: http, server, server if, location, location if
Splits the string value in the subject
argument with the separator string specified by the
separator
argument. The result is an array-typed value saved to the nginx variable specified by the to=VAR
option.
For example,
array_split "," $arg_names to=$names;
will split the string values in the URI query argument names
into an array-typed value saved to the custom nginx variable
$names
.
This directive creates an array-typed variable. Array-typed variables cannot be used outside the directives offered by this module. If you want to use the values in an array-typed variable in other contexts, you must use the array_join directive to produce a normal string value.
array_join
syntax: array_split <separator> $array_var
default: no
context: http, server, server if, location, location if
Joins the elements in the array-typed nginx variable ($array_var
) into a single string value
with the separator specified by the first argument.
For example,
location /foo {
array_split ',' $arg_names to=$names;
array_join '+' $names;
echo $names;
}
Then request GET /foo?names=Bob,Marry,John
will yield the response body
Bob+Marry+John
In the example above, we use the ngx_echo module's echo directive to output the final result.
array_map
syntax: array_map <template> $array_var
syntax: array_map <template> $array_var to=$new_array_var
default: no
context: http, server, server if, location, location if
Maps the string template to each element in the array-typed nginx variable specified. Within
the string template, you can use the special iterator variable $array_it
to reference the current
array element in the array being mapped.
For example,
array_map "[$array_it]" $names;
will change each element in the array variable $names
by putting the square brackets around
each element's string value. The modification is in-place in this case.
If you do not want in-place modifications, you can use the to=$var
option to specify a new nginx variable to hold the results. For instance,
array_map "[$array_it]" $names to=$new_names;
where the results are saved into another (array-typed) nginx variable named $new_names
while
the $names
variable keeps intact.
Below is a complete example for this:
location /foo {
array_split ',' $arg_names to=$names;
array_map '[$array_it]' $names;
array_join '+' $names;
echo "$names";
}
Then request GET /foo?names=bob,marry,nomas
will yield the response body
[bob]+[marry]+[nomas]
array_map_op
syntax: array_map_op <directive> $array_var
syntax: array_map_op <directive> $array_var to=$new_array_var
default: no
context: http, server, server if, location, location if
Similar to the array_map directive but maps the specified nginx configuration directive instead of a string template to each element in the array-typed nginx variable specified. The result of applying the specified configuration directive becomes the result of the mapping.
The nginx configuration directive being used as the iterator must be implemented by Nginx Devel Kit (NDK)'s set_var submodule's ndk_set_var_value
.
For example, the following set-misc-nginx-module directives can be invoked this way:
- set_quote_sql_str
- set_quote_pgsql_str
- set_quote_json_str
- set_unescape_uri
- set_escape_uri
- set_encode_base32
- set_decode_base32
- set_encode_base64
- set_decode_base64
- set_encode_hex
- set_decode_hex
- set_sha1
- set_md5
This is a higher-order operation where other nginx configuration directives can be used
as arguments for this map_array_op
directive.
Consider the following example,
array_map_op set_quote_sql_str $names;
This line changes each element in the array-typed nginx variable $names
by applying the
set_quote_sql_str
directive provided by the ngx_set_misc
module one by one. The result is that each element in the array $names
has been escaped as SQL string literal values.
You can also specify the to=$var
option if you do not want in-place modifications of the input arrays. For instance,
array_map_op set_quote_sql_str $names to=$quoted_names;
will save the escaped elements into a new (array-typed) nginx variable named $quoted_names
with $names
intact.
The following is a relatively complete example:
location /foo {
array_split ',' $arg_names to=$names;
array_map_op set_quote_sql_str $names;
array_join '+' $names to=$res;
echo $res;
}
Then request GET /foo?names=bob,marry,nomas
will yield the response body
'bob'+'marry'+'nomas'
Pretty cool, huh?
Installation
You're recommended to install this module (as well as the Nginx core and many other goodies) via the OpenResty bundle. See the detailed instructions for downloading and installing OpenResty into your system. This is the easiest and most safe way to set things up.
Alternatively, you can install this module manually with the Nginx source:
Grab the nginx source code from nginx.org, for example, the version 1.13.6 (see nginx compatibility), and then build the source with this module:
wget 'http://nginx.org/download/nginx-1.13.6.tar.gz'
tar -xzvf nginx-1.13.6.tar.gz
cd nginx-1.13.6/
# Here we assume you would install you nginx under /opt/nginx/.
./configure --prefix=/opt/nginx \
--add-module=/path/to/ngx_devel_kit \
--add-module=/path/to/array-var-nginx-module
make -j2
make install
Download the latest version of the release tarball of this module from array-var-nginx-module file list, and the latest tarball for ngx_devel_kit from its file list.
Also, this module is included and enabled by default in the OpenResty bundle.
Building as a dynamic module
Starting from NGINX 1.9.11, you can also compile this module as a dynamic module, by using the --add-dynamic-module=PATH
option instead of --add-module=PATH
on the
./configure
command line above. And then you can explicitly load the module in your nginx.conf
via the load_module
directive, for example,
load_module /path/to/modules/ndk_http_module.so; # assuming NDK is built as a dynamic module too
load_module /path/to/modules/ngx_http_array_var_module.so;
Compatibility
The following versions of Nginx should work with this module:
- 1.13.x (last tested: 1.13.6)
- 1.12.x
- 1.11.x (last tested: 1.11.2)
- 1.10.x
- 1.9.x (last tested: 1.9.7)
- 1.8.x
- 1.7.x (last tested: 1.7.10)
- 1.6.x
- 1.5.x (last tested: 1.5.12)
- 1.4.x (last tested: 1.4.2)
- 1.2.x (last tested: 1.2.9)
- 1.1.x (last tested: 1.1.5)
- 1.0.x (last tested: 1.0.8)
- 0.9.x (last tested: 0.9.4)
- 0.8.x (last tested: 0.8.54)
- 0.7.x >= 0.7.44 (last tested: 0.7.68)
Earlier versions of Nginx like 0.6.x and 0.5.x will not work.
If you find that any particular version of Nginx above 0.7.44 does not work with this module, please consider reporting a bug.
Source Repository
Available on github at openresty/array-var-nginx-module.
Getting involved
You'll be very welcomed to submit patches to the author or just ask for a commit bit to the source repository on GitHub.
Author
Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>, CloudFlare Inc.
Copyright & License
Copyright (c) 2009-2016, Yichun Zhang (agentzh) <agentzh@gmail.com>, CloudFlare Inc.
This module is licensed under the terms of the BSD license.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.