MOD amélioration de la mise en évidence des messages FIX#32
[euphorik.git] / 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       "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",
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    }