Browse code

Create yab.md

Stéphane THOMAS authored on 08/06/2017 18:25:34 • GitHub committed on 08/06/2017 18:25:34
Showing 1 changed files
... ...
@@ -20,13 +20,51 @@ The client (aka [coincoin](../ontology/coincoin.md)) is written in pure Javascri
20 20
 
21 21
 Any visitor can post to the tribune but one can identify, to "sign" its posts, if he wants to do so.
22 22
 
23
-Yab uses a very simple cookie authentication : every visitor is given a unique visitor id, he can associate a username of its choice. This username will then be used as "login" field instead of the default username associated with the visitor id (which is simply a hash of it). When a username has been set for a particular visitor id, only this visitor will be able to change it.
23
+Yab uses a very simple cookie authentication : every visitor is given a unique visitor id (VID), he can associate a username of its choice. This username will then be used as "login" field instead of the default username associated with the visitor id (which is simply a hash of it). When a username has been set for a particular visitor id, only this visitor will be able to change it.
24 24
 
25 25
 The visitor id isn’t stored on the server (only a hash), so losing the cookie means losing the related identity. In other terms, there is no way to recover it, using a password or some other method. It may be an future feature but it’s not a priority. In case a user wants to use the same identity from different terminals he has to manually copy the cookie by himself.
26 26
 
27
-By default visitor ids assigned to clients by the server are 2048 random alphanumeric strings, but there is no policy on what a client can send as its visitor id. As we’ll see in the next part, the only limitation that applies on messages is the total size of the post data (info+id+message).
27
+By default, visitor ids assigned to clients by the server are 2048 random alphanumeric strings, but there is no policy on what a client can send as its visitor id. As we’ll see in the next part, the only limitation that applies on messages is the total size of the post data (info+id+message).
28 28
 
29 29
 ## Messages
30 30
 
31
+The server uses non blocking read on the socket. Every 300ms it sends new posts (if any) to the client. All messages have the same format : the first character is a capital letter which indicate the message type, the second character is ':' and the remaining of the message is a variable number of fields separated by null characters. In the descriptions below, messages from server to client are marked with ↓ and messages from client to server marked with ↑. NUL is noted '^@'
31 32
 
33
+Let’s detail:
32 34
 
35
+So… chronologically, on client first connection, if we consider the client has no VID cookie yet (it’s a new visitor), the server will start the chat by sending a "Cookie" message that looks like this (the value has been truncated in the following examples):
36
+
37
+↓    `C:4abfd94ec5835b98e4c5b210305f89c569b7a18…30c27aea2ddf624f2af89b72112bc6d2913fd^@Sat Apr 15 19:14:17 2119`
38
+
39
+no surprise here… it will make the client write a cookie, named 'VID', the value is a 2048 long random string and it expires in roughly hundred years.
40
+
41
+Now our client has a cookie. When a client has a cookie it sends a "Who" message to the server when it connects:
42
+
43
+↑    `W:4abfd94ec5835b98e4c5b210305f89c569b7a18…30c27aea2ddf624f2af89b72112bc6d2913fd`
44
+
45
+yes, it just sends the cookie value.
46
+
47
+If it’s the first client connection its 'last id' value is 0, so the server will send all posts it has and update 'last id' to the id of the last post sent. "Post" messages look like this:
48
+
49
+↓    `P:14^@20170608194433^@Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.96 Safari/537.36^@d6bed91c9c95477d007b1c95df01f629023b6b4248241e09200b7e8e558ff27b^@plop`
50
+
51
+here coincoin’s developpers will recognize a standard post. We have the following fields:
52
+
53
+ 1. ID is 14 (this is an integer primary key)
54
+ 2. Time of the post is 20170608194433 (this is the historical "norloge" _(not a typo)_ format, a very convenient time representation, which combines facility to parse with facility for a human to read it)
55
+ 3. Commonly referred as "info", it’s by tradition filled with the [UA string](https://en.wikipedia.org/wiki/User_agent) of the client
56
+ 4. The "login" field. Here we can see this post was sent by an anonymous visitor because it’s a hash (registred usernames may not be longer than 32 characters…). If the post would have been posted by an authenticated user we would find its username in this field.
57
+ 5. The actual message
58
+ 
59
+ When a client sends a post it sends this kind of message, the "New" message:
60
+ 
61
+ ↑    `N:Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.96 Safari/537.36^@4abfd94ec5835b98e4c5b210305f89c569b7a18…30c27aea2ddf624f2af89b72112bc6d2913fd^@Coucou`
62
+
63
+Of course the server would immediatly send back a "Post" message again with this post it just received, as it’s new (the post id is higher than last id).
64
+
65
+There are other kind of messages but those are the core ones.
66
+
67
+# Références
68
+
69
+    Horloge '(@[0-9]{1,16})'
70
+    User    '(@[A-zÀ-ÿ][A-zÀ-ÿ0-9_-]{1,32})'