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

Depuis l'introduction du module JavaScript NGINX (njs) dans2015 (sous son nom d'origine, nginScript) et en le rendant généralement disponible en 2017<.htmla>, nous avons régulièrement continué à ajouter de nouvelles fonctionnalités et à affiner notre implémentation à travers des dizaines de mises à jour de version . Normalement, nous attendons une sortie de NGINX Plus pour discuter des fonctionnalités d'une nouvelle version NGINX JavaScript, mais nous sommes tellement enthousiasmés par la version 0.7.7 que cette fois, nous avons hâte !

Les améliorations significatives de njs 0.7.7 contribuent à rendre votre configuration NGINX encore plus modulaire, organisée et réutilisable :

• Vous pouvez désormais déclarer le code njs dans les contextes où il s'applique plutôt que globalement, rapprochant ainsi votre code personnalisé du point d'utilisation.
• Les hooks dans le code njs lui-même vous permettent de modifier le comportement en fonction du contexte d'exécution .
• Le nouvel objet fs.FileHandle rend les opérations sur les fichiers plus efficaces .

Pour en savoir plus sur njs et consulter la liste des cas d'utilisation pour lesquels nous fournissons un exemple de code, lisez Exploiter la puissance et la commodité de JavaScript pour chaque requête avec le module JavaScript NGINX sur notre blog.

Pour une liste complète de toutes les nouvelles fonctionnalités et corrections de bogues dans njs 0.7.7, consultez la documentation des modifications .

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

Dans les versions précédentes de njs, vous deviez importer votre code JavaScript et déclarer les variables pertinentes (avec les directives js_import , js_path , js_set et js_var ) dans le contexte http ou stream de niveau supérieur, l'équivalent de la déclaration de variables globales en haut d'un fichier principal. Mais les directives qui invoquent réellement les fonctions et variables JavaScript apparaissent dans un contexte enfant – par exemple, avec la directive js_content dans un bloc HTTP location{} et la directive js_access dans un bloc Stream server{} . Cela crée deux problèmes :

1. Pour quelqu'un qui lit la configuration, les déclarations dans les contextes http et stream sont essentiellement du bruit, car il n'y a aucune indication où le code et les variables associés sont réellement utilisés.
2. Ce n’est pas évident dans le contexte enfant 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 lire des fichiers de configuration plus petits et spécifiques aux fonctions à partir des répertoires /etc/nginx/conf.d et /etc/nginx/stream.d , la configuration NGINX est flexible : vous pouvez inclure les blocs http{} et stream{} dans plusieurs fichiers. Cela peut être particulièrement problématique dans les environnements où plusieurs personnes travaillent sur votre configuration NGINX et ne suivent pas toujours les conventions établies.

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

• HTTP –

  • Ces directives peuvent apparaître dans les contextes de serveur et d'emplacement ainsi que dans le contexte http :

    • js_import
    • chemin_js
    • 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 du serveur ainsi que dans le contexte du flux :

  • js_import
  • chemin_js
  • js_set
  • js_var

Avoir toute la configuration njs pour un cas d'utilisation spécifique dans un seul fichier rend également votre code plus modulaire et portable.

À titre d'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 invoquée (ici, jscode_local.conf ).

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

Modification du comportement en fonction du contexte d'exécution

Plusieurs nouveautés de njs 0.7.7 vous permettent de modifier le comportement de votre code JavaScript en fonction du contexte (phase de traitement) où 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 gérées par les blocs location{} qui incluent la directive internal ). Vous pouvez utiliser l’indicateur r.internal pour dupliquer la logique lorsqu’un script utilise un gestionnaire d’événements général qui peut être appelé dans des contextes internes et non internes.

Les éléments suivants sont classés comme demandes 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 à partir d'un serveur en amont
• Les sous-requêtes invoquées par les directives auth_request et mirror , les directives du module ngx_http_addition_module ou la commande virtuelle d' inclusion côté serveur (SSI) (prise en charge par le module ngx_http_ssi_module )
• Demandes modifiées par la directive de réécriture

Méthode de flux s.send() améliorée

Dans les versions antérieures de njs, la méthode Stream s.send() dépend du contexte, car la direction dans laquelle elle envoie des données est déterminée par l'emplacement (en amont ou en aval) du rappel où la méthode est appelée. Cela fonctionne bien pour les rappels synchrones – pour lesquels s.send() a été conçu à l’origine – mais échoue avec les fonctions asynchrones telles que ngx.fetch() .

Dans njs 0.7.7 et versions ultérieures, la direction est stockée dans un indicateur interne séparé, que s.send() peut ensuite utiliser.

Opérations de fichiers plus efficaces avec le nouvel objet fs.FileHandle()

Le module du système de fichiers ( fs ) implémente des opérations sur les fichiers. Le nouvel objet FileHandle dans le module fs est un wrapper d'objet pour 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 être utilisé pour :

• Exécuter des fonctions telles que read() et write() sur le fichier
• Ouvrir un fichier et effectuer des lectures et des écritures à un emplacement spécifié 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 pour chaque propriété, consultez la documentation ) :

• descripteur de fichier.fd
• handle de fichier.read()
• filehandle.stat()
• handle de fichier.write()
• handle de fichier.write()
• handle de fichier.close()

Ces méthodes ont été mises à jour pour prendre en charge FileHandle (consultez la documentation liée pour plus d'informations sur les arguments de chaque méthode) :

• fs.openSync()
• fs.promises.open()
• fs.fstatSync()
• fs.readSync()
• fs.writeSync() (tampon)
• fs.writeSync() (chaîne)

Utilisez njs pour améliorer votre configuration

Avec njs 0.7.7, nous avons facilité le travail et le partage du code njs pour vos équipes. Les contextes étendus des directives njs rendent encore plus simple l’amélioration de la configuration NGINX avec du code JavaScript personnalisé. Vous pouvez faire le premier pas vers une passerelle API, un proxy inverse ou un serveur Web, et ce, de manière plus qu’un simple middleware ou composant de périphérie. Vous pouvez l’intégrer à votre application via JavaScript, TypeScript ou des modules Node tiers sans ajouter un autre composant dans votre pile. Tout ce dont vous avez besoin c'est NGINX !

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