2eb81a62ded3883bcc676bb78f6185f4654a0339
[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 : "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    }