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