README.md

Introduction

Ce dépôt contient le backend de Sigma, le successeur de Frankiz, un site étudiant permettant de gérer les groupes et les étudiants du plateau de Saclay.

Pour obtenir une copie de ce dépôt, clonez-le avec

git clone git@gitlab.binets.fr:br/sigma-backend.git

ou git clone https://gitlab.binets.fr/br/sigma-backend.git, puis installez les dépendences JavaScript avec npm install.

A terme, ce projet doit tourné sur un serveur de l'école polytechnique et fournir à un serveur front au code séparé et documenté séparément toute les données nécessaires à son bon fonctionnement (authentification, appartenance à un groupe, droits de visibilité...).

Ce document détaille les différentes dépendances du projet, sa structure générale, détaille un peu plus des éléments sur la base de données et la documentation ; le code est également commenté en détail.

Dépendances

Une dépendance, c'est un librairie JavaScript dont dépend le code source, soit pour le faire tourner soit pour faire tourner les outils dévs. Les dépendances développeur servent à tester par exemple. On trouve la liste des dépendances dans package.json. Express est un exemple de dépendance normale, nodemon et ESLint (voir infra) sont des dépendances dev (devDependencies).

Les dépendances s'installent avec npm install. Par défaut, toutes les dépendances sont installées. Si la variable NODE_ENV est configurée (vérifier avec la commande echo "$NODE_ENV"),

• la valeur development installe tout
• la valeur production n'installe pas les dépendances développeur

Certaines d'entre elles comme KnexJS ou Webpack doivent être installées globalement :

npm install -g knex
npm install -g webpack
npm install -g eslint

Les dépendances les plus importantes sont knex.js, notre outil de gestion de BDD locale, GraphQL qui sert à communiquer entre serveurs, ldap.js qui interroge le LDAP avec la plupart des données, webpack qui sert à la gestion du serveur. ESlint est un outil de vérification synthaxique.

Le serveur utilisé est express.js ; il est configuré dans server.js puis lancé sur le port 8888 dans index.js.

Structure

La structure générale du projet est détaillée ci-dessous ; pas d'inquiétude, la plupart des fichiers .js sont aussi extensivement documentés plus bas.

