HackBBS Reloaded

Introduction

Avec l'age, de nombreuses fonctionnalitées ont été rajoutées à HackBBS. La qualité originelle du code et les modifications successives ne permettent plus d'avoir quelque chose de maintenable.

C'est dans cette optique que la refonte du site a été envisagée.

Équipe

• Korigan : CDP, dev
• TorTukiTu : Architecte, dev
• Lancien : dev
• heaven : GDP (Gestionnaire de projet), dev
• fredo2009 : dev
• Shiney  : <to be completed>
• Manu404  : <to be completed>
• Vous ? :-)

Liste des tâches

• [Liste des tâches résolues]
• FAIT - Concevoir et Développer la GUI (IHM) - Tortukitu
• FAIT - Concevoir le noyau - Tortukitu
• FAIT - Développer des modules testant toutes les fonctionnalitées de base du noyau - Tortukitu
• FAIT - Créer le dépot GIT reloadedHackBBS - Korigan
• FAIT - (Optionnel) Créer le système de gestion de projet et des tickets (Redmine ? autre ?) - Korigan
• En Cours - Migrer devBBS vers le wiki - Neomoloch, Zer00cool, Lancien - Manque 2 fichiers .sql
• A faire - Mettre en place un environnement de test et de dev avec une bdd propre et vidée de ses véritables infos - Korigan et?
• En cours - Écrire le code métier du noyau - Tortukitu, Korigan
• En cours - Écrire le code de la couche consumer du noyau - Tortukitu, Korigan
• A faire - Développer une API pour brancher les challenges (Sous forme d'un Web service SOAP pour pouvoir y brancher facilement des challs situés sur des serveurs externes)- Anybody :)
• En attente - Référencement, campagne publicitaire. - Neomoloch
• FAIT - Traduction de certains passages en langue Bambara (dialecte Africain) - Neomoloch.

Contraintes

• Utiliser l'installation et la configuration actuelle du serveur Apache2
• Utiliser des technologies les plus connues et les plus répandues possibles. (Ce qui permettra une implication plus large de la communautée)
• Utiliser des technologies permettant une modularité
• Utiliser des technologies pouvant s'interfacer avec MySQL (Réutilisation de la base de données existante)
• Limiter au maximum l'utilisation de frameworks pour que le projet soit maintenable avec un bagage de connaissances minimum

Technologies retenues

• PHP
• PDO
• Ajax
• HTML5
• gitlab? (Cf heaven, sliim et korigan)

Architecture

Il s'agit d'une architecture 3 couches:

• Une couche gère l'interface utiisateur
• Une couche contient le code métier
• Une couche consomme les différents services (Tape dans les bases de données, envoie les emails, etc.).

Le diagramme ci dessous vous présente l'architecture retenue. Une ligne pleine représente une notion de dépendance, une ligne pointillée un flux de communication.

La communication entre les couches DOIT suivre le sens indiqué par les flèches. Par exemple, appeller des fonctions dans la couche Consumer depuis la couche Business est autorisé. Par contre appeller des fonctions de la couche Business depuis la couche Consumer est interdit.

Une approche par script de transaction a été choisie. Ce qui signifie que les objets du modèle ne DOIVENT JAMAIS comporter des fonctions métier de traitement.

D'une manière plus générale, retenez seulement que vos modules ne devraient accéder QUE a la couche business du noyau (et les couches transversales tel que le modèle ou la sécurité).

L'ensemble de l'application est extensible via l'utilisation de modules (cf. schéma).

Couche provider (Interface utilisateur)

Une interface de type "terminal" a été retenue. Ce type d'interface pose en temps normal des problèmes d'expérience utilisateur, mais s'agissant d'un site de chall, ceci n'entre pas vraiment en ligne de compte. La gestion du terminal est effectuée par des fonctions javascript utilisant la lirairie JQuery et ses extensions jTerminal et JQueryUI.

La communication du serveur vers le client se fait en JSON. C'est en fait un objet DataBusVO sérialisé qui est envoyé du serveur vers le client. La sérialisation est gérée par le script dispatcher.php

L'ensemble du travail des modules consiste donc à générer une instance de DataBusVO qui sera récupérée par dispatcher.php pour modifier l'affichage côté client.

Les fichiers de cette couche sont situés dans le répertoire / et /resources.

Couche business (métier)

La couche métier présente des services aux couches supérieures. Ces services consistent en des singletons ou, plus exotiquement, des fonctions statiques. Les services présentés sont les suivants:

• LoaderService : Gère le chargement dynamique des modules.
• SecurityService : Fourni des fonctions de vérification des permissions des utilisateurs
• SessionService : Gère l'étanchéité des variables de sessions entre différents modules, fournis des fonctions de récupération de l'utilisateur courant
• UserService : Fournis des fonctions de CRUD des utilisatuers, de vérification de connection d'un utilisateur
• SanitizerService : Fournis des fonctions de nettoyage des variables utilisateur.

Les fichiers de cette couche sont situés dans le répertoire /php/core_services/business et /php/modules.

Couche consumer (consommateur de services)

Cette couche conient des services de manipulation de la base de données et d'envoi d'emails.

Les fichiers de cette couche sont situés dans le répertoire /php/core_services/consumer.

Pour consommer des services de cette couche, il faut TOUJOURS le faire via la facade.

Voici un diagramme de classes partiel (il manque les méthodes et les attributs...) de la couche consumer :

Pas d'ORM pour ce projet. Pour savoir comment gérer le relationnel, voir la couche transversale modèle.

Couche transversale : modèle

Cette couche contient des objets porteurs de données dont les instances sont transportés d'une couche à l'autre. Par exemple, la couche consumer crée une instance de User qui est renvoyé à la couche Business.

Les fichiers de cette couche sont situés dans le répertoire /php/model.

Les différents objets du modèle étendent la classe persistent, ce qui permet de donner à chaque instance un identifiant unique. les relations entre objets se font indirectement via leurs identifiants. Il ne faut pas mettre une instance d'un objet dans la variable d'un autre (ce pour éviter les sauvegardes et les chargement en cascade (et éviter un éventuel chargement paresseux d'expérience casse geule à implémenter et à utiliser...)). On a donc opté pour un chargement dynamique des objets a chaque fois que nécéssaire a partir de leurs dentifiants.

Dans notre cas, le coût de cette solution en terme de performances ne devrait pas être un problème.

Dans le cas de relations 1-N, il faut utiliser des arrays d'entiers (identifiants) pour représenter cette relation.

Couche transversale : sécurité

TODO.

Couche transversale : logging

TODO.

Configuration

La configuration (données d'accès aux bases, définition des modules à charger) se trouve dans le fichier hackbbsConf.ini dans le répertoire /php/conf/

Détail du fichier de confguration

Développement de modules

Un module (ici Monmodule) est consitué de trois éléments:

• Une implémentation de l'interface IModule (obligatoire) appellé par convention MonmoduleModule.
• Un dossier (optionnel) appellé par convention monmoduleModule.
• Une déclaration names[] = Monmodule dans le fichier de configuration hackbbsConf.ini (obligatoire).

ATTENTION ! Tous les modules doivent se trouver dans le dossier /php/modules. Veillez à bien respecter les conventions de nommage. Sinon, votre module ne sera pas chargé par le LoaderService et ne sera pas disponible dans le terminal.

Implémentation de IModule

L'interface à implémenter (/php/contract/IModule) compte 3 fonctions :

• function canHandleData($data) : $data est la String que l'utilisateur a entré dans le terminal. Renvoyez true si votre module doit se charger de réaliser l'opération demandée par l'utilisateur, false sinon.
• function manageData($data) : $data est la String que l'utilisateur a entré dans le terminal. Ici, réalisez vos traitements, puis renvoyez une instance de DataBusVO contenant les actions que vous voulez effectuer sur le terminal. Voir la page Contrôle du terminal via DataBusVO.
• function getPrototype() : Renvoie String contenant une description rapide de la commande en HTML. Typiquement macommande : Ce que fait ma commande.

Ci dessous une implémentation de démonstration de IModule

class MonmoduleModule implements IModule{

   public function canHandleData($data) {
       $ans = false;
       if($data == "macommande"){
           $ans = true;
       }
       return $ans;
   }
   public function getPrototype() {
       return "macommande : Ce que fait ma commande";
   }
   public function manageData($data) {
       $dataBus = new DataBusVO();
       $dataBus->setHtmlData("Cette comande ne fait rien de particulier.");
       return $dataBus;
   }    

}

Cette implémentation est à placer dans le répertoire /php/modules.

Modification du fichier de configuration

Ajouter la ligne :

names[] = Monmodule

A la fin de la section [modules] du fichier /php/conf/hackbbsConf.ini

Répertoire monmoduleModule

Contient tous les fichiers spécifiques au mondule monmodule. Si nécéssaire, découper en couches business, model et consumer. Ce répertoire est à placer dans le répertoire /php/modules.

REMARQUE : Entorse à l'architecture pendant la partie refonte de HackBBS.. Un développeur de modules ne devrait jamais toucher au noyau. Or, la plupart du métier (et modèle) développé aujourd'hui sera nécéssaire à un grand nombre de futur modules. Il est donc de bon ton d'ajouter au métier du noyau les fonctions et services que l'on saura réutilisés dans la suite des développements. Ceci est laissé à l'appréciation du développeur. Lorsque la refonte sera terminé, il deviendra interdit aux futurs développeurs de toucher au code du noyau pour y ajouter de nouvelles fonctionnalitées. Les modules préexistants seront alors fusionnés avec le noyau.

Règles générales (A toujours avoir sous les yeux !)

• A toute classe son interface.
• Jamais de copier coller
• Respectez l'architecture
• Ne jamais utiliser directement $_SESSION, toujours passser par le service SessionService (sauf exceptions autorisées par l'architecte)
• Chaque classe et fonction doit être commentée
• Pensez sécurité... Vous développez un site de hack. Il sera attaqué de la facon la plus tordue possible. Vous avez un service de nettoyage des entrées, alors utilisez-le !
• Choisissez toujours la convention sur la configuration
• (Optionnel) Écrire une page de wiki par module
• (Optionnel) Si vous avez le temps, les tests unitaires, c'est bien

FAQ / HOWTO

• FAQ : Développement de modules
• HOWTO : Modification du modèle du noyau