Haga que su configuración NGINX sea aún más modular y reutilizable con njs 0.7.7

Desde la introducción del módulo JavaScript de NGINX (njs) en2015 (bajo su nombre original, nginScript) y poniéndolo a disposición del público en 2017<.htmla>, hemos continuado agregando nuevas funciones y refinando nuestra implementación a lo largo de docenas de actualizaciones de versiones . Normalmente esperamos un lanzamiento de NGINX Plus para discutir las características de una nueva versión de NGINX JavaScript, ¡pero estamos tan entusiasmados con la versión 0.7.7 que esta vez no podemos esperar!

Las mejoras significativas en njs 0.7.7 ayudan a que su configuración de NGINX sea aún más modular, organizada y reutilizable:

• Ahora puede declarar el código njs en los contextos donde se aplica en lugar de hacerlo globalmente, acercando su código personalizado al punto de uso.
• Los ganchos en el propio código njs le permiten modificar el comportamiento dependiendo del contexto de ejecución .
• El nuevo objeto fs.FileHandle hace que las operaciones con archivos sean más eficientes .

Para obtener más información sobre njs y revisar la lista de casos de uso para los que proporcionamos código de muestra, lea Cómo aprovechar el poder y la conveniencia de JavaScript para cada solicitud con el módulo JavaScript de NGINX en nuestro blog.

Para obtener una lista completa de todas las nuevas características y correcciones de errores en njs 0.7.7, consulte la documentación de Cambios .

Declaración de código JavaScript y variables en contextos locales

En versiones anteriores de njs, debes importar tu código JavaScript y declarar las variables relevantes (con las directivas js_import , js_path , js_set y js_var ) en el contexto http o de flujo de nivel superior, el equivalente a declarar variables globales en la parte superior de un archivo principal. Pero las directivas que realmente invocan las funciones y variables de JavaScript aparecen en un contexto secundario; por ejemplo, con la directiva js_content en un bloque HTTP location{} y la directiva js_access en un bloque Stream server{} . Esto crea dos problemas:

1. Para alguien que lee la configuración, las declaraciones en los contextos http y stream son esencialmente ruido, porque no hay ninguna indicación de dónde se utilizan realmente el código y las variables asociadas.
2. No es obvio en el contexto secundario dónde se importaron y declararon el código y las variables. Si bien recomendamos incluir los bloques http{} y stream{} solo en el archivo de configuración principal ( nginx.conf ) y usar la directiva include para leer archivos de configuración más pequeños y específicos de funciones desde los directorios /etc/nginx/conf.d y /etc/nginx/stream.d , la configuración de NGINX es flexible: puede incluir bloques http{} y stream{} en varios archivos. Esto puede ser especialmente problemático en entornos donde varias personas trabajan en su configuración NGINX y es posible que no siempre sigan las convenciones establecidas.

En njs 0.7.7 y versiones posteriores, puedes importar código y declarar variables en los contextos donde se utilizan:

• HTTP –

  • Estas directivas pueden aparecer en los contextos de servidor y ubicación , así como en el contexto http :

    • js_import
    • ruta_js
    • conjunto js
    • variable_js

  • Estas directivas pueden aparecer tanto en el contexto if como en los contextos location y limit_except :

    • filtro js_body
    • contenido js
    • filtro de encabezado js

• Transmisión : estas directivas pueden aparecer tanto en el contexto del servidor como en el contexto de la transmisión :

  • js_import
  • ruta_js
  • conjunto js
  • variable_js

Tener toda la configuración de njs para un caso de uso específico en un solo archivo también hace que su código sea más modular y portátil.

A modo de ejemplo, en versiones anteriores de njs, cuando agregabas un nuevo script, tenías que cambiar tanto nginx.conf (agregando js_import y posiblemente js_path , js_set y js_var ) como el archivo donde se invoca la función JavaScript (aquí, jscode_local.conf ).

En njs 0.7.7 y versiones posteriores, toda la configuración relacionada con la función util está en un solo archivo, jscode_integrated.conf :

Modificar el comportamiento según el contexto de ejecución

Varias características nuevas en njs 0.7.7 le permiten modificar el comportamiento de su código JavaScript dependiendo del contexto (fase de procesamiento) donde se esté ejecutando.

La propiedad HTTP r.internal

La propiedad HTTP r.internal es un indicador booleano establecido como “verdadero” para solicitudes internas (que son manejadas por bloques location{} que incluyen la directiva internal ). Puede utilizar el indicador r.internal para bifurcar la lógica cuando un script utiliza un controlador de eventos general que puede llamarse en contextos internos y no internos.

Se clasifican como solicitudes internas las siguientes:

• Solicitudes redirigidas por las directivas error_page , index , random_index y try_files
• Solicitudes redirigidas por el encabezado de respuesta X-Accel-Redirect desde un servidor ascendente
• Subsolicitudes invocadas por las directivas auth_request y mirror , las directivas en el módulo ngx_http_addition_module o el comando virtual de inclusión del lado del servidor (SSI) (compatible con el módulo ngx_http_ssi_module )
• Solicitudes modificadas por la directiva de reescritura

Método de transmisión s.send() mejorado

En versiones anteriores de njs, el método s.send() de Stream depende del contexto, porque la dirección en la que envía datos está determinada por la ubicación (ascendente o descendente) de la devolución de llamada donde se llama al método. Esto funciona bien para devoluciones de llamadas sincrónicas (para las cuales se diseñó originalmente s.send()) , pero falla con funciones asincrónicas como ngx.fetch() .

En njs 0.7.7 y versiones posteriores, la dirección se almacena en un indicador interno separado, que luego s.send() puede usar.

Operaciones de archivos más eficientes con el nuevo objeto fs.FileHandle()

El módulo del sistema de archivos ( fs ) implementa operaciones en archivos. El nuevo objeto FileHandle en el módulo fs es un contenedor de objetos para un descriptor de archivo numérico. Las instancias del objeto FileHandle se crean mediante el método fs.promises.open() .

Utilice el objeto FileHandle para obtener un descriptor de archivo, que puede utilizarse además para:

• Realizar funciones como read() y write() en el archivo
• Abrir un archivo y realizar lecturas y escrituras en una ubicación específica sin leer el archivo completo

Se han implementado las siguientes propiedades de FileHandle (para obtener información sobre los argumentos obligatorios y opcionales para cada propiedad, consulte la documentación ):

• manejadordearchivo.fd
• manejadordearchivo.read()
• manejador de archivo.stat()
• manejadordearchivo.write()
• manejadordearchivo.write()
• manejador de archivo.close()

Estos métodos se han actualizado para admitir FileHandle (consulte la documentación vinculada para obtener información sobre los argumentos de cada método):

• fs.openSync()
• fs.promesas.abrir()
• fs.fstatSync()
• fs.readSync()
• fs.writeSync() (búfer)
• fs.writeSync() (cadena)

Utilice njs para mejorar su configuración

Con njs 0.7.7, hemos facilitado que sus equipos trabajen y compartan código njs. Los contextos extendidos para las directivas njs hacen que sea aún más sencillo mejorar la configuración de NGINX con código JavaScript personalizado. Puede dar el primer paso hacia una puerta de enlace API, un proxy inverso o un servidor web, que sea más que simplemente otro middleware o componente de borde. Puede hacerlo parte de su aplicação a través de JavaScript, TypeScript o módulos de nodo de terceros sin agregar otro componente a su pila. ¡Todo lo que necesitas es NGINX!

¿Tiene preguntas?Únase al Slack de la comunidad NGINX y consulte el canal #njs-code-review para obtener más información, hacer preguntas y recibir comentarios sobre su código njs.