Update reliable protocol

Author: zackliu

articles/azure-web-pubsub/howto-develop-reliable-clients.md

@@ -12,10 +12,27 @@ ms.date: 12/15/2021
 
 Websocket client connections may drop due to intermittent network issue and when connections drop, messages will also be lost. In a pubsub system, publishers are decoupled from subscribers, so publishers hard to detect subscribers' drop or message loss. It's crucial for clients to overcome intermittent network issue and keep the reliability of message delivery. To achieve that, you can create a reliable Websocket client with the help of reliable subprotocols.
 
+> [!NOTE]
+> Reliable protocols are still in preview. Some changes are expected in future.
+
 ## Reliable Protocol
 
 Service supports two reliable subprotocols `json.reliable.webpubsub.azure.v1` and `protobuf.reliable.webpubsub.azure.v1`. Clients must follow the protocol, mainly including the part of reconnection, publisher and subscriber to achieve the reliability, or the message delivery may not work as expected or the service may terminate the client as it violates the protocol spec.
 
+## Initialization
+
+To use reliable subprotocols, you must set subprotocol when constructing Websocket connections. In JavaScript, you can use as following:
+
+- Use Json reliable subprotocol
+    ```js
+    var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.reliable.webpubsub.azure.v1');
+    ```
+
+- Use Protobuf reliable subprotocol
+    ```js
+    var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'protobuf.reliable.webpubsub.azure.v1');
+    ```
+
 ## Reconnection
 
 Websocket connections relay on TCP, so if the connection doesn't drop, all messages should be lossless and in order. When facing network issue and connections drop, all the status such as group and message info are kept by the service and wait for reconnection to recover. A Websocket connection owns a session in the service and the identifier is `connectionId`. Reconnection is the basis of achieving reliability and must be implemented. When a new connection connects to the service using reliable subprotocols, the connection will receive a `Connected` message contains `connectionId` and `reconnectionToken`.
@@ -65,7 +82,7 @@ A sample ack response:
 
 If the service returns ack with `success: true`, the message has been processed by the service and the client can expect the message will be delivered to all subscribers.
 
