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