Rendez votre configuration NGINX encore plus modulaire et réutilisable avec njs 0.7.7

Prabhat Dixit

Depuis le lancement du module JavaScript de NGINX (njs) en 2015 (initialement appelé nginScript) et sa mise à disposition générale en 2017<.htmla>, nous n’avons cessé d’ajouter de nouvelles fonctionnalités et d’améliorer notre implémentation au fil de dizaines de mises à jour de version. Habituellement, nous attendons la sortie d’une version de NGINX Plus pour présenter les fonctionnalités d’une nouvelle version de NGINX JavaScript, mais la version 0.7.7 nous enthousiasme tellement que, cette fois-ci, nous ne pouvons pas attendre !

Les améliorations majeures apportées à njs 0.7.7 contribuent à rendre votre configuration NGINX encore plus modulaire, structurée et réutilisable :

• Vous pouvez désormais déclarer le code njs dans les contextes où il s’applique plutôt que globalement, afin de rapprocher votre code personnalisé de son point d’utilisation.
• Les hooks intégrés au code njs vous permettent de modifier le comportement en fonction du contexte d’exécution.
• Le nouvel objet « fs.FileHandle » améliore l’efficacité des opérations sur les fichiers.

Pour en savoir plus sur njs et consulter la liste des cas d’utilisation pour lesquels nous proposons des exemples de code, lisez « Exploiter la puissance et la simplicité de JavaScript pour chaque requête avec le module JavaScript de NGINX » sur notre blog.

Pour obtenir la liste complète des nouvelles fonctionnalités et des corrections de bogues de njs 0.7.7, consultez la documentation relative aux modifications.

Déclaration de code JavaScript et de variables dans des contextes locaux

Dans les versions précédentes de njs, vous devez importer votre code JavaScript et déclarer les variables concernées – à l’aide des directives « js_import », « js_path », « js_set » et « js_var » – dans le contexte de niveau supérieur « http » ou « stream », ce qui revient à déclarer des variables globales au début d’un fichier principal. Cependant, les directives qui appellent effectivement les fonctions et variables JavaScript figurent dans un contexte enfant – par exemple, la directive « js_content » dans un bloc HTTP « location{} » et la directive « js_access » dans un bloc Stream « server{} ». Cela pose deux problèmes :

1. Pour une personne qui parcourt la configuration, les déclarations dans les contextes http et stream constituent essentiellement du bruit, car rien n’indique où le code et les variables associés sont réellement utilisés.
2. Dans le contexte enfant, il n’est pas évident de savoir où le code et les variables ont été importés et déclarés. Bien que nous recommandions d’inclure les blocs http{} et stream{} uniquement dans le fichier de configuration principal (nginx.conf) et d’utiliser la directive include pour charger des fichiers de configuration plus petits et propres à chaque fonction depuis les répertoires /etc/nginx/conf.d et /etc/nginx/stream.d, la configuration de NGINX est flexible : vous pouvez inclure des blocs http{} et stream{} dans plusieurs fichiers. Cela peut s’avérer particulièrement problématique dans les environnements où plusieurs personnes travaillent sur votre configuration NGINX et ne respectent pas toujours les conventions établies.

Dans njs 0.7.7 et les versions ultérieures, vous pouvez importer du code et déclarer des variables dans les contextes où ils sont utilisés :

• HTTP –
  • Ces directives peuvent apparaître dans les contextes server et location, ainsi que dans le contexte http :
    • js_import
    • js_path
    • js_set
    • js_var
  • Ces directives peuvent apparaître dans le contexte if, ainsi que dans les contextes location et limit_except :
    • js_body_filter
    • js_content
    • js_header_filter
• Stream – Ces directives peuvent apparaître dans le contexte server ainsi que dans le contexte stream :
  • js_import
  • js_path
  • js_set
  • js_var

Le fait de regrouper toute la configuration njs correspondant à un cas d’usage spécifique dans un seul fichier rend également votre code plus modulaire et portable.

Par exemple, dans les versions précédentes de njs, lorsque vous ajoutiez un nouveau script, vous deviez modifier à la fois nginx.conf (en ajoutant js_import et éventuellement js_path, js_set et js_var) et le fichier dans lequel la fonction JavaScript est appelée (ici, jscode_local.conf).

