Packager son projet

• Dans l'écosystème NodeJS* on utilise une foule de librairies spécialisées
• Une librairie répond généralement à une problématique simple
• Votre application utilisera des librairies, et en sera peut-être une elle-même
• package = modules + dépendances + tests
• NPM vous aide à packager et distribuer votre projet

Exemples de structure

• Librairie ou executable en ligne de commandes :

  lib/            # votre code (aussi libs)
  node_modules/   # les dépendances gérées par NPM
  test/           # le code de vos tests
  .npmignore      # les exclusions du package
  README.md
  package.json
  

• Application Web serveur & client :

  app/            # code serveur uniquement
    tests/
  assets/         # Les assets coté serveur
  config/         # les fichiers de configuration (aussi conf)
  node_modules/   # les dépendances serveur gérées par NPM
  public/         # code client
    dist/         # le client minifié
    test/
    vendor/       # dépendances client, gérées par bower/webpack... (aussi libs)
  package.json
  

Le fichier package.json

• Descripteur du projet

  {
    "name": "nom-du-projet",
    "version": "0.3.1",
    "description": "Elle sera publiée",,
    "author": "You ",
    "license": "MIT",
    "repository": "https://github.com/you/nom-du-projet.git",
    "dependencies": {
      "lodash": "~2.4.1"
    },
    "main": "./lib/entry_point.js",
    "bin": {
      "start-project": "./bin/start"
    },
    "scripts": {
      "test": "lab test"
    },
    "engines": {"node": ">=0.10.3"}
  }
  

Déclarer ses dépendances

• Dépendance = nom du package + containte de version
• x.y.z : exactement la version
• ^x.y.z : la version x la plus haute (y.z au minimum)
• l'url d'un dépôt git : git://github.com/user/project.git#commit
• l'url d'un tarball : http://bitbucket.org/user/repo?format=tar.gz
• Pour rester portable, n'utilisez que ces syntaxes

Publier sur le registry

• NPM est un dépôt en ligne, avec un site de recherche
• Peut héberger vos propres packages (publish)
• Le site affiche le README.md, les mot-clés, les stats de téléchargement, les dépendances...
• Le dépôt contient toutes les versions publiés
• Il est utilisé par défaut par le CLI (install, publish)

Le client NPM

• NPM vient avec une interface en ligne de commande
• Il lit le descripteur lors de certaines commandes :
  • npm install : récupération & compilation des dépendances, création des exécutables
  • npm test : lance l'exécution des tests présents
  • npm start/restart/stop : lance et arrête le projet
  • npm publish : publie le projet sur le registry central
• NPM !== build-system, NPM === gestion de dépendances

Lab : le test runner

• var assert = require('assert');
  var lab = exports.lab = require('lab').script();
  // describe est un fonction qui définit un "groupe" de tests
  lab.describe('Array#indexOf', function() {
  
    // it est une fonction qui définit un test
    lab.it('should return -1 when the value is not present', function(done){
      assert.equal(-1, [1,2,3].indexOf(5));
      assert.equal(-1, [1,2,3].indexOf(0));
      done(); // si une exception est levée avant done(), le test échoue
    });
  
    lab.it('should return index when the value is present', function(done){
      assert.equal(2, [1,2,3].indexOf(3));
      assert.equal(0, [1,2,3].indexOf(1));
      done(); // si done() est invoquée (sans erreur), le test est réussit
    });
  });

• En ligne de commande : lab test/array.js -v

Lab ou Mocha ?

• Fonctionnement général et fonctions similaires
• Mocha a pour principaux avantages :
  1. De fonctionner sur un navigateur
  2. D'être plus synthétique
  3. D'avoir plein de jolis reporters
• Lab a pour principaux avantages :
  1. D'exécuter un linter et une couverture de test
  2. D'utiliser les domaines pour récupérer les erreurs
  3. De pouvoir lancer les tests en parallèle

Chai : les assertions

• var lab = exports.lab = require('lab').script();
  // notez l'inclusion de chai
  var expect = require('chai').expect;
  
  lab.describe('Array#indexOf', function() {
    lab.it('should return -1 when the value is not present', function(done){
      var array = [1, 2, 3];
  
      // permet de faire la même chose...
      expect(array.indexOf(5)).to.equal(-1);
  
      //...et des assertions bien plus expressives !
      expect(array).to.be.an.instanceof(Array).and.to.have.a.lengthOf(3);
      expect(array).to.include(2);
      expect(array).not.to.contain(4);
      done();
    });
  });

• 3 styles possibles expect est le meilleur compromis

Les assertions disponibles

• égalité

  expect(x)/*not.*/.to./*deep.*/equals(y)

• existance

  expect(x).to.be.null

  expect(x).to.exist

• taille des tableaux

  expect(x).to.be.empty

  expect(x).to.have.length(y)

