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       "conversations" : [{"root" : 3, "minimized" : true},
  97       "ek_master" : true | false,
  98       "ostentatious_master" : "invisible" | "light" | "heavy"
  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       "conversations" : [{"root" : 3, "minimized" : true},
 124       "ostentatious_master" : "invisible" | "light" | "heavy"
 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       "ostentatious_master" : "invisible" | "light" | "heavy"
 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    }
 197 ou
 198    {
 199       "reply" : "new_troll",
 200       "troll_id" : 123,
 201       "message_id" : 12,
 202       "content" : "Linux sera desktop ready en 2008 ?"
 203    }
 204 ou
 205    <error>
 206
 207
 208 === Wait event (page = admin) ===
 209 c -> s
 210    {
 211       "header" : {action : "wait_event", version : 3},
 212       "page" : "admin",
 213       "last_troll" : 5
 214    }
 215
 216 s -> c
 217    {
 218       "reply" : "troll_modified",
 219       "troll_id" : 3,
 220       "content" : "plop"
 221    }
 222 ou
 223 s -> c
 224    {
 225       "reply" : "troll_added",
 226       "trolls" :
 227          [
 228             {
 229                "troll_id" : 5,
 230                "content" : "plop",
 231                "author" : "<Pseudo>"
 232                "author_id" : 2
 233             }
 234          ]
 235    }
 236 ou
 237 s -> c
 238    {
 239       "reply" : "troll_deleted",
 240       "troll_id" : 2
 241    }
 242 ou
 243 indique de mettre à jour la liste d'ips
 244 s -> c
 245    {
 246       "reply" : "banned_ips_refresh"
 247    }
 248
 249
 250 === Envoie d'un troll ===
 251 c -> s
 252    {
 253       "header" : {action : "put_troll", version : 3},
 254       "cookie" : "LKJDLAKSJBFLKASN",
 255       "content" : "Un bon troll velu !"
 256    }
 257
 258 s -> c
 259    <ok>
 260 ou
 261    <error>
 262
 263
 264 === Modification d'un troll ===
 265 c -> s
 266    {
 267       "header" : {action : "mod_troll", version : 3},
 268       "cookie" : "LKJDLAKSJBFLKASN",
 269       "troll_id" : 3,
 270       "content" : "Un bon troll velu 2 !"
 271    }
 272
 273 s -> c
 274    <ok>
 275 ou
 276    <error>
 277
 278
 279 === Suppression d'un troll ===
 280 c -> s
 281    {
 282       "header" : {action : "del_troll", version : 3},
 283       "cookie" : "LKJDLAKSJBFLKASN",
 284       "troll_id" : 3
 285    }
 286
 287 s -> c
 288    <ok>
 289 ou
 290    <error>
 291
 292
 293 === Envoie message ===
 294 Le client envoie un message, le message peut répondre à un certain nombre d'autres messages.
 295 "answer_to" n'est pas obligatoire.
 296
 297 c -> s
 298    {
 299       "header" : {action : "put_message", version : 3},
 300       "cookie" : "LKJDLAKSJBFLKASN",
 301       "nick" : "Paul",
 302       "content" : "Bonjour",
 303       "answer_to" : [ 345, 532, ... ]
 304    }
 305
 306 s -> c
 307    <ok>
 308 ou
 309    <error>
 310
 311
 312 === Slapage ===
 313 c -> s
 314    {
 315       "header" : {action : "slap", version : 3},
 316       "cookie" :  "LKJDLAKSJBFLKASN",
 317       "user_id" : 67,
 318       "reason" : "blablabla"
 319    }
 320
 321 s -> c
 322    <ok>
 323 ou
 324    <error>
 325
 326
 327 === Bannissement ===
 328 c -> s
 329    {
 330       "header" : {action : "ban", version : 3},
 331       "cookie" : "LKJDLAKSJBFLKASN",
 332       "duration" : 15, // en minute
 333       "user_id" : 67,
 334       "reason" : "blablabla"
 335    }
 336
 337 s -> c
 338    <ok>
 339 ou
 340    <error>
 341
 342
 343 === Liste des ip bannis ===
 344 c -> s
 345    {
 346       "header" : {action : "list_banned_ips", version : 3},
 347       "cookie" : "LKJDLAKSJBFLKASN"
 348    }
 349
 350 s -> c
 351    {
 352       "reply" : "list_banned_ips",
 353       "list" : [
 354          {
 355             ip : "192.168.1.2",
 356             remaining_time : "1h23"
 357             users : [
 358                {
 359                   nick : "Pierre" ,
 360                   login : "pierre"
 361                }
 362             ]
 363          }
 364       ]
 365    }
 366
 367
 368 === Débannissement ===
 369 c -> s
 370    {
 371       "header" : {action : "unban", version : 3},
 372       "cookie" : "LKJDLAKSJBFLKASN"
 373       "ip" : "192.168.1.2"
 374    }
 375
 376 s -> c
 377    <ok>
 378 ou
 379    <error>
 380
 381
 382 === Ajout d'une correction d'un messages ===
 383 Le client envoie un correctif sous la forme de texte supplémentaire à appondre au dernier messages.
 384 Le message est appondu avec un " +++ " devant, par exemple :
 385 > Gnome c'est mieux que KDE +++ Euh non ok, c'est faux
 386
 387 c -> s
 388    {
 389       "header" : {action : "correction", version : 3},
 390       "cookie" : "LKJDLAKSJBFLKASN",
 391       "content" : "Euh non ok, c'est faux"
 392    }
 393
 394 s -> c
 395    {
 396       "reply" : "correction",
 397       "status" : "ok" | "error",
 398       "message_error" : "blabla"
 399    }