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 : "register", version : 3},
  59       "login" : "paul",
  60       "password" : "IJKJDHHSAD9081238",
  61       "profile_infos" : { .. } // voir <profile_infos>
  62    }
  63 ou
  64    {
  65       "header" : {action : "authentification", version : 3}
  66       "cookie" : "LKJDLAKSJBFLKASN"
  67    }
  68 ou
  69    {
  70       "header" : {action : "authentification", version : 3},
  71       "login" : "paul",
  72       "password" : "IJKJDHHSAD9081238"
  73    }
  74
  75 s -> c
  76    {
  77       "reply" : "register" | "authentification",
  78       "status" : "auth_registered" | "auth_not_registered",
  79       "cookie" : "LKJDLAKSJBFLKASN",
  80       "id" : 193,
  81       "nick" : "Paul",
  82       "login" : "paul49",
  83       "email" : "paul@pierre.com",
  84       "css" : "css/3/euphorik.css",
  85       "chat_order" : "chrono" | "reverse",
  86       "nick_format" : "nick" | "login" | "nick_login",
  87       "view_times" : true | false,
  88       "view_tooltips" : true | false,
  89       "conversations" : [{"root" : 3, "minimized" : true},
  90       "ek_master" : true | false,
  91       "ostentatious_master" : "invisible" | "light" | "heavy"
  92    }
  93
  94
  95 === Logout ===
  96 c -> s
  97    {
  98       "header" : {action : "logout", version : 3},
  99       "cookie" : "LKJDLAKSJBFLKASN"
 100    }
 101
 102
 103 === Profile ===
 104 <profile_infos>
 105    {
 106       "nick" : "Paul",
 107       "email" : "paul@pierre.com",
 108       "css" : "css/3/euphorik.css",
 109       "chat_order" : "chrono" | "reverse",
 110       "nick_format" : "nick" | "login" | "nick_login",
 111       "view_times" : true | false,
 112       "view_tooltips" : true | false,
 113       "conversations" : [{"root" : 3, "minimized" : true},
 114       "ostentatious_master" : "invisible" | "light" | "heavy"
 115    }
 116
 117 c -> s
 118    {
 119       "header" : {action : "set_profile", version : 3},
 120       "cookie" : "LKJDLAKSJBFLKASN",
 121       "login" : "paul49",
 122       "password" : "IJKJDHHSAD9081238",
 123       "profile_infos" : <profile_infos>
 124    }
 125
 126 s -> c
 127    <ok>
 128 ou
 129    <error>
 130
 131
 132 === Wait event (page = chat) ===
 133 Si "last_message_id" est absent alors le client ne possède pas de message.
 134 Si "main_page" est absent alors est vaut 1.
 135 "cookie" n'est pas obligatoire.
 136
 137 <message>
 138    {
 139       "id" : 54,
 140       "user_id" : 344,
 141       "date" : "Hier 17:26:54",
 142       "system" : true | false,
 143       "owner" : true | false,
 144       "answered" : true | false,
 145       "is_a_reply" : true | false,
 146       "nick" : "Paul",
 147       "login" : "paul_22",
 148       "content" : "Salut",
 149       "root" : 453,
 150       "answer_to" : [
 151          { "id" : 123, "nick" : "Pierre", "login" : "pierre_45" }
 152       ],
 153       "ek_master" : true | false,
 154       "ostentatious_master" : "invisible" | "light" | "heavy",
 155       "last_modification" : "Hier 17:26:54"
 156    }
 157
 158 c -> s
 159    {
 160       "header" : {action : "wait_event", version : 3},
 161       "page" : "chat"
 162       "cookie" : "LKJDLAKSJBFLKASN",
 163       "message_count" : 10,
 164       "last_message_id" : 163,
 165       "main_page" : 1,
 166       "troll_id" : 45,
 167       "conversations" : [
 168          {
 169             "root" : 123,
 170             "page" : 1,
 171             "last_message_id" : 4 (pas obligatoire)
 172          }
 173       ]
 174    }
 175
 176 s -> c
 177 La première conversation est la principale (main).
 178 L'ordre des conversation est le même que celui des données de l'utilisateur.
 179 Le format de la date n'est pas formel.
 180 first correpond au premier message de la conversation, vaut 'null' pour la conversation principale ainsi que pour les conversations vides.
 181    {
 182       "reply" : "new_message",
 183       "conversations" : [
 184          {
 185             "last_page" : true | false,
 186             "first" : <message> | null,
 187             "messages" : [ <message>, .. ]
 188          }
 189       ]
 190    }
 191 ou
 192    {
 193       "reply" : "message_updated",
 194       "message_id" : 123,
 195       "content" : "Salut poulpe",
 196       "last_modification" : "Hier 17:26:54"
 197    }
 198 ou
 199    {
 200       "reply" : "new_troll",
 201       "troll_id" : 123,
 202       "message_id" : 12,
 203       "content" : "Linux sera desktop ready en 2008 ?"
 204    }
 205 ou
 206    <error>
 207
 208
 209 === Wait event (page = admin) ===
 210 c -> s
 211    {
 212       "header" : {action : "wait_event", version : 3},
 213       "page" : "admin",
 214       "last_troll" : 5
 215    }
 216
 217 s -> c
 218    {
 219       "reply" : "troll_modified",
 220       "troll_id" : 3,
 221       "content" : "plop"
 222    }
 223 ou
 224 s -> c
 225    {
 226       "reply" : "troll_added",
 227       "trolls" :
 228          [
 229             {
 230                "troll_id" : 5,
 231                "content" : "plop",
 232                "author" : "<Pseudo>"
 233                "author_id" : 2
 234             }
 235          ]
 236    }
 237 ou
 238 s -> c
 239    {
 240       "reply" : "troll_deleted",
 241       "troll_id" : 2
 242    }
 243 ou
 244 indique de mettre à jour la liste d'ips
 245 s -> c
 246    {
 247       "reply" : "banned_ips_refresh"
 248    }
 249
 250
 251 === Envoie d'un troll ===
 252 c -> s
 253    {
 254       "header" : {action : "put_troll", version : 3},
 255       "cookie" : "LKJDLAKSJBFLKASN",
 256       "content" : "Un bon troll velu !"
 257    }
 258
 259 s -> c
 260    <ok>
 261 ou
 262    <error>
 263
 264
 265 === Modification d'un troll ===
 266 c -> s
 267    {
 268       "header" : {action : "mod_troll", version : 3},
 269       "cookie" : "LKJDLAKSJBFLKASN",
 270       "troll_id" : 3,
 271       "content" : "Un bon troll velu 2 !"
 272    }
 273
 274 s -> c
 275    <ok>
 276 ou
 277    <error>
 278
 279
 280 === Suppression d'un troll ===
 281 c -> s
 282    {
 283       "header" : {action : "del_troll", version : 3},
 284       "cookie" : "LKJDLAKSJBFLKASN",
 285       "troll_id" : 3
 286    }
 287
 288 s -> c
 289    <ok>
 290 ou
 291    <error>
 292
 293
 294 === Envoie message ===
 295 Le client envoie un message, le message peut répondre à un certain nombre d'autres messages.
 296 "answer_to" n'est pas obligatoire.
 297
 298 c -> s
 299    {
 300       "header" : {action : "put_message", version : 3},
 301       "cookie" : "LKJDLAKSJBFLKASN",
 302       "nick" : "Paul",
 303       "content" : "Bonjour",
 304       "answer_to" : [ 345, 532, ... ]
 305    }
 306
 307 s -> c
 308    <ok>
 309 ou
 310    <error>
 311
 312
 313 === Slapage ===
 314 c -> s
 315    {
 316       "header" : {action : "slap", version : 3},
 317       "cookie" :  "LKJDLAKSJBFLKASN",
 318       "user_id" : 67,
 319       "reason" : "blablabla"
 320    }
 321
 322 s -> c
 323    <ok>
 324 ou
 325    <error>
 326
 327
 328 === Bannissement ===
 329 c -> s
 330    {
 331       "header" : {action : "ban", version : 3},
 332       "cookie" : "LKJDLAKSJBFLKASN",
 333       "duration" : 15, // en minute
 334       "user_id" : 67,
 335       "reason" : "blablabla"
 336    }
 337
 338 s -> c
 339    <ok>
 340 ou
 341    <error>
 342
 343
 344 === Liste des ip bannis ===
 345 c -> s
 346    {
 347       "header" : {action : "list_banned_ips", version : 3},
 348       "cookie" : "LKJDLAKSJBFLKASN"
 349    }
 350
 351 s -> c
 352    {
 353       "reply" : "list_banned_ips",
 354       "list" : [
 355          {
 356             ip : "192.168.1.2",
 357             remaining_time : "1h23"
 358             users : [
 359                {
 360                   nick : "Pierre" ,
 361                   login : "pierre"
 362                }
 363             ]
 364          }
 365       ]
 366    }
 367
 368
 369 === Débannissement ===
 370 c -> s
 371    {
 372       "header" : {action : "unban", version : 3},
 373       "cookie" : "LKJDLAKSJBFLKASN"
 374       "ip" : "192.168.1.2"
 375    }
 376
 377 s -> c
 378    <ok>
 379 ou
 380    <error>
 381
 382
 383 === Ajout d'une correction d'un messages ===
 384 Le client envoie un correctif sous la forme de texte supplémentaire à appondre au dernier messages.
 385 Le message est appondu avec un " +++ " devant, par exemple :
 386 > Gnome c'est mieux que KDE +++ Euh non ok, c'est faux
 387
 388 c -> s
 389    {
 390       "header" : {action : "correction", version : 3},
 391       "cookie" : "LKJDLAKSJBFLKASN",
 392       "content" : "Euh non ok, c'est faux"
 393    }
 394
 395 s -> c
 396    {
 397       "reply" : "correction",
 398       "status" : "ok" | "error",
 399       "message_error" : "blabla"
 400    }