Gadz.org souhaite privilégier l'Architecture Orientée Service (FR) afin de fluidifier les évolutions des applications ainsi que les évolutions technologiques.

Règles de design

Les applications communiquent entre elles via RabbitMQ
Les applications peuvent requeter les référentiels directement via une API HTTP. Dans ce cas, la dépendance au service concernée doit être explicitement signalée

Structure des messages

Les messages doivent vérifier le schema JSON suivant : gorg_soa_message.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "event_name": {
      "type": "string",
      "pattern": "^[_a-z]+((\\.)?[_a-z]+)*$",
      "description": "Event type. Must match the routing key"
    },
    "event_uuid": {
      "type": "string",
      "description": "The unique identifier of this message as UUID",
      "pattern": "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
    },
    "event_creation_time": {
      "type": "string",
      "description": "Creation time in UTC ISO 8601 format",
      "pattern": "^([\\+-]?\\d{4}(?!\\d{2}\\b))((-?)((0[1-9]|1[0-2])(\\3([12]\\d|0[1-9]|3[01]))?|W([0-4]\\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\\d|[12]\\d{2}|3([0-5]\\d|6[1-6])))([T\\s]((([01]\\d|2[0-3])((:?)[0-5]\\d)?|24\\:?00)([\\.,]\\d+(?!:))?)?(\\17[0-5]\\d([\\.,]\\d+)?)?([zZ]|([\\+-])([01]\\d|2[0-3]):?([0-5]\\d)?)?)?)?$"
    },
    "event_sender_id": {
      "type": "string",
      "description": "Producer that sent the original message"
    }, 
    "data": {
      "type": "object",
      "description": "Data used to process this message"
    },
    "errors_count": {
      "type": "integer",
      "description": "Helper for counting errors"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "error_type": {
            "enum": [  "debug", "info", "warning", "softerror", "harderror" ],
            "description": "Type of error."
          },
          "error_sender": {
            "type": "string",
            "description": "Consummer that sent this error"
          },
          "error_code":{
            "type":"string",
            "description": "Optionnal error code from the consummer"
          },
          "error_uuid":{
            "type":"string",
            "description": "The unique identifier of this error as UUID",
            "pattern": "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
          },
          "error_message":{
            "type":"string",
            "description": "Error explanation"
          },          
          "timestamp": {
            "type": "string",
            "description": "Time of occuring error in UTC ISO 8601",
            "pattern": "^([\\+-]?\\d{4}(?!\\d{2}\\b))((-?)((0[1-9]|1[0-2])(\\3([12]\\d|0[1-9]|3[01]))?|W([0-4]\\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\\d|[12]\\d{2}|3([0-5]\\d|6[1-6])))([T\\s]((([01]\\d|2[0-3])((:?)[0-5]\\d)?|24\\:?00)([\\.,]\\d+(?!:))?)?(\\17[0-5]\\d([\\.,]\\d+)?)?([zZ]|([\\+-])([01]\\d|2[0-3]):?([0-5]\\d)?)?)?)?$"
          },
          "error_debug": {
            "type": "object",
            "description": "Complementary informations for debugging"
          }
        },
        "additionalProperties": false,
        "required": [
          "error_type",
          "error_sender",
          "timestamp",
          "error_uuid",
          "error_message"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "event_name",
    "event_uuid",
    "event_creation_time",
    "event_sender_id",
    "data"
  ]
}

Exemple de message :

{  
   "event_uuid":"88d818a1-c77c-44e6-ad0c-8aa893468e94",
   "event_name":"request.gapps.account.create",
   "event_creation_time":"2016-05-29T15:03:50+00:00",
   "event_sender_id":"gram",
   "data":{  
      "id":"12453"
   },
   "errors_count":1,
   "errors":[  
      {  
         "error_type":"softerror",
         "error_uuid":"e157e1a0-2663-11e6-b67b-9e71128cae77",
         "error_sender":"gappsd",
         "error_message":"Google API Unavailable",
         "timestamp":"2016-05-29T15:03:50Z",
         "error_debug":{  
			"id":"12453"
         }
      }
   ]
}

Gestion des erreurs

Dans chaque applications, des erreurs peuvent empecher le message d'être traiter. Chaque message contient l'historique des erreurs qui lui sont associées.

Si un service consommateur souhaite ajouter une erreur il doit obligatoirement renvoyer ce message vers l'exchange RabbitMQ principal. Si le traitement du message ne necessitait pas que celui-ci soit envoyé à un autre service consomateur, il peut être envoyé directement au service d'audit via la routing key spéciale : "agoram.log"

Types d'erreurs

Les messages sont séparés en 5 classes d'erreur

Les termes "Softerror" et "Harderror" sont tirés de la précédente version du manager Google Apps écrit en python par les X. https://github.com/vzanotti/gappsd

Debug

a

Info

b

Warning

c

Softerror

Une erreur temporaire empêche le traitement du message. Il s'agit d'une erreur due à l'environnement extérieur, indépendante du service consommateur. Le message est envoyé dans une queue de stockage pour être retraiter plus tard automatiquement.

Exemples :

