@villedemontreal/scripting

Librairie pour la création et utilisation de scripts dans un projet Node.js

Cette librairie, basée sur Caporal, offre une manière standardisée de créer et de lancer des scripts localement dans un projet d'API ou dans une librairie utilisant Node.js.

Les scripts sont développés en Typescript, ce qui vous permet d'utiliser des librairies npm, de déboguer avec breakpoints, etc.

Un ensemble de scripts core sont fournis et sont disponibles automatiquement. Vous ajoutez dans votre projet les scripts supplémentaires dont vous avez besoin.

Une aide est automatiquement créée (et affichable) pour les scripts et leurs options sont automatiquement validées au runtime.

Notez que cette librairie est conçue pour ne fonctionner que lorsque les dépendances dev sont disponibles! Ce que cela signifie, c'est que dans vos Dockerfile, lorsque seules les dépendances production sont disponibles, vous devrez lancer node src/start pour démarrer l'application et non utiliser le script start! De lancer ./run start ne fonctionnerait pas car des dépendances dev manqueraient.

Ceci apporte le bénéfice à votre application nodejs de recevoir les signaux émis par Kubernetes quand il s'apprête à fermer un conteneur (SIGTERM), ce qui permet à l'application de faire du cleanup avant de mourir (Voir pod-lifecycle/pod-termination)

Utilisation de la librairie

Installation

Il faut créer deux fichiers à la racine du projet:

• run.cmd contenant:

@echo off
node "%~dp0\run" %*

• run contenant:

#!/usr/bin/env node
const caporal = require("@villedemontreal/caporal").program;

// Here, you could add custom global options, or tweak
// the Caporal instance, if required.

// Then it is run:
require(`${__dirname}/node_modules/@villedemontreal/scripting/dist/src/run`).run(
  {
    caporal,
    projectRoot: __dirname,
    scriptsIndexModule: `./scripts/index`,
  }
);

Note: si vous êtes sur Linux/Mac, vous devrez aussi lancer chmod +x run pour rendre exécutable le fichier ./run.

Configurations

Il est possible de configurer certains aspects de la librairie dans le fichier run du projet.

• Une fois l'instance de caporal obtenue (const caporal), vous pouvez la configurer. Par exemple, il est possible d'y ajouter des options globales customs avec caporal.option(...).Mais, en règle général, vous ne devriez pas avoir à configurer cette instance directement.

• scriptsIndexModule : qui est le chemin vers l'index (le fichier Typescript) exportant les scripts custom de votre projet. Dans un projet d'API, ce chemin ne devrait probablement pas être changé. Notez que si votre projet ne définie pas de scripts custom, vous pouvez complètement enlever ce paramètre ou encore le mettre à null.

Lancer un script

Un script se lance en ligne de commande avec:

• Windows : > run [scriptName] [options]
• Linux/Mac: > ./run [scriptName] [options]

Par exemple:

> run test --jenkins

Obtenir de l'aide sur les scripts

• Pour obtenir la liste complète des scripts disponibles et leurs options, lancez: > run
  ou
  > run help

• Pour obtenir de l'aide sur un script en particulier, lancez: > run [scriptName] --help
  ou
  > run help [scriptName]

Lancez un script en utilisant les configurations de tests

Un script dont le nom:

• est "test"
• est "validate"
• débute par "test-"
• débute par "testing:"

sera exécuté avec la variable d'environnement NODE_APP_INSTANCE automatiquement mise à tests. Ceci fera en sorte que les configurations -tests seront utilisées.

Autrement, vous pouvez spécifier l'option globale --testing pour forcer cette valeur.

Ajouter un script dans votre projet

Un script sera ajouté en général ajouté sous un répetoire "scripts" racine. Notez que vous pouvez créer plusieurs niveaux de sous-répertoires.

Vous devez exporter un nouveau script dans l'index de vos scripts (scripts/index.ts).

• Un Script doit au minimum implémenter 3 méthodes:

  • name(): le nom du script
  • description(): une description pour le script
  • main(): contenant le code du script

• Si votre script demande plus de configurations qu'un nom et description, vous pouvez également implémenter configure().

• La classe de base fournit également un logger vous permettant d'afficher des messages en respectant le niveau demandé par les arguments --silent, --quiet et --verbose pouvant être passés lors d'une commande.

Si une erreur survient dans votre script, lancez simplement une erreur régulière (throw new Error(...)).

Note: référez-vous aux scripts core fournis par cette librairie sous scripts/testing comme exemples!

Ajouter des options à un script

Pour ajouter des options ou des arguments à vos scripts:

• Vous overridez la méthode configure(command) et vous utilisez l'object command fourni pour ajouter les options. Par exemple:

protected async configure(command: Command): Promise<void> {
  command.option(`-p, --port <number>`, `A port number`, {
    validator: caporal.NUMBER
  });
}

• Vous créez une interface Options au dessus de la classe de votre script et définissez les options dans cette interface. Par exemple:

export interface Options {
  port?: number;
}

• Vous paramétrisez la classe de base ScriptBase avec cette interface, comme premier argument. Par exemple:

export class MyScript extends ScriptBase<Options> {
  // "this.options.port" est maintenant disponible de manière typée.
}

Ajouter une option globale

Cette fonctionnalité ne devrait pas souvent être requise, mais il est possible d'ajouter une option globale, en plus de celles qui sont ajoutées automatiquement par la librairie.

Pour se faire, vous

• Éditez le fichier run de votre projet pour ajouter l'option globale à l'instance caporal. Par exemple:

caporal.option("--custom", "Custom global option", {
  global: true,
});

• Créez dans votre projet une interface héritant de IGlobalOptions. Par exemple:

export interface IAppGlobalOptions extends IGlobalOptions {
  something?: boolean;
}

