Haz que tu configuración de NGINX sea aún más modular y reutilizable con njs 0.7.7

Prabhat Dixit

Desde que presentamos el módulo JavaScript de NGINX (njs) en 2015 (con su nombre original, nginScript) y lo pusimos a disposición general en 2017<.htmla>, hemos seguido incorporando nuevas funciones y perfeccionando nuestra implementación a lo largo de decenas de actualizaciones de versión. Normalmente esperamos al lanzamiento de una versión de NGINX Plus para hablar de las funciones de una nueva versión de NGINX JavaScript, pero la versión 0.7.7 nos entusiasma tanto que esta vez no podemos esperar.

Las importantes mejoras de njs 0.7.7 permiten que la configuración de NGINX sea aún más modular, organizada y reutilizable:

• Ahora puede declarar código njs en los contextos en los que se aplica en lugar de hacerlo globalmente, acercando así su código personalizado al punto de uso.
• Los hooks del propio código njs permiten modificar el comportamiento en función 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 consultar la lista de casos de uso para los que proporcionamos código de ejemplo, lea Cómo aprovechar la potencia y la comodidad de JavaScript para cada solicitud con el módulo JavaScript de NGINX en nuestro blog.

Para consultar una lista completa de todas las funciones nuevas y correcciones de errores de njs 0.7.7, consulte la documentación de Cambios.

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

En versiones anteriores de njs, había que importar el código JavaScript y declarar las variables pertinentes —mediante las directivas js_import, js_path, js_set y js_var— en el contexto de nivel superior http o stream, lo que equivale a declarar variables globales al principio de un archivo principal. Sin embargo, las directivas que realmente invocan las funciones y variables de JavaScript aparecen en un contexto secundario; por ejemplo, la directiva js_content en un bloque location{} de HTTP y la directiva js_access en un bloque server{} de Stream. Esto plantea dos problemas:

1. Para quien revise la configuración, las declaraciones de los contextos http y stream son básicamente ruido, ya que no se indica dónde se utilizan realmente el código y las variables asociados.
2. En el contexto secundario, no resulta evidente dónde se han importado y declarado el código y las variables. Aunque recomendamos incluir los bloques http{} y stream{} únicamente en el archivo de configuración principal (nginx.conf) y utilizar la directiva include para cargar archivos de configuración más pequeños y específicos para cada función 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 resultar especialmente problemático en entornos donde varias personas trabajan en la configuración de NGINX y no siempre siguen las convenciones establecidas.

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

• HTTP –
  • Estas directivas pueden aparecer en los contextos server y location, así como en el contexto http:
    • js_import
    • js_path
    • js_set
    • js_var
  • Estas directivas pueden aparecer en el contexto if, así como en los contextos location y limit_except:
    • js_body_filter
    • js_content
    • js_header_filter
• Flujo – Estas directivas pueden aparecer tanto en el contexto server como en el contexto stream:
  • js_import
  • js_path
  • js_set
  • js_var

Tener toda la configuración de njs para un caso de uso específico en un único archivo también hace que el código sea más modular y portable.

Por ejemplo, en versiones anteriores de njs, al añadir un nuevo script había que modificar tanto nginx.conf (añadiendo js_import y, posiblemente, js_path, js_set y js_var) como el archivo en el que se invoca la función de JavaScript (en este caso, jscode_local.conf).

Cargando ejemplo de código…

Cargando ejemplo de código…

En njs 0.7.7 y versiones posteriores, toda la configuración relacionada con la función util se encuentra en un único archivo, jscode_integrated.conf:

Cargando ejemplo de código…

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

Varias funciones nuevas de njs 0.7.7 permiten modificar el comportamiento del código JavaScript en función del contexto (fase de procesamiento) en el que se ejecuta.

La propiedad HTTP «r.internal»

La propiedad HTTP r.internal es un indicador booleano establecido en «true» para las solicitudes internas (que son gestionadas 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 genérico que puede invocarse tanto en contextos internos como no internos.

Las siguientes se clasifican como solicitudes internas:

• Solicitudes redirigidas por las directivas error_page, index, random_index y try_files directives
• Solicitudes redirigidas por la cabecera de respuesta X-Accel-Redirect de un servidor ascendente
• Subsolicitudes invocadas por las directivas auth_request y mirror, las directivas del módulo ngx_http_addition_module, o el comando include virtual de Server Side Include (SSI) (compatible con el módulo ngx_http_ssi_module)
• Solicitudes modificadas por la directiva «rewrite»

Método mejorado de flujo s.send() Stream Method

En versiones anteriores de njs, el método s.send() de Stream depende del contexto, ya que la dirección en la que envía los datos viene determinada por la ubicación (ascendente o descendente) de la función de retorno en la que se llama al método. Esto funciona correctamente con las funciones de retorno síncronas, para las que se diseñó originalmente s.send(), pero falla con funciones asíncronas como ngx.fetch().

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

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

El módulo del sistema de archivos (fs) implementa operaciones con archivos. El nuevo objeto FileHandle del módulo fs encapsula un descriptor numérico de archivo. 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 posteriormente para:

• Ejecutar funciones como read() y write() en el archivo
• Abrir un archivo y realizar operaciones de lectura y escritura 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 de cada propiedad, consulte la documentación):

• filehandle.fd
• filehandle.read()
• filehandle.stat()
• filehandle.write()
• filehandle.write()
• filehandle.close()

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

• fs.openSync()
• fs.promises.open()
• fs.fstatSync()
• fs.readSync()
• fs.writeSync() (búfer)
• fs.writeSync() (cadena)

Usa njs para mejorar tu configuración

Con njs 0.7.7, hemos facilitado que sus equipos trabajen con código njs y lo compartan. Los contextos ampliados para las directivas de njs hacen que mejorar la configuración de NGINX con código JavaScript personalizado sea aún más sencillo. Puede dar el primer paso hacia una puerta de enlace de API, un proxy inverso o un servidor web que sea mucho más que otro middleware o componente perimetral. Puede integrarlo en su aplicación mediante JavaScript, TypeScript o módulos de Node de terceros sin añadir otro componente a su pila. ¡Solo necesita NGINX!

¿Tienes alguna pregunta? Únete al Slack de la comunidad de NGINX y visita el canal #njs-code-review para obtener más información, plantear tus dudas y recibir comentarios sobre tu código njs.

Sobre el autor

Prabhat Dixit

Más artículos de Prabhat Dixit