• objets

  expect(x).to.have./*deep.*/property('model.name').that.equals(z)

• contenu

  expect(x).to.contain/*.keys*/(y)

• nombres

  expect(x).to.be.at.least(y).and.at.most(z)

• fourre-tout

  expect(1).to.satisfy(function(num) {return num > 0;})

• exception

  expect(function(){}).to.throw(/message/)

expect(x).to.be.equal(y)

expect(x).to.be.true

expect(x).to.have.property(name, value)

hooks et exclusions

• A l'intérieur d'un describe() :

  lab.describe('Array', function() {
    var array = []
  
    lab.beforeEach(function(done) { // before(), after(), afterEach()
      array = [1, 2, 3];
      done();
    });
  
    lab.it('should splice() remove elements', {skip: true}, function(done){
      expect(array.splice(1, 1)).to.deep.equals([1, 3]);
      done();
    })
  })

• Exécutés quel que soit le résultat des it()
• only positionne skip sur les autres it du describe()

Tests en actions

1. Vous allez tester le module tp/fs/fs_utils.js. Dans tp/fs utilisez npm init pour générer un descripteur package.json
2. Toujours dans tp/fs, installez lab et chai: npm install --save-dev lab chai
3. Dans un module tp/fs/test/fs_utils.js réalisez les tests suivants :
   1. FS utils getDirContent should return current folder content with absolute paths
   2. FS utils getDirContent should fail when reading an unknown folder
   3. FS utils getDirStat should return alphabetically ordered current folder
   4. FS utils getDirStat should fail when reading an unknown folder
   avec une couverture de test de plus de 90%
4. Lancement avec lab -r html -o coverage.html pour voir la couverture

Request

• Fonctionne le plus simplement possible :

  var request = require('request');
  request('http://www.google.com', function (err, response, body) {
    if (!err && response.statusCode === 200) {
      console.log(body);
    }
  })

• Http ET Https
• Gère les proxy et les redirections
• Permet d'envoyer des formulaires

Configuration des requêtes

• 1er paramètre : une chaîne ou un object literal:

  request({
    url: 'http://www.google.com/search',
    method: 'GET',
    qs: {
      q: 'request'
    },
    proxy: 'http://proxy-internet.localnet:3128'
  }, function (err, response, body) {
    // ...
  })

• Méthode spécifiable avec request.get(), post() etc...
• Lit les variables d'envir. HTTP(S)/NO_PROXY
• Permet d'envoyer du json et des formulaires

Streaming et forumulaires

• request/request.get renvoient un ReadableStream:

  request('http://google.com/doodle.png').pipe(fs.createWriteStream('doodle.png'));

• Pour request.post/request.put, un WritableSteam:

  fs.createReadStream('file.json').pipe(request.put('http://mysite.com/obj.json'));

• Envoi d'un formulaire multipart/urlencoded:

  request.post('http://service.com/upload').form({key:'value'});

• Pour le multipart/form-data:

  request.post({url:'http://service.com/upload',
  formData: {
    field1: 'my_value',
    field3: fs.createReadStream('unicycle.jpg')
  }});

TODO mise en oeuvre request

• Surcharge de http.Server avec les améliorations :
  1. Routage des url par chemin et verbe HTTP
  2. Validation de la requête et outillage de la réponse
  3. Templating HTML
  4. Mécanisme de plugins
• Structure les développements du serveur
• Philosophie différente des middleware d'Express
• Projet initié par Walmart, maintenant communautaire

Anatomie du serveur

• var Hapi = require('hapi');
  var server = new Hapi.Server();
  server.connection({ port: 3000 });
  
  server.route({
    method: 'GET',
    path: '/hello/{user}',
    handler: function (request, reply) {
      reply('Hello ' + encodeURIComponent(request.params.user) + '!');
    }
  });
  
  server.start();

• Les routes peuvent contenir des paramètres
• request contient la requête parsée
• reply() est une factory pour constituer la réponse

Validation des paramètes

• Se repose sur le module externe Joi:

  var Joi = require('joi');
  
  server.route({
    method: 'GET',
    path: '/hello/{user}',
    handler: function (request, reply) {
      reply('Hello ' + encodeURIComponent(request.params.user) + '!');
    },
    config: {
      validate: { params: { user: Joi.string().min(3).max(10) } }
    }
  });

• Contrôle les paramètres de chemin (params), ceux de requête (query), les entêtes (headers) et le corps (payload)
• Réponses intelligibles avec un code de retour 400

Architecture de plugins

• Les plugins permettent de déporter vos routes
• Un plugin doit exporter une fonction register :

  exports.register = function(server, options, next) {
    // Manipulation du serveur: par exemple ajout de routes.
    // Lorsque les manipulations sont terminées, appel de next()
    next();
  };
  
  exports.register.attributes = {
    name: 'plugin-name',
    version: '1.0.0' // facultatif
  };