• Racine du projet : fichiers de configuration ;
  • config.json : données "sensibles" spécifique au projet à priori non partageable (adresse du LDAP, mots de passe),
  • configfile_doc.json : JSDoc, l'outil de génération automatique de documentation,
  • autres fichiers relatifs à des modules particuliers ou à la gestion de paquets,
  • assets : ressources ;
    • images et divers (dont l'essentiel flavicon)
  • build : dépendances gérées automatiquement ;
    • bundle.js est un monstrueux fichier généré automatiquement qui gère nos dépendances.
  • db : base de donnée sigma ;
  • knex_router.js charge la configuration précisée dans knexfile.js,
    • migrations stocke l'ensemble des migrations knex ; c'est un équivalent d'un répertoire git pour la BDD sigma (du coup seulement les groupes pas les individus),
    • seeds : stocke les éléments de générations des BDD ; c'est un ensemble de scripts.
  • doc : documentation ;
    • ensemble de pages html et fichiers associés ; index.html permet de naviguer sereinement sur toute la doc JSDoc.
  • node_modules : gestion automatique des modules.
  • src : code source
    • admin_view : gestion d'une interface administrateur de la base de donnée, s'appuie sur css et views
    • ldap : gestion des requêtes LDAP

La syntaxe adoptée est JavaScript ES6, un standard moderne (2015) de JavaScript. Il permet d'importer des dépendances en utilisant le mot-clé import, ce que le serveur Node.js ne comprend pas puisque la version 8 de Node ne comprend que le standard ES5 (2009), qui gère les imports avec require().

Base de données

Sigma s'appuie sur deux bases de données :

• La BDD frankiz accessible par LDAP hébergée sur un serveur de l'école, qui contient identifiants, mots de passe, et toutes les informations sur les utilisateurs et groupes spécifiques X.
  • On y accède par des requêtes LDAP, d'où la nécessité de ldap.js.
• La BDD de sigma propre est en PostgreSQL, hébergée en propre BR, qui contient les groupes et leurs niveaux de visibilité mais peu d'information sur les utilisateurs (seulement son école).
  • Les requêtes à cette base de données sont gérées par Knex.js.

Cette structure peut sembler lourde et redondante mais s'explique par plusieurs raisons :

• Volonté d'intégrer d'autres écoles simplement
  • Rajouter leurs groupes sur la BDD sigma
  • Pas les obliger à rejoindre notre LDAP avec notre structure
• Garder le LDAP X et le mettre à jour ; il est utilisé par beaucoup d'autres sites X
• Enjeu de sécurité
  • La BDD de sigma est public et ne comporte rien de compromettant
  • La BDD accessible par LDAP de l'X qui contient des informations plus sensibles et qui doit être plus protégée

Les deux sections suivantes détaillent les opérations possibles grâce au back directement sur les bases de données via sigma.

Guide: Knex.js

L'interface en ligne de commande de Knex.js contient les commandes suivantes :

• knex migrate:make migration_name crée une migration dans db/migrations/
• knex migrate:latest met à jour le schéma de la BDD
• knex seed:make filename crée un seed seeds/filename
• knex seed:run insère les seeds dans la BDD

Un fichier seed permet d'insérer des données dans la BDD. Ils sont stockés dans seeds.

Comment faire une migration

On utilisera l'interface en ligne de commande de Knex.js.

Les migrations servent à mettre à jour le schéma de la base de données. Pour créer une migration, on lance la commande knex migrate:make <nom_migration>, qui crée un fichier db/migrations/[hash]_nom_migration.js où le hash est la date et l'heure.

Maintenant, on édite le fichier de migration. Il fait deux exports, exports.up et exports.down, qui définissent respectivement comment mettre à jour le schéma de la BDD et comment annuler la modification si knex migrate:rollback est invoqué.

Il faut se référer à la documentation de Knex.js pour comprendre comment écrire les requêtes. Voici un cheatsheet.

Fonctions LDAP

On peut facilement explorer et modifier des éléments du LDAP de l'école depuis le réseau de l'X avec JXplorer en entrant frankiz dans nouvelle connexion et en allant dans net.

Accéder à la BDD de sigma propre

Pour accéder à la "vraie" BDD, sur roued (le serveur qui héberge sigma), il faut

• se connecter dessus en ssh roued
• passer en sudo
• faire un su postgres pour se faire passer pour l'utilisateur unix postgres
• se connecter à la BDD via la commande psql
• faire les requetes en SQL par l'interface de postgreSQL.

Scripts

Les scripts sont des instructions en ligne de commande que l'on peut faire tourner avec la commande npm run. Ce sont des raccourcis pour gagner du temps sur des opérations un peu longues. Ils sont définis dans package.json.

Les plus importants sont détaillées ci-dessous (ne pas oublier npm install déjà mentionné plus tôt) :

On utilisera Webpack pour transpiler le fichier source src/index.js en build/bundle.js qui est suit la syntaxe ES5 compatible Node. Pour ça, on utilise :

• npm run build qui exécute la commande webpack avec le fichier de configuration webpack.config.js, ou
• npm run watch qui recompile automatiquement dès que le code est modifié.

Pour faire tourner le serveur, il y a deux options :

• npm serve fait tourner le serveur bundle.js en mode prod sur le port 3000 (donc il faut consulter https://localhost:3000)
• npm start le démarre avec nodemon, outil dév qui redémarre automatiquement le serveur dans bundle.js dès que celui-ci est modifié.

Donc, lancer npm run watch dans un terminal et npm test dans un autre permet de recompiler le serveur et le redémarrer automatiquement dès qu'il y a une modification.

Le script pour faire tourner JSDoc et régénérrer la documentation est : npm run doc

Documentation

La documentation détaillée du projet est ici. Elle a été compilée avec JSDoc sous format hmtl selon le fichier de configuration configfile_doc.json à la racine du projet.

Les fichiers compilés se situent dans doc avec leurs fichiers image. Par nature de l'outil JSDoc il est facile de documenter en détail des fonctions .js mais plus compliqué de documenter un fichier.

A la fin de ce fichier JSDoc rajjoute les commentaires placés dans chacun des fichiers et des hyperliens pour y accéder.

Appendixes

ESLint

On utilisera ESLint pour standardiser le code : un ensemble de règles de style pour le code sont appliquées, et quelques-unes d'entre elles sont dans le fichier .eslintrc.json. Pour l'instant, la config ESLint impose d'utiliser quatre espaces pour les indentations et d'utiliser des points-virgule en fin de ligne.

Il est préférable de l'installer globalement avec npm install -g eslint. Pour faire valider les fichiers source par ESLint, utilisez npm run lint.

qui fait appel au script eslint src/ défini dans le package.json. L'option --fix permet de corriger les fichiers.

Sinon, si vous utilisez Atom ou Visual Studio Code pour éditer votre code, il existe des plugins qui font tourner ESLint en live sur le code et vérifient que tout est en ordre.

Pour mieux comprendre ESLint, référez-vous à la doc.

API/panneau d'administration

Authentification

L'authentification se fait contre le LDAP en envoyant un requête HTTP POST à '/login'. En fonction de la valeur du header Accept inclus dans la requête, on a deux comportements possibles

application/json	autre
Renvoie un message de succès/d'échec	Redirige vers /admin