Saltar a contenido

array-var: Variables de tipo array para NGINX

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-array-var

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-array-var

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_array_var_module.so;

Este documento describe nginx-module-array-var v0.6 lanzado el 23 de mayo de 2022.

location /foo {
    array_split ',' $arg_files to=$array;

    # usa la directiva set_quote_sql_str en el módulo ngx_set_misc
    # para mapear a cada elemento en el array $array:
    array_map_op set_quote_sql_str $array;

    array_map "name = $array_it" $array;

    array_join ' or ' $array to=$sql_condition;

    # bueno, podríamos alimentarlo a ngx_drizzle para hablar con MySQL, por ejemplo ;)
    echo "select * from files where $sql_condition";
}

Descripción

Este módulo proporciona variables de tipo array para nginx.conf.

Bajo el capó, este módulo simplemente "abusa" de los valores de cadena de nginx para mantener punteros binarios a estructuras de datos en C (la estructura ngx_array_t del núcleo de NGINX).

El tipo array le da a nginx.conf maravillosas capacidades para manejar listas de valores. Sin embargo, hoy en día, se recomienda encarecidamente usar el módulo ngx_lua para tener todo el poder de scripting proporcionado por el lenguaje Lua en nginx.

Directivas

array_split

sintaxis: array_split <separador> <sujeto> to=$variable_objetivo

predeterminado: no

contexto: http, server, server if, location, location if

Divide el valor de cadena en el argumento sujeto con la cadena separadora especificada por el argumento separador. El resultado es un valor de tipo array guardado en la variable nginx especificada por la opción to=VAR.

Por ejemplo,

array_split "," $arg_names to=$names;

dividirá los valores de cadena en el argumento de consulta URI names en un valor de tipo array guardado en la variable nginx personalizada $names.

Esta directiva crea una variable de tipo array. Las variables de tipo array no pueden ser utilizadas fuera de las directivas ofrecidas por este módulo. Si deseas usar los valores en una variable de tipo array en otros contextos, debes usar la directiva array_join para producir un valor de cadena normal.

array_join

sintaxis: array_split <separador> $array_var

predeterminado: no

contexto: http, server, server if, location, location if

Une los elementos en la variable nginx de tipo array ($array_var) en un solo valor de cadena con el separador especificado por el primer argumento.

Por ejemplo,

location /foo {
    array_split ',' $arg_names to=$names;
    array_join '+' $names;
    echo $names;
}

Entonces, la solicitud GET /foo?names=Bob,Marry,John producirá el cuerpo de respuesta

Bob+Marry+John

En el ejemplo anterior, usamos la directiva echo del módulo ngx_echo para mostrar el resultado final.

array_map

sintaxis: array_map <plantilla> $array_var

sintaxis: array_map <plantilla> $array_var to=$nuevo_array_var

predeterminado: no

contexto: http, server, server if, location, location if

Mapea la plantilla de cadena a cada elemento en la variable nginx de tipo array especificada. Dentro de la plantilla de cadena, puedes usar la variable iteradora especial $array_it para hacer referencia al elemento actual del array que se está mapeando.

Por ejemplo,

array_map "[$array_it]" $names;

cambiará cada elemento en la variable de array $names al poner corchetes alrededor del valor de cadena de cada elemento. La modificación es in situ en este caso.

Si no deseas modificaciones in situ, puedes usar la opción to=$var para especificar una nueva variable nginx para mantener los resultados. Por ejemplo,

array_map "[$array_it]" $names to=$new_names;

donde los resultados se guardan en otra variable nginx (de tipo array) llamada $new_names, mientras que la variable $names permanece intacta.

A continuación se muestra un ejemplo completo para esto:

location /foo {
    array_split ',' $arg_names to=$names;
    array_map '[$array_it]' $names;
    array_join '+' $names;
    echo "$names";
}

Entonces, la solicitud GET /foo?names=bob,marry,nomas producirá el cuerpo de respuesta

[bob]+[marry]+[nomas]

array_map_op

sintaxis: array_map_op <directiva> $array_var

sintaxis: array_map_op <directiva> $array_var to=$nuevo_array_var

predeterminado: no

contexto: http, server, server if, location, location if

Similar a la directiva array_map pero mapea la directiva de configuración nginx especificada en lugar de una plantilla de cadena a cada elemento en la variable nginx de tipo array especificada. El resultado de aplicar la directiva de configuración especificada se convierte en el resultado del mapeo.

La directiva de configuración nginx que se utiliza como iterador debe ser implementada por el submódulo set_var del Nginx Devel Kit (NDK) ndk_set_var_value. Por ejemplo, las siguientes directivas del set-misc-nginx-module pueden ser invocadas de esta manera:

Esta es una operación de orden superior donde otras directivas de configuración nginx pueden ser utilizadas como argumentos para esta directiva map_array_op.

Considera el siguiente ejemplo,

array_map_op set_quote_sql_str $names;

Esta línea cambia cada elemento en la variable nginx de tipo array $names aplicando la directiva set_quote_sql_str proporcionada por el módulo ngx_set_misc una por una. El resultado es que cada elemento en el array $names ha sido escapado como valores literales de cadena SQL.

También puedes especificar la opción to=$var si no deseas modificaciones in situ de los arrays de entrada. Por ejemplo,

array_map_op set_quote_sql_str $names to=$quoted_names;

guardará los elementos escapados en una nueva variable nginx (de tipo array) llamada $quoted_names con $names intacto.

A continuación se muestra un ejemplo relativamente completo:

location /foo {
    array_split ',' $arg_names to=$names;
    array_map_op set_quote_sql_str $names;
    array_join '+' $names to=$res;
    echo $res;
}

Entonces, la solicitud GET /foo?names=bob,marry,nomas producirá el cuerpo de respuesta

'bob'+'marry'+'nomas'

Bastante genial, ¿verdad?

Aquí asumimos que instalarías nginx bajo /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 ```

Descarga la última versión del archivo tarball de este módulo desde array-var-nginx-module file list, y el último tarball para ngx_devel_kit desde su file list.

Además, este módulo está incluido y habilitado por defecto en el OpenResty bundle.

Ver También

GitHub

Puedes encontrar consejos adicionales de configuración y documentación para este módulo en el repositorio de GitHub para nginx-module-array-var.