Problème réseau empéchant de se connecter à une API
Limite de vitesse d'utilisation d'une API atteinte

Harderror

Une erreur empêche le traitement du message. Il s'agit d'une erreur du au message lui même. Le message ne peux et ne pourra jamais être traiter.

Exemple :

Json mal formaté
Données non valide (ex: pas d'email pour la création d'un compte Google Apps)

Catalogue des services

Gapps

I/O

Routing key

Action/Déclencheur

Format du JSON

Requête

request.gapps.account.create

Crée un nouveau compte Google Apps à partir des informations contenues dans le GrAM et l'application Zenimel

{
  "event":"request.gapps.account.create",
  "data":{
    "id": [Integer] Numéro sociétaire
  }
}

Requête

request.gapps.account.update

Met à jour un compte Google Apps à partir des informations contenues dans le GrAM et l'application Zenimel

{
  "event":"request.gapps.account.update",
  "data":{
    "id": [Integer] Numéro sociétaire
  }
}

Requête

request.gapps.account.delete

Supprime un compte Google Apps à partir des informations contenues dans le GrAM et l'application Zenimel

{
  "event":"request.gapps.account.delete",
  "data":{
    "id": [Integer] Numéro sociétaire
  }
}

Requête

request.gapps.account.suspend

Suspend un compte Google Apps à partir des informations contenues dans le GrAM et l'application Zenimel

{
  "event":"request.gapps.account.suspend",
  "data":{
    "id": [integer] Numéro sociétaire
  }
}

Notification

notify.gapps.account.updated

Un compte Google Apps a été modifié par Gappsd

{
  "event":"notify.gapps.account.updated",
  "data":{
    "id": [Integer] Numéro sociétaire
    "google_apps_id": [String] Adresse principale du compte google apps
    "google_apps_statue": [ENUM(non_existent,created,suspended,deleted)] état du compte
  }
}

{
   "event_uuid":"88d818a1-c77c-44e6-ad0c-8aa893468e94",
   "event_name":"testing_key",
   "event_creation_time":"2016-05-29T15:03:50+00:00",
   "event_sender_id":"tester",
   "data":{
      "test_data":"testing_message"
   },
   "errors_count":1,
   "errors":[
      {
         "error_type":"softerror",
         "error_uuid":"88d838a1-c77c-44e6-ad0c-8aa893468e94",
         "error_sender":"a_sender",
         "error_message":"test_error",
         "timestamp":"2016-05-29T15:03:50Z",
         "error_debug":{

         }
      }
   ]
}

{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "event_name": { "type": "string", "pattern": "^[_a-z]+((\\.)?[_a-z]+)*$", "description": "Event type. Must match the routing key" }, "event_uuid": { "type": "string", "description": "The unique identifier of this message as UUID", "pattern": "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" }, "event_creation_time": { "type": "string", "description": "Creation time in UTC ISO 8601 format", "pattern": "^([\\+-]?\\d{4}(?!\\d{2}\\b))((-?)((0[1-9]|1[0-2])(\\3([12]\\d|0[1-9]|3[01]))?|W([0-4]\\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\\d|[12]\\d{2}|3([0-5]\\d|6[1-6])))([T\\s]((([01]\\d|2[0-3])((:?)[0-5]\\d)?|24\\:?00)([\\.,]\\d+(?!:))?)?(\\17[0-5]\\d([\\.,]\\d+)?)?([zZ]|([\\+-])([01]\\d|2[0-3]):?([0-5]\\d)?)?)?)?$" }, "event_sender_id": { "type": "string", "description": "Producer that sent the original message" }, "data": { "type": "object", "description": "Data used to process this message" }, "errors_count": { "type": "integer", "description": "Helper for counting errors" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "error_type": { "enum": [ "debug", "info", "warning", "softerror", "harderror" ], "description": "Type of error." }, "error_sender": { "type": "string", "description": "Consummer that sent this error" }, "error_code":{ "type":"string", "description": "Optionnal error code from the consummer" }, "error_uuid":{ "type":"string", "description": "The unique identifier of this error as UUID", "pattern": "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" }, "error_message":{ "type":"string", "description": "Error explanation" }, "timestamp": { "type": "string", "description": "Time of occuring error in UTC ISO 8601", "pattern": "^([\\+-]?\\d{4}(?!\\d{2}\\b))((-?)((0[1-9]|1[0-2])(\\3([12]\\d|0[1-9]|3[01]))?|W([0-4]\\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\\d|[12]\\d{2}|3([0-5]\\d|6[1-6])))([T\\s]((([01]\\d|2[0-3])((:?)[0-5]\\d)?|24\\:?00)([\\.,]\\d+(?!:))?)?(\\17[0-5]\\d([\\.,]\\d+)?)?([zZ]|([\\+-])([01]\\d|2[0-3]):?([0-5]\\d)?)?)?)?$" }, "error_debug": { "type": "object", "description": "Complementary informations for debugging" } }, "additionalProperties": false, "required": [ "error_type", "error_sender", "timestamp", "error_uuid", "error_message" ] } } }, "additionalProperties": false, "required": [ "event_name", "event_uuid", "event_creation_time", "event_sender_id", "data" ]}