• Lors de son chargement, les routes d'un plugin pourront être préfixées

Les principaux plugins

• Les plugins se chargent dans le serveur:

  server.register([{
    register: require('myplugin'),
    options: {}
  }], function (err) {
    // plugins chargés
  });

• Logging des requêtes avec Good
• Websocket avec Hapi-io
• Authentification externe avec Bell et Hapi-oauth2orize
• Documentation des API avec Lout et Swaggered

Hapi server !

1. Créez un serveur Hapi dans un module tps/hapi-server/server.js.
2. Créez un module de test avec dans tps/hapi-server/test/server.js. Ce module doit importer le serveur du fichier éponyme et tester :
   1. Hapi server should be started > vérifiez que le serveur démarre et renvoi une 404 sur n'importe quelle url
   2. Hapi server hello API should say hello John > le serveur renvoi le text 'Hi JohnX !' à l'url GET '/hello/JohnX' X étant un nombre aléatoire
   3. Hapi server hello API should fail on too short name > renvoi un code 400 avec une erreur intelligible si le nom n'a pas entre 3 et 10 caractères
   4. Hapi server hello view should render xml content > réponse <msg>Hello JohnX</msg> pour l'url si le header 'accept' contient 'xml'
3. Transformez votre API en un plugin tps/hapi-server/routes/hello.js

"Pyramid of Doom" ??

fs.readdir(source, function(err, files) {
  if (err) {
    console.log('Error finding files: ' + err)
  } else {
    files.forEach(function(filename, fileIndex) {
      console.log(filename)
      gm(source + filename).size(function(err, values) {
        if (err) {
          console.log('Error identifying file size: ' + err)
        } else {
          console.log(filename + ' : ' + values)
          aspect = (values.width / values.height)
          widths.forEach(function(width, widthIndex) {
            height = Math.round(width / aspect)
            console.log('resizing '+filename+'to '+height+'x'+height)
            this.resize(width, height).write(destination+'w'+width+'_'+filename,
              function(err) {
                if (err) console.log('Error writing file: ' + err)
              })
          }.bind(this))
        }
      })
    })
  }
})

Asynchronisme et tableaux

• Appliquer un traitement asynchrone à un tableau

  async.map(['file1','file2','file3'], function(file, next) {
    // appliqué de manière asynchrone sur tous les éléments du tableau
    // la signature de next est next(err, result)
    fs.readFile(file, next);
  }, function(err, results){
    // err est la première erreur renvoyée
    // results est le tableau (ordonné) des résultats intermédiaires
  });

• Tous les traitement sont déclenchés en parallèlemapLimitmapSeries
• Le callback de fin est déclenché... à la fin
• Le premièr échec déclenche le callback de fin, et ignore les résultats en cours

Asynchronisme et functions

• Gérer un flow de fonctions asynchrones

  async.parallel([
    function(done) {
      // la signature de done est done(err, result)
      fs.readFile('in.txt', done);
    }, function(done){
      fs.writeFile('out.txt', 'finished !', done);
    }
  ], function(err, results) {
      // err est la première erreur renvoyée
      // results est le tableau (ordonné) des resultats intermédiaires
  });

• Tous les traitements sont déclenchés en parallèleparallelLimitseries
• Le callback de fin est déclenché à la fin,
  ou suite au premier échec

async.parallel({
  one: function(done) {
    // la signature de done est done(err, result)
    fs.readFile('in.txt', done);
  }, two: function(done){
    fs.writeFile('out.txt', 'finished !', done);
  }
], function(err, results) {
    // err est la première erreur renvoyée
    // results reprends les clé de l'objet initial: {one: '', two: ''}
});

Asynchronisme et functions

• whilst(), doWhilst(): executer une function asynchrone tant que le test synchrone est vrai
• until(), doUntil(): executer une function asynchrone jusqu'a ce que le test synchrone soit vrai
• seq(), compose(), waterfall(): passe les résultats de l'étape N à l'étape N+1
• queue(), cargo(): pool d'exécution asynchrone
  

Utiliser async

1. Maintenant que tps/fs/fs_utils.js est testé, nous allons le refactoriser
2. Refactorisez l'implémentation de getDirStat en utilisant async
3. TODO test avec des fonctions, 20 minutes

Récap du troisième jour

• Node Package Manager
• TDD avec Lab et Chai
• Client évolué avec Request
• Serveur évolué avec Hapi
• Algorithmie asynchrone avec Async

Crédits photos

• Slide 1 - Ricardo Fujii/Grudaemmim
• Slide 2 - Npm inc.
• Slide 9 - Bark
• Slide 17 - Antonio Santa-Pau Ramírez
• Slide 23 - Pharell Wiliams
• Slide 30 - Inception
• Slide 38 - Ricardo Fujii/Grudaemmim