updated readme for renamed {ping}

README.md

@@ -73,9 +73,9 @@ When user's `me` topic comes online (i.e. an authenticated session attaches to `
 
 ## General considerations
 
-Timestamps are always represented as RFC 3339-formatted string with precision to milliseconds and timezone always set to UTC, e.g. `"2015-10-06T18:07:29.841Z"`.
+Timestamps are always represented as [RFC 3339](http://tools.ietf.org/html/rfc3339)-formatted string with precision to milliseconds and timezone always set to UTC, e.g. `"2015-10-06T18:07:29.841Z"`.
 
-Whenever base64 encoding is mentioned, it means base64 URL encoding with padding characters stripped, see RFC 4648.
+Whenever base64 encoding is mentioned, it means base64 URL encoding with padding characters stripped, see [RFC 4648](http://tools.ietf.org/html/rfc4648).
 
 Server-issued message IDs are base-10 sequential numbers starting at 1. They guaranteed to be unique per topic. Client-assigned message IDs are strings generated by the client. Client should make them unique at least per session. The client-assigned IDs  are not interpreted by the server, they are returned to the client as is.
 
@@ -354,12 +354,12 @@ del: {
 No special permission is needed to soft-delete messages `hard=false`. Soft-deleting messages hides them from the
 requesting user. `D` permission is needed to hard-delete messages. Only owner can delete a topic.
 
-#### `{ping}`
+#### `{note}`
 
-Client-generated notification for other clients currently attached to the topic. Pings are "fire and forget": not stored to disk and not acknowledged by the server. They are intended for ephemeral notifications, such as typing notifications and delivery receipts.
+Client-generated notification for other clients currently attached to the topic. Notes are "fire and forget": not stored to disk and not acknowledged by the server. Messages deemed invalid are silently dropped. They are intended for ephemeral notifications, such as typing notifications and delivery receipts.
 
 ```js
-ping: {
+note: {
   topic: "grp1XUtEhjv6HND", // string, topic to notify, required
   what: "kp", // string, one of "kp" (key press), "read" (read notification),
               // "rcpt" (received notification), any other string will cause
@@ -371,8 +371,8 @@ ping: {
 
 The following actions are currently recognized:
  * kp: key press, i.e. a typing notification. The client should use it to indicate that the user is composing a new message.
- * rcpt: a `{data}` message is received by the client software but not yet seen by user.
- * read: a `{data}` message is seen by the user. It implies `rcpt`.
+ * recv: a `{data}` message is received by the client software but not yet seen by user.
+ * read: a `{data}` message is seen by the user. It implies `recv`.
 
 ### Server to client messages
 
@@ -443,7 +443,7 @@ ctrl: {
       "given":"RWP" // string, granted access permission
     },
     seq: 123, // integer, server-issued id of the last {data} message
-    read: 112, // integer, ID of the message user claims through {ping} message
+    read: 112, // integer, ID of the message user claims through {note} message
               // to have read, optional
     recv: 115, // integer, like 'read', but received, optional
     public: { ... }, // application-defined data that's available to all topic
@@ -469,7 +469,7 @@ ctrl: {
       // The following fields are present only when querying 'me' topic
       topic: "grp1XUtEhjv6HND", // string, topic this subscription describes
       seq: 321, // integer, server-issued id of the last {data} message
-      read: 112, // integer, ID of the message user claims through {ping} message 
+      read: 112, // integer, ID of the message user claims through {note} message
                 // to have read, optional
       recv: 315, // integer, like 'read', but received, optional
       with: "usr2il9suCbuko", // string, if this is a P2P topic, peer's ID, optional
@@ -513,18 +513,20 @@ The `{pres}` messages are purely transient. No attempt is made to store a `{pres
 
 Timestamp is not present in `{pres}` messages.
 
-#### `{ping}`
+#### `{info}`
 
-Client-generated notification forwarded on behalf of the client.
+Forwarded client-generated notification `{note}`. Server guarantees that the message complies with this specification and that content of `topic` and `from` fields are valid. The other content is copied from the `{note}` message verbatim.
 
 ```js
-ping: {
+info: {
   topic: "grp1XUtEhjv6HND", // string, topic affected, always present
   from: "usr2il9suCbuko", // string, id of the user who published the
                           // message, always present
-  what: "read", // string, see client-side {ping}, always present
-  seq: 123, // integer, ID of the message that client has acknowledged, present for
-            // rcpt & read
+  what: "read", // string, one of "kp", "recv", "read", see client-side {note},
+                // always present
+  seq: 123, // integer, ID of the message that client has acknowledged,
+            // guaranteed 0 < read <= recv <= {ctrl.info.seq}; present for rcpt &
+            // read
 }
 ```