Principes du protocole Cyberrail

Le protocole Cyberrail est défini en plusieurs couches :

D’un point de vue “Modèle OSI”, le protocole se découpe de façon suivante :

• Couche Transport et inférieures : Voir Couche de transport sur Wikipedia : il s’agit d’aller lire une socket du système.
• Couche Session : aucune
• Couche Présentation : le protocole Cyberrail utilise YAML 1.1 (et 1.2 lorsque / si PyYAML est mis à jour). Il est possible que le protocole passe à JSON si PyYAML était amené à disparaître. Le protocole fournit un objet associatif récursif (un dictionnaire par exemple).
• Couche Application : la suite de ce document

• Couche Dialogue : les différents types de messages et leurs réponses éventuelles
• Couche Message : détails des ordres et des données

La couche dialogue permet d’abstraire et de normaliser différents types de messages. Il y a plusieurs familles de messages spécifiées par le protocole. En outre, chaque message dispose d’un type, spécifié par chaque module et portant une valeur “métier”.

• Messages asynchrone : ce sont les messages les plus simple. Un module envoie un message indiquant un nouvel état, ou une nouvelle action de l’utilisateur. Le message doit comprend le destinataire
• Messages asynchrone diffusé : ces messages les plus simple. Ces messages sont remis à tous les modules abonnés à ce type de message
• Requête directe : une requête directe attend une réponse précise d’un module interrogé. Cette requête comprend un destinataire spécifique ainsi qu’un identifiant unique, qui sera utilisé lors de la réponse
• Requête diffusée : une requête diffusée à tous les modules abonnés au type de la requête
• Réponse à une requête : un message comprenant l’identifiant unique de la requête ainsi qu’une réponse à destination du module expéditeur
• Avertissement : C’est un message envoyé par le noeud central concernant une erreur récupérable dans le protocole. La connexion n’est pas fermée, mais le message précédent n’a sans doute pas pu être délivré
• Erreur : C’est un message envoyé par le noeud central concernant une erreur irrécupérable du protocole. Le message provoquant l’erreur n’a pas été traité, ni les suivants. La connexion est fermée.

Attention, dans les deux derniers cas, il ne s’agit pas d’erreurs fonctionnelles mais purement protocolaire.

Un message sera envoyé avec les éléments suivants :

• famille : ”request”, ”response”, ”warning”, ”error”
• type : une chaîne de caractères définie par un module
• destinataire, optionnel : défini le destinataire, qui doit être abonné. En cas d’absence, le message est diffusé à tous les abonnés.
• identifiant de requête, optionnel : défini l’identifiant de suivi de cette requête. En cas d’absence, ce message n’est pas une requête et n’aura donc pas de réponse
• expéditeur, ajouté ou remplacé par le noeud central : défini l’expéditeur du message
• date, ajouté ou remplacé par le noeud central : la date à laquelle le noeud central a reçu le message
• contenu : un contenu accompagnant ce message, et comportant toutes les données utiles au traitement de ce message par d’autres modules

Résumé des messages possibles concernant les requêtes :

Certains messages et certains paramètres doivent respecter un formalisme qui leur est propre.

Les messages asynchrones peuvent être envoyés n’importe quand. Le, ou les destinataires doivent exister. En cas d’inexistence du destinataire, un avertissesment est renvoyé.

Les messages asynchrones peuvent être envoyés n’importe quand. Les destinataire doivent préalablement s’abonner au type du message. En cas d’absence de destinataire, un avertissesment est renvoyé.

Les requêtes peuvent être envoyées n’importe quand, même lorsqu’une requête précédente n’a toujours pas obtenue sa ou ses réponses.

Chaque requête doit disposer d’un, ou de plusieurs destinataires.

Chaque nouvelle requête doit disposer d’un identifiant différent des précédents. Cet identifiant doit être unique parmi tous les modules. En cas d’identifiant déjà existant, la requête sera rejetée par un avertissement.

Cette requête ne recevra qu’une seule réponse par destinataire.

Le noeud central informera le module originaire de la requête que celle-ci est terminée une fois toutes les réponses reçues via une dernière réponse correspondant à cette requête.

Même principe que pour les requêtes.

Le noeud central informera le module originaire de la requête que celle-ci est terminée une fois toutes les réponses reçues. C’est le seul moyen pour ce module de connaitre le moment ou toutes les réponses possibles sont reçues.

Les réponses sont obligatoirement des messages dont l’identifiant unique est spécifié. Il est interdit de générer des réponses comportant un identifiant qui n’a pas été créé par une requête. Dans ce dernier cas, la réponse est ignorée et un avertissement est envoyée.

L’identifiant d’une requête est valide à partir de sa réception par un module et pour une et une seule réponse.

Ces messages ne sont envoyés que par le noeud central. Un client correctement écrit ne devrais pas générer de tels types de messages.

Une requête :

{
  "family": "request",
  "type": "saveRequest",
  "id": "4542546",
  "content": ""
}

Un message simple :

{
  "family": "request",
  "type": "plopMessage",
  "dest": ["module1-1245", "moduleX-7541],
  "content": {
    "content" : "payload",
    "desc": "This is the payload"
  }
}

Une réponse à la requête précédente :

{
  "family": "response",
  "type": "saveResponse",
  "id": "4542546",
  "content": "Data to be saved"
}
{
  "family": "response",
  "type": "noMoreResponse",
  "id": "4542546",
}