-However, In some cases, Service meets some transient internal error and the message can't be sent to subscriber. In such case, publisher will receive an ack like following and should resend message with the same `ackId`.
+However, In some cases, Service meets some transient internal error and the message can't be sent to subscriber. In such case, publisher will receive an ack like following and should resend message with the same `ackId` if it's necessary based on business logic.
 
 ```json
 {
@@ -81,7 +98,7 @@ However, In some cases, Service meets some transient internal error and the mess
 
 ![Message Failure](./media/howto-develop-reliable-clients/message-failed.png)
 
-Service's ack may be dropped because of WebSockets connection dropped. So, publishers should wait for ack with timeout, and resend message with the same message-id after timeout. If the message has actually processed by the service, it will response ack with `Duplicate` and publishers should stop resending this message again.
+Service's ack may be dropped because of WebSockets connection dropped. So, publishers should get notified when Websocket connection drops and resend message with the same `ackId` after reconnection. If the message has actually processed by the service, it will response ack with `Duplicate` and publishers should stop resending this message again.
 
 ```json
 {
@@ -99,16 +116,16 @@ Service's ack may be dropped because of WebSockets connection dropped. So, publi
 
 ## Subscriber
 
-Clients who receive messages sent from event handlers or publishers are called subscriber in the document. When connections drop by network issues, the service doesn't know how many messages are actually sent to subscribers. So subscribers should tell the service which message has been received. Messages send to subscribers contains `sequenceId` and subscribers must ack the sequence-id with sequence ack message:
+Clients who receive messages sent from event handlers or publishers are called subscriber in the document. When connections drop by network issues, the service doesn't know how many messages are actually sent to subscribers. So subscribers should tell the service which message has been received. Data Messages contains `sequenceId` and subscribers must ack the sequence-id with sequence ack message:
 
 A sample sequence ack:
 ```json
 {
-    "type": "ack",
+    "type": "sequenceAck",
     "sequenceId": 1
 }
 ```
 
-The sequence-id is a uint64 incremental number with-in a connection-id session. And don't expect the number must be consecutive. Subscribers should record the largest sequence-id it ever received and accept all messages with larger sequence-id and drop all messages with smaller or equal sequence-id. The sequence ack supports quick ack, which means if you ack `sequence-id=5`, the service will treat all messages with sequence-id smaller than 5 have already been received by subscribers. Subscribers should ack with the largest sequence-id it recorded, so that the service can skip redelivering messages that subscribers have already received.
+The sequence-id is a uint64 incremental number with-in a connection-id session. Subscribers should record the largest sequence-id it ever received and accept all messages with larger sequence-id and drop all messages with smaller or equal sequence-id. The sequence ack supports selective ack, which means if you ack `sequence-id=5`, the service will treat all messages with sequence-id smaller than 5 have already been received by subscribers. Subscribers should ack with the largest sequence-id it recorded, so that the service can skip redelivering messages that subscribers have already received.
 
 All messages are delivered to subscribers in order until the WebSockets connection drops. With sequence-id, the service can have the knowledge about how many messages subscribers have actually received across WebSockets connections with-in a connection-id session. After a WebSockets connection drop, the service will redeliver messages it should deliver but not ack-ed by the subscriber. The service hold messages that are not ack-ed with limit, if messages exceed the limit, the service will close the WebSockets connection and remove the connection-id session. Thus, subscribers should ack the sequence-id as soon as possible.

articles/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol.md

@@ -14,6 +14,9 @@ This document describes the subprotocol `json.reliable.webpubsub.azure.v1`.
 
 When the client is using this subprotocol, both outgoing data frame and incoming data frame are expected to be **JSON** payloads.
 
+> [!NOTE]
+> Reliable protocols are still in preview. Some changes are expected in future.
+
 ## Overview
 
 Subprotocol `json.reliable.webpubsub.azure.v1` empowers the client to have a high reliable message delivery experience under network issues and do a publish-subscribe (PubSub) directly instead of doing a round trip to the upstream server. The WebSocket connection with the `json.reliable.webpubsub.azure.v1` subprotocol is called a Reliable PubSub WebSocket client.
@@ -37,7 +40,7 @@ Format:
 
 ```json
 {
-    "type": "ack",
+    "type": "sequenceAck",
     "sequenceId": "<sequenceId>",
 }
 ```
@@ -48,7 +51,7 @@ Reliable PubSub WebSocket client must send sequence ack message once it received
 
 ## Responses
 
-Messages received by the client can be several types: `ack`, `message`, and `system`. All response messages have `sequenceId` property. Client must send [Sequence Ack](#sequence-ack) to the service once it receives a message.
+Messages received by the client can be several types: `ack`, `message`, and `system`. Messages with type `message` have `sequenceId` property. Client must send [Sequence Ack](#sequence-ack) to the service once it receives a message.
 
 ### Ack response
 
@@ -57,7 +60,6 @@ If the request contains `ackId`, the service will return an ack response for thi
 Format:
 ```json
 {
-    "sequenceId": 1,
     "type": "ack",
     "ackId": 1, // The ack id for the request to ack
     "success": false, // true or false
@@ -153,7 +155,6 @@ When the connection connects to service.
 
 ```json
 {
-    "sequenceId": 1,
     "type": "system",
     "event": "connected",
     "userId": "user1",
@@ -176,7 +177,6 @@ When the server closes the connection, or when the service declines the client.
 
 ```json
 {
-    "sequenceId": 1,
     "type": "system",
     "event": "disconnected",
     "message": "reason"

articles/azure-web-pubsub/reference-protobuf-reliable-webpubsub-subprotocol.md

@@ -14,6 +14,9 @@ This document describes the subprotocol `protobuf.reliable.webpubsub.azure.v1`.
 
 When a client is using this subprotocol, both the outgoing and incoming data frames are expected to be protocol buffers (protobuf) payloads.
 
+> [!NOTE]
+> Reliable protocols are still in preview. Some changes are expected in future.
+
 ## Overview
 
 Subprotocol `protobuf.reliable.webpubsub.azure.v1` empowers the client to have a high reliable message delivery experience under network issues and do a publish-subscribe (PubSub) directly instead of doing a round trip to the upstream server. The WebSocket connection with the `protobuf.reliable.webpubsub.azure.v1` subprotocol is called a Reliable PubSub WebSocket client.
@@ -53,6 +56,7 @@ message UpstreamMessage {
         string group = 1;
         optional uint64 ack_id = 2;
         MessageData data = 3;
+        optional bool no_echo = 4;
     }
 
     message EventMessage {
@@ -109,7 +113,6 @@ message DownstreamMessage {
         uint64 ack_id = 1;
         bool success = 2;
         optional ErrorMessage error = 3;
-        uint64 sequence_id = 4;
     
         message ErrorMessage {
             string name = 1;
@@ -134,18 +137,16 @@ message DownstreamMessage {
             string connection_id = 1;
             string user_id = 2;
             string reconnection_token = 3;
-            uint64 sequence_id = 4;
         }
 
         message DisconnectedMessage {
             string reason = 2;
-            uint64 sequence_id = 3;
         }
     }
 }
 ```
 
-Messages received by the client can be in any of three types: `ack`, `message`, or `system`. All response messages have `sequence_id` property. Client must send [Sequence Ack](#sequence-ack) to the service once it receives a message.
+`AckMessage` has `sequence_id` property. Client must send [Sequence Ack](#sequence-ack) to the service once it receives a message.
 
 ### Ack response