• Dans vos scripts, vous paramétrisez la classe de base ScriptBase avec cette interface, comme deuxième argument. Par exemple:

export class MyScript extends ScriptBase<Options, IAppGlobalOptions> {
  // "this.options.something" est maintenant disponible de manière typée.
}

Invoquer un script dans un script

Dans un script, il est possible d'en appeller un (ou plusieurs) autre en utilisant la méthode this.invokeScript(...). Vous passez à cette méthode la classe du script à appeler ainsi que les options et arguments à utiliser.

Notez que les options globales seront automatiquement disponibles par le script appellé! Vous ne les spécifiez que si vous avez besoin d'en changer la valeur.

Lancer une commande shell dans un script

Un utilitaire fourni this.invokeShellCommand(...) permet de lancer une commande shell dans un script. Par exemple:

await this.invokeShellCommand("node", ["some/js/module", "--somearg"]);

Le troisième paramètre est un objet options. Une de ces options est useTestsNodeAppInstance que vous pouvez mettre à true pour lancer le nouveau process avec une variable d'environnement "NODE_APP_INSTANCE" égale à "tests" et d'ainsi faire en sorte que les configurations de tests soient utilisées si du code de l'API est exécuté dans le process.

Ajouter un script en mode "testing"

Pour vos tests, il est possible de spécifier un script, mais en faisant en sorte qu'il ne soit disponible que lorsque vos tests roulent. Pour ce faire, vous devez préfixer le nom du script par TESTING_SCRIPT_NAME_PREFIX qui est une constante exportée par le fichier src/scriptBase.ts de la librairie. Par exemple:

get name(): string {
  return `${TESTING_SCRIPT_NAME_PREFIX}myTestScript`;
}

Script non listé

Pour éviter qu'un script ne se retrouve dans la documentation globale générée par Caporal, vous pouvez appeller command.hide();, dans la méthode configure() overridée:

protected async configure(command: Command): Promise<void> {
  command.hide();
  // ...
}

Scripts npm

Si désiré, vous pouvez aussi déclarer vos scripts dans le fichier package.json de votre projet. Ces scripts npm ne seront que des indirections vers le fichier run bootstrappant la librairie de scripting, en utilisant node. Par exemple:

"scripts": {
  "test": "node run test",
  // ...
}

Notez que si vous utilisez npm pour lancer un script, et que vous avez à passer des options, il vous faudra ajouter l'argument spécial "--" avant les options. Par exemple:

> npm run test -- --nc

Ceci est passablement plus verbeux que la méthode utilisant run directement:

run test --nc

Développement de la librairie

Lintage

Utilisez un éditeur (VSCode a été testé) avec ces extensions installées:

• ESLint
• Prettier

Launch configurations

Ces "launch configurations" sont founies pour développer la librairie dans VSCode :

• "Debug script" - Lance un script en mode debug. Vous pouvez mettre des breakpoints et ils seront respectés. Pour changer le script exécuté, vous devez modifier la ligne appropriée dans le fichier ".vscode/launch.json".

• "Debug all tests" - Lance tous les tests en mode debug. Vous pouvez mettre des breakpoints et ils seront respectés.

• "Debug current test file" - Lance en mode debug le fichier de tests présentement ouvert dans VSCode. Vous pouvez mettre des breakpoints et ils seront respectés.

• "Debug current tests file - fast" - Lance en mode debug le fichier de tests présentement ouvert dans VSCode. Aucune compilation n'est effectuée au préalable. Cette launch configuration doit être utilisée lorsque la compilation incrémentale roule (en lançant au préalable run watch dans un terminal).

Test et publication de la librairie sur Nexus

En mergant une pull request dans la branche develop, un artifact "-pre.build" sera créé automatiquement dans Nexus. Vous pouvez utiliser cette version temporaire de la librairie pour bien la tester dans un réel projet.

Une fois mergée dans master, la librairie est définitiement publiée dans Nexus, en utilisant la version spécifiée dans le package.json.

Artifact Nexus privé, lors du développement

Lors du développement d'une nouvelle fonctionnalité, sur une branche feature, il peut parfois être utile de déployer une version temporaire de la librairie dans Nexus. Ceci permet de bien tester l'utilisation de la librairie modifiée dans un vrai projet, ou même dans une autre librairie elle-même par la suite utilisée dans un vrai projet.

Si le code à tester est terminé et prêt à être mis en commun avec d'autres développeurs, la solution de base, comme spécifiée à la section précédante, est de merger sur develop: ceci créera automatiquement un artifact "-pre-build" dans Nexus. Cependant, si le code est encore en développement et vous désirez éviter de polluer la branche commune develop avec du code temporaire, il y a une solution permettant de générer un artifact "[votre prénom]-pre-build" temporaire dans Nexus, à partir d'une branche feature directement:

• Checkoutez votre branche feature dans une branche nommée "nexus". Ce nom est important et correspond à une entrée dans le Jenkinsfile.
• Une fois sur la branche nexus, ajoutez un suffixe "-[votre prénom]" à la version dans le package.json, par exemple: "5.15.0-roger". Ceci permet d'éviter tout conflit dans Nexus et exprime clairement qu'il s'agit d'une version temporaire pour votre développement privé.
• Commitez et poussez la branche nexus.
• Une fois le build Jenkins terminé, un artifact pour votre version aura été déployé dans Nexus.

Notez que, lors du développement dans une branche feature, l'utilisation d'un simple npm link local peut souvent être suffisant! Mais cette solution a ses limites, par exemple si vous désirez tester la librairie modifiée dans un container Docker.

Aide / Contributions

Pour obtenir de l'aide avec ce gabarit, vous pouvez poster sur la salle Google Chat dev-discussions.

Notez que les contributions sous forme de pull requests sont bienvenues.