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