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