messages.asciidoc

 = Yab messages
 
+Yab uses messages to communicate between client and server.
+
+Messages always start with a letter, which indicates the type of message, followed by ':', then followed by a variable number of NUL separated fields. 
+
 == Client to server
 
 === Post
 
-    N:<info>^@<username>^@<message>
+Post a new message to the board. _userID_ is the cookie value 'VID'. _message_ can be anything…
+
+    N:<username>^@<userID>^@<message>
 
 === Update username
 
+Register a username for the given userID.
+
+Username must not start with a digit but may be any letter/digit (also '-' and '_'). Length must be between 2 and 64 characters (UTF-8).
+
+    U:<userID>^@<username>
+
 === Get profile
 
+Send our userID, the server will respond with our profile.
+
+    W:<userID>
+
 === Query
 
+Various other operations can use the following kind of message (see link:queries[Queries]):
+
+    Q:<userID>^@<queryID>^@<commande>^@<arg1>^@<arg2>…^@<argN>
+
 == Server to client
 
-=== New posts
+=== New post
+
+Send a new post that the client doesn’t have yet. At first application loading, existing posts in the backend are sent individually with this type of message :
+
+    P:<postID>^@<time>^@<info>^@<login>^@<message>
 
 === Set cookie
 
+Ask the client to set a cookie with his userID.
+
+Cookie value is named 'VID' and is a random 512 long hexadecimal string.
+
+Expire date is arbitrarily set to roughly 100 years in the future. This cookie value is not updated.
+
+    C:<userID>^@<expire>
+
 === Send profile
 
+Send profile to the user. This message is sent back when the client sends a "get profile" message (W:).
+
+    Y:<username>^@<capabilities>^@<last notified>
+
+Additional fields may be added in the future.
+
 === Signal error
 
+    E:<error message>
+
 === Reply to a query
+
+The following type of message is sent back as a reply to a "query" message (Q:)
+
+    R:<username>^@<queryID>^@<commande>^@<record1>^@<record2>…^@<recordN>
+
+== Rules
+
+ - server MUST reply with Y: or E: on a W: message
+ - server MUST reply with R: or E: on a W: message