Chargement de l’exemple de code…

Chargement de l’exemple de code…

Dans njs 0.7.7 et les versions ultérieures, toute la configuration relative à la fonction util se trouve dans un seul fichier, « jscode_integrated.conf » :

Chargement de l’exemple de code…

Modifier le comportement en fonction du contexte d’exécution

Plusieurs nouvelles fonctionnalités de njs 0.7.7 vous permettent de modifier le comportement de votre code JavaScript en fonction du contexte (phase de traitement) dans lequel il s’exécute.

La propriété HTTP « r.internal »

La propriété HTTP « r.internal » est un indicateur booléen défini sur « true » pour les requêtes internes (qui sont traitées par des blocs location{} incluant la directive « internal »). Vous pouvez utiliser l’indicateur r.internal pour adapter la logique lorsqu’un script utilise un gestionnaire d’événements générique pouvant être appelé aussi bien dans des contextes internes que non internes.

Les requêtes suivantes sont considérées comme des requêtes internes :

• Requêtes redirigées par les directives « error_page », « index », « random_index » et « try_files »
• Requêtes redirigées par l’en-tête de réponse X-Accel-Redirect provenant d’un serveur en amont
• Sous-requêtes appelées par les directives « auth_request » et « mirror », par les directives du module ngx_http_addition_module, ou par la commande Server Side Include (SSI) « include virtual » (prise en charge par le module ngx_http_ssi_module)
• Requêtes modifiées par la directive « rewrite »

Amélioration de la méthode de flux « s.send() »

Dans les versions antérieures de njs, la méthode Stream s.send() dépend du contexte, car le sens dans lequel elle envoie les données est déterminé par l’emplacement (en amont ou en aval) de la fonction de rappel dans laquelle la méthode est appelée. Cela fonctionne correctement avec les fonctions de rappel synchrones – pour lesquelles s.send() a été conçue à l’origine –, mais échoue avec les fonctions asynchrones telles que ngx.fetch().

À partir de njs 0.7.7, la direction est stockée dans un indicateur interne distinct, que s.send() peut ensuite utiliser.

Des opérations sur les fichiers plus efficaces grâce au nouvel objet « fs.FileHandle() »

Le module de système de fichiers (fs) permet d’effectuer des opérations sur les fichiers. Le nouvel objet FileHandle du module fs encapsule un descripteur de fichier numérique. Les instances de l’objet FileHandle sont créées par la méthode fs.promises.open().

Utilisez l’objet « FileHandle » pour obtenir un descripteur de fichier, qui peut ensuite servir à :

• Effectuer des opérations telles que read() et write() sur le fichier
• Ouvrir un fichier et effectuer des opérations de lecture et d’écriture à un emplacement précis sans lire l’intégralité du fichier

Les propriétés suivantes de FileHandle ont été implémentées (pour plus d’informations sur les arguments obligatoires et facultatifs de chaque propriété, consultez la documentation ):

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

Ces méthodes ont été mises à jour pour prendre en charge FileHandle (consultez la documentation correspondante pour en savoir plus sur les arguments de chaque méthode) :

• fs.openSync()
• fs.promises.open()
• fs.fstatSync()
• fs.readSync()
• fs.writeSync() (tampon)
• fs.writeSync() (chaîne de caractères)

Utilisez njs pour améliorer votre configuration

Avec njs 0.7.7, nous avons facilité le travail de vos équipes sur le code njs ainsi que son partage. Grâce à l’extension des contextes pris en charge par les directives njs, il est encore plus simple d’enrichir la configuration de NGINX avec du code JavaScript personnalisé. Vous pouvez ainsi faire un premier pas vers la création d’une passerelle API, d’un proxy inverse ou d’un serveur web qui ne soit pas un simple middleware ou composant périphérique de plus. Vous pouvez l’intégrer à votre application à l’aide de JavaScript, TypeScript ou de modules Node tiers, sans ajouter de composant supplémentaire à votre pile. Tout ce dont vous avez besoin, c’est de NGINX !

Vous avez des questions ? Rejoignez le Slack de la communauté NGINX et consultez le canal #njs-code-review pour en savoir plus, poser vos questions et obtenir des retours sur votre code njs.

À propos de l’auteur

Prabhat Dixit

Autres articles de Prabhat Dixit