Updated ii-doc

ii-doc.txt

@@ -11,10 +11,10 @@ Clients aka points can:
 * fetch messages by their IDs
 
 Nodes aka stations can:
-* accept (or not accept) posted messages from points
+* accept (or reject) posted messages from points
 * serve echo lists
-* serve echos and their message ID lists
+* serve echos and their indexes (message ID lists)
-* serve message bundles
+* serve message bundles or single messages
 * fetch echos and messages from other stations
 
 The main transport protocol is currently HTTP/HTTPS, although the spec doesn't
@@ -27,26 +27,44 @@ Echo and message naming convention
 ----------------------------------
 Within the network, echo names must be from 3 to 120 characters long and have
 at least one dot (.) character. Message IDs must be exactly 20 characters long
-and depend on the message contents hash (see the exact algorithm below).
+and depend on the message contents hash upon posting (see the exact algorithm
+below in the "Message ID generation algorithm" section).
 
-Station (node) HTTP API (as implemented in tii)
+Station (node) HTTP API
------------------------------------------------
+-----------------------
 Every station must implement the following HTTP API calls.
 In case of multi-line responses, the newline separator must be "\n" character
 (line feed, ASCII 10).
+All station responses must end with a newline separator.
 
 - Fetching the public echo list -
 
 Request: GET /list.txt
 Response: newline-separated list of echo_name:msg_count:echo_description
 
-Note: msg_count must not decrease even if some messages are deleted.
+Note: the msg_count field must reflect the actual non-blacklisted message
-Some nodes (e.g. ii-php) still can violate this rule, so the message count
+count that the station can serve.
-reported by nodes still should not be the basis for any client-side logic.
 
-- Listing messages in the echo(s) -
+- Fetching the public message blacklist -
+
+Request: GET /blacklist.txt
+Response: newline-separated list of message IDs
+
+The blacklisted message IDs must not be served to the clients in any of the
+API calls specified below.
+
+- Listing messages in a single echo -
+
+Request: GET /e/echo.name
+Response: newline-separated message ID list
+
+When a new message is posted to the echo, it gets appended to the end of the
+corresponding message ID list for this echo.
+
+- Listing messages in any amount of echos -
 
 Request: GET /u/e/echo.1.name/echo.2.name/...
+Limited request: GET /u/e/echo.1.name/echo.2.name/.../offset:limit
 Response: newline-separated list of echo names and message IDs in the format:
 
 echo.1.name
@@ -58,38 +76,56 @@ msgid1fromecho2
 msgid2fromecho2
 ...
 
-When a new message is posted to the echo, it gets appended to the end of the
+In case of limited request, the offset can be negative. E.g. -10:10 means
-corresponding message ID list for this echo.
+requesting last 10 messages from the index.
 
-- Fetching the message bundles -
+- Fetching a single message by its ID -
+
+Request: GET /m/msgid
+Response: plaintext message in the Node-to Point Message format
+
+- Fetching a message bundle -
 
 Request: GET /u/m/msgid1/msgid2/...
 Response: newline-separated list of msgid:base64_msgtext
 
-where base64_msgtext is a Base64-encoded Node-to-Point Message (see below).
+Here, base64_msgtext is a Base64-encoded Node-to-Point Message (see below).
 
 - Posting a message (via POST) -
 
 Request: POST /u/point
 Content-Type: application/x-www-form-urlencoded 
 Data: pauth=auth_string&tmsg=base64_msgtext
-Response: in case of success, must start with "msg ok"
+Response: in case of success, must start with "msg ok", otherwise with "error"
 
-where base64_msgtext is the Base64-encoded Point-to-Node Message (see below).
+Here, auth_string is the user's authorization string and base64_msgtext is the
+Base64-encoded Point-to-Node Message (see below).
 The maximum length of the tmsg field must be 87382 bytes.
 
 - Posting a message (via GET) -
 
 Request: GET /u/point/auth_string/base64_msgtext
-Response: in case of success, must start with "msg ok"
+Response: in case of success, must start with "msg ok", otherwise with "error"
 
-where base64_msgtext is the Base64URL-encoded Point-to-Node Message.
+Here, auth_string is the user's authorization string and base64_msgtext is the
+Base64URL-encoded Point-to-Node Message.
 The maximum length of the tmsg field must be 87382 bytes.
 
 Note: the Base64URL encoding means that after the standard Base64 encoding,
 the + character is replaced with -, the / character is replaced with _, and
 the = character is omitted from the end.
 
+- Pushing a message bundle to another node -
+
+Request: POST /u/push
+Content-Type: application/x-www-form-urlencoded
+Data: nauth=auth_string&upush=bundle_contents&echoarea=echo.name
+Response: in case of success, must start with "message saved: ok", otherwise
+          with "error:"
+
+Here, auth_string is the node authorization string and bundle_contents is the
+message bundle in the exact format as received by GET /u/m API method.
+
 Node-to-Point Message format
 ----------------------------
 The encoding must be UTF-8 and the newline separator must be "\n" (ASCII 10).
@@ -140,9 +176,6 @@ Implementation notes
 * Most HTTP servers are configured to reject long GET lines, so tii passes a
   limited amount of message IDs to the /u/m endpoints. This behaviour can be
   configured in the stations.txt file.
-* Some of the crucial validations are for message IDs to be 20 lines and for
-  all messages (Node-to-Point and Point-to-Node) to strictly have LF line
-  endings, not CRLF.
 * The message order in an echo does not always match the timestamp ordering;
   it is fully up to the client on how to sort the messages internally. The
   messages are only guaranteed to be saved by the server in the order they