doc/protocole3.txt

   1 Euphorik - Protocole v3
   2 -----------------------
   3
   4 == Introduction ==
   5 Ce document a pour but de décrire la communication client-serveur du site euphorik.
   6 Les messages échangés sont basés sur le format JSON.
   7 Ce document remplace 'protocole2.txt'.
   8
   9
  10 == Principes ==
  11 Enregistrement:
  12  * Permet de créer un compte, un cookie est donné en retour. Ce cookie doit être stocké par le client pour pouvoir s'authentifier par la suite.
  13
  14 Authentification:
  15  * L'authentification (login) se fait soit par un couple <login, mot de passe> soit à l'aide d'un cookie.
  16  * Permet de récupérer les données d'un profile
  17
  18 Rafraichissement:
  19  * Le client envoie une demande au serveur avec l'id du dernier message (via XMLHttpRequest ou un function de JQuery)
  20  * Le serveur maintient la connexion bloquée si le client est à jour.
  21  * Dès qu'un nouveau message arrive, le serveur débloque la connexion et envoie le ou les messages manquants.
  22
  23
  24 == Protocole ==
  25 c : client
  26 s : server
  27 Les messages client vers serveur sont envoyés par HTTP-POST.
  28
  29 A toutes les requêtes le serveur peut répondre une erreur :
  30 <error>
  31    {
  32       "reply" : "error",
  33       "error_message" : "blabla"
  34    }
  35
  36 Message ok générique :
  37 <ok>
  38    {
  39       "reply" : "ok"
  40    }
  41
  42 Entete des messages clients :
  43 Si la version du protocole n'est pas similaire du coté serveur la requête est refusée
  44 <client_header>
  45    {
  46       "action" : <action>,
  47       "version" : 3
  48    }
  49
  50
  51 === Enregistrement et authentification ===
  52 Permet de créer un nouvel utilisateur.
  53 "login" et "password" peuvent ne pas être fournis avec un message de type "register", dans ce cas l'utilisateur ne pourra s'authentifier qu'a l'aide de son cookie.
  54 Le mot de passe est hashé en md5.
  55
  56 c -> s
  57    {
  58       "header" : {action : "authentification", version : 3},
  59       "login" : "paul",
  60       "password" : "IJKJDHHSAD9081238"
  61    }
  62 ou
  63    {
  64       "header" : {action : "authentification", version : 3}
  65       "cookie" : "LKJDLAKSJBFLKASN"
  66    }
  67 ou
  68    {
  69       "header" : {action : "authentification", version : 3},
  70       "login" : "paul",
  71       "password" : "IJKJDHHSAD9081238"
  72    }
  73
  74 s -> c
  75    {
  76       "reply" : "register" | "authentification",
  77       "status" : "auth_not_registered",
  78       "cookie" : "LKJDLAKSJBFLKASN",
  79       "id" : 193,
  80       "css" : "css/1/euphorik.css",
  81       "main_page" : 1
  82    }
  83 ou
  84    {
  85       "reply" : "register" | "authentification",
  86       "status" : "auth_registered",
  87       "cookie" : "LKJDLAKSJBFLKASN",
  88       "id" : 193,
  89       "nick" : "Paul",
  90       "login" : "paul49",
  91       "email" : "paul@pierre.com",
  92       "css" : "css/3/euphorik.css",
  93       "nick_format" : "nick" | "login" | "nick_login",
  94       "view_times" : true | false,
  95       "view_tooltips" : true | false,
  96       // "main_page" : 1,
  97       "conversations" : [3, 8],
  98       "ek_master" : true | false
  99    }
 100
 101
 102 === Logout ===
 103 c -> s
 104    {
 105       "header" : {action : "logout", version : 3},
 106       "cookie" : "LKJDLAKSJBFLKASN"
 107    }
 108
 109
 110 === Profile ===
 111 c -> s
 112    {
 113       "header" : {action : "set_profile", version : 3},
 114       "cookie" : "LKJDLAKSJBFLKASN",
 115       "login" : "paul49",
 116       "password" : "IJKJDHHSAD9081238",
 117       "nick" : "Paul",
 118       "email" : "paul@pierre.com",
 119       "css" : "css/3/euphorik.css",
 120       "nick_format" : "nick" | "login" | "nick_login",
 121       "view_times" : true | false,
 122       "view_tooltips" : true | false,
 123       "main_page" : 1,
 124       "conversations" : [3, 8]
 125    }
 126
 127 s -> c
 128    <ok>
 129 ou
 130    <error>
 131
 132
 133 === Wait event (page = chat) ===
 134 Si "last_message_id" est absent alors le client ne possède pas de message.
 135 Si "main_page" est absent alors est vaut 1.
 136 "cookie" n'est pas obligatoire.
 137
 138 <message>
 139    {
 140       "id" : 54,
 141       "user_id" : 344,
 142       "date" : "Hier 17:26:54",
 143       "system" : true | false,
 144       "owner" : true | false,
 145       "answered" : true | false,
 146       "is_a_reply" : true | false,
 147       "nick" : "Paul",
 148       "login" : "paul_22",
 149       "content" : "Salut",
 150       "root" : 453,
 151       "answer_to" : [
 152          { "id" : 123, "nick" : "Pierre", "login" : "pierre_45" }
 153       ]
 154       "ek_master" : true | false
 155    }
 156
 157 c -> s
 158    {
 159       "header" : {action : "wait_event", version : 3},
 160       "page" : "chat"
 161       "cookie" : "LKJDLAKSJBFLKASN",
 162       "message_count" : 10,
 163       "last_message_id" : 163,
 164       "main_page" : 1,
 165       "troll_id" : 45,
 166       "conversations" : [
 167          {
 168             "root" : 123,
 169             "page" : 1,
 170             "last_message_id" : 4 (pas obligatoire)
 171          }
 172       ]
 173    }
 174
 175 s -> c
 176 La première conversation est la principale (main).
 177 L'ordre des conversation est le même que celui des données de l'utilisateur.
 178 Le format de la date n'est pas formel.
 179 first correpond au premier message de la conversation, vaut 'undefined' pour la conversation principale ainsi que pour les conversations vides.
 180    {
 181       "reply" : "new_message",
 182       "conversations" : [
 183          {
 184             "last_page" : true | false,
 185             "first" : <message> | undefined,
 186             "messages" : [ <message>, .. ]
 187          }
 188       ]
 189    }
 190 ou
 191    {
 192       "reply" : "message_updated",
 193       "message_id" : 123,
 194       "content" : "Salut +++ poulpe"
 195    }
 196 ou
 197    {
 198       "reply" : "new_troll",
 199       "troll_id" : 123,
 200       "message_id" : 12,
 201       "content" : "Linux sera desktop ready en 2008 ?"
 202    }
 203 ou
 204    <error>
 205
 206
 207 === Wait event (page = admin) ===
 208 c -> s
 209    {
 210       "header" : {action : "wait_event", version : 3},
 211       "page" : "admin",
 212       "last_troll" : 5
 213    }
 214
 215 s -> c
 216    {
 217       "reply" : "troll_modified",
 218       "troll_id" : 3,
 219       "content" : "plop"
 220    }
 221 ou
 222 s -> c
 223    {
 224       "reply" : "troll_added",
 225       "trolls" :
 226          [
 227             {
 228                "troll_id" : 5,
 229                "content" : "plop",
 230                "author" : "<Pseudo>"
 231                "author_id" : 2
 232             }
 233          ]
 234    }
 235 ou
 236 s -> c
 237    {
 238       "reply" : "troll_deleted",
 239       "troll_id" : 2
 240    }
 241 ou
 242 indique de mettre à jour la liste d'ips
 243 s -> c
 244    {
 245       "reply" : "banned_ips_refresh"
 246    }
 247
 248
 249 === Envoie d'un troll ===
 250 c -> s
 251    {
 252       "header" : {action : "put_troll", version : 3},
 253       "cookie" : "LKJDLAKSJBFLKASN",
 254       "content" : "Un bon troll velu !"
 255    }
 256
 257 s -> c
 258    <ok>
 259 ou
 260    <error>
 261
 262
 263 === Modification d'un troll ===
 264 c -> s
 265    {
 266       "header" : {action : "mod_troll", version : 3},
 267       "cookie" : "LKJDLAKSJBFLKASN",
 268       "troll_id" : 3,
 269       "content" : "Un bon troll velu 2 !"
 270    }
 271
 272 s -> c
 273    <ok>
 274 ou
 275    <error>
 276
 277
 278 === Suppression d'un troll ===
 279 c -> s
 280    {
 281       "header" : {action : "del_troll", version : 3},
 282       "cookie" : "LKJDLAKSJBFLKASN",
 283       "troll_id" : 3
 284    }
 285
 286 s -> c
 287    <ok>
 288 ou
 289    <error>
 290
 291
 292 === Envoie message ===
 293 Le client envoie un message, le message peut répondre à un certain nombre d'autres messages.
 294 "answer_to" n'est pas obligatoire.
 295
 296 c -> s
 297    {
 298       "header" : {action : "put_message", version : 3},
 299       "cookie" : "LKJDLAKSJBFLKASN",
 300       "nick" : "Paul",
 301       "content" : "Bonjour",
 302       "answer_to" : [ 345, 532, ... ]
 303    }
 304
 305 s -> c
 306    <ok>
 307 ou
 308    <error>
 309
 310
 311 === Slapage ===
 312 c -> s
 313    {
 314       "header" : {action : "slap", version : 3},
 315       "cookie" :  "LKJDLAKSJBFLKASN",
 316       "user_id" : 67,
 317       "reason" : "blablabla"
 318    }
 319
 320 s -> c
 321    <ok>
 322 ou
 323    <error>
 324
 325
 326 === Bannissement ===
 327 c -> s
 328    {
 329       "header" : {action : "ban", version : 3},
 330       "cookie" : "LKJDLAKSJBFLKASN",
 331       "duration" : 15, // en minute
 332       "user_id" : 67,
 333       "reason" : "blablabla"
 334    }
 335
 336 s -> c
 337    <ok>
 338 ou
 339    <error>
 340
 341
 342 === Liste des ip bannis ===
 343 c -> s
 344    {
 345       "header" : {action : "list_banned_ips", version : 3},
 346       "cookie" : "LKJDLAKSJBFLKASN"
 347    }
 348
 349 s -> c
 350    {
 351       "reply" : "list_banned_ips",
 352       "list" : [
 353          {
 354             ip : "192.168.1.2",
 355             remaining_time : "1h23"
 356             users : [
 357                {
 358                   nick : "Pierre" ,
 359                   login : "pierre"
 360                }
 361             ]
 362          }
 363       ]
 364    }
 365
 366
 367 === Débannissement ===
 368 c -> s
 369    {
 370       "header" : {action : "unban", version : 3},
 371       "cookie" : "LKJDLAKSJBFLKASN"
 372       "ip" : "192.168.1.2"
 373    }
 374
 375 s -> c
 376    <ok>
 377 ou
 378    <error>
 379
 380
 381 === Ajout d'une correction d'un messages ===
 382 Le client envoie un correctif sous la forme de texte supplémentaire à appondre au dernier messages.
 383 Le message est appondu avec un " +++ " devant, par exemple :
 384 > Gnome c'est mieux que KDE +++ Euh non ok, c'est faux
 385
 386 c -> s
 387    {
 388       "header" : {action : "correction", version : 3},
 389       "cookie" : "LKJDLAKSJBFLKASN",
 390       "content" : "Euh non ok, c'est faux"
 391    }
 392
 393 s -> c
 394    {
 395       "reply" : "correction",
 396       "status" : "ok" | "error",
 397       "message_error" : "blabla"
 398    }