Merge pull request #175768 from zackliu/ackidrefactor

[WebPubSub] Update client-protocols to add ack related content

Author: PMEds28

articles/azure-web-pubsub/concept-client-protocols.md

@@ -86,6 +86,47 @@ As you likely noticed in the earlier PubSub WebSocket client description, a clie
 | `webpubsub.sendToGroup.<group>` | The client can publish messages to group `<group>`. |
 | | |
 
+## AckId and Ack Response
+
+The PubSub WebSocket Client supports `ackId` property for `joinGroup`, `leaveGroup`, `sendToGroup` and `event` messages. When using `ackId`, you can receive an ack response message when your request is processed. You can choose to omit `ackId` in fire-and-forget scenarios. In the article, we describe the behavior differences between specifying `ackId` or not.
+
+### Behavior when No `ackId` specified
+
+If `ackId` is not specified, it's fire-and-forget. Even there're errors when brokering messages, you have no way to get notified.
+
+### Behavior when `ackId` specified
+
+#### Idempotent publish
+
+`ackId` is a uint64 number and should be unique within a client with the same connection id. Web PubSub Service records the `ackId` and messages with the same `ackId` will be treated as the same message. The service refuses to broker the same message more than once, which is useful in retry to avoid duplicated messages. For example, if a client sends a message with `ackId=5` and fails to receive an ack response with `ackId=5`, then the client retries and sends the same message again. In some cases, the message is already brokered and the ack response is lost for some reason, the service will reject the retry and response an ack response with `Duplicate` reason.
+
+#### Ack Response
+
+Web PubSub Service sends ack response for each request with `ackId`.
+
+Format:
+```json
+{
+    "type": "ack",
+    "ackId": 1, // The ack id for the request to ack
+    "success": false, // true or false
+    "error": {
+        "name": "Forbidden|InternalServerError|Duplicate",
+        "message": "<error_detail>"
+    }
+}
+```
+
+* The `ackId` associates the request.
+
+* `success` is a bool and indicate whether the request is successfully processed by the service. If it is `false`, clients need to check the `error`.
+
+* `error` only exists when `success` is `false` and clients should have different logic for different `name`. You should suppose there might be more type of `name` in future.
+    - `Forbidden`: The client doesn't have the permission to the request. The client needs to be added relevant roles.
+    - `InternalServerError`: Some internal error happened in the service. Retry is required.
+    - `Duplicate`: The message with the same `ackId` has been already processed by the service.
+
+
 For more information about the JSON subprotocol, see [JSON subprotocol](./reference-json-webpubsub-subprotocol.md).
 
 For more information about the protobuf subprotocol, see [Protobuf subprotocol](./reference-protobuf-webpubsub-subprotocol.md).

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

@@ -49,11 +49,11 @@ Format:
 {
     "type": "joinGroup",
     "group": "<group_name>",
-    "ackId" : 1 // optional
+    "ackId" : 1
 }
 ```
 
-* `ackId` is optional, it's an incremental integer for this command message. When the `ackId` is specified, the service sends a [ack response message](#ack-response) back to the client when the command is executed.
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](./concept-client-protocols.md#ackid-and-ack-response)
 
 ### Leave groups
 
@@ -63,11 +63,11 @@ Format:
 {
     "type": "leaveGroup",
     "group": "<group_name>",
-    "ackId" : 1 // optional
+    "ackId" : 1
 }
 ```
 
-* `ackId` is optional, it's an incremental integer for this command message. When the `ackId` is specified, the service sends a [ack response message](#ack-response) back to the client when the command is executed.
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](./concept-client-protocols.md#ackid-and-ack-response)
 
 ### Publish messages
 
@@ -77,14 +77,14 @@ Format:
 {
     "type": "sendToGroup",
     "group": "<group_name>",
-    "ackId" : 1, // optional
+    "ackId" : 1,
     "noEcho": true|false,
     "dataType" : "json|text|binary",
     "data": {}, // data can be string or valid json token depending on the dataType 
 }
 ```
 
-* `ackId` is optional, it's an incremental integer for this command message. When the `ackId` is specified, the service sends a [ack response message](#ack-response) back to the client when the command is executed.
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](./concept-client-protocols.md#ackid-and-ack-response)
 * `noEcho` is optional. If set to true, this message is not echoed back to the same connection. If not set, the default value is false.
 * `dataType` can be one of `json`, `text`, or `binary`:
      * `json`: `data` can be any type that JSON supports and will be published as what it is; If `dataType` isn't specified, it defaults to `json`.
@@ -97,7 +97,8 @@ Format:
     "type": "sendToGroup",
     "group": "<group_name>",
     "dataType" : "text",
-    "data": "text data" 
+    "data": "text data",
+    "ackId": 1
 }
 ```
 
@@ -146,7 +147,8 @@ Format:
     "type": "sendToGroup",
     "group": "<group_name>",
     "dataType" : "binary",
-    "data": "<base64_binary>"
+    "data": "<base64_binary>",
+    "ackId": 1
 }
 ```
 
@@ -170,11 +172,14 @@ Format:
 {
     "type": "event",
     "event": "<event_name>",
+    "ackId": 1,
     "dataType" : "json|text|binary",
     "data": {}, // data can be string or valid json token depending on the dataType 
 }
 ```
 
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](./concept-client-protocols.md#ackid-and-ack-response)
+
 `dataType` can be one of `text`, `binary`, or `json`:
 * `json`: data can be any type json supports and will be published as what it is; If `dataType` is not specified, it defaults to `json`.
 * `text`: data should be in string format, and the string data will be published;
@@ -185,6 +190,7 @@ Format:
 {
     "type": "event",
     "event": "<event_name>",
+    "ackId": 1,
     "dataType" : "text",
     "data": "text data", 
 }
@@ -218,6 +224,7 @@ text data
 {
     "type": "event",
     "event": "<event_name>",
+    "ackId": 1,
     "dataType" : "json",
     "data": {
         "hello": "world"
@@ -255,6 +262,7 @@ ce-eventName: <event_name>
 {
     "type": "event",
     "event": "<event_name>",
+    "ackId": 1,
     "dataType" : "binary",
     "data": "base64_binary", 
 }
@@ -302,7 +310,7 @@ Format:
     "ackId": 1, // The ack id for the request to ack
     "success": false, // true or false
     "error": {
-        "name": "NotFound|Forbidden|Timeout|InternalServerError",
+        "name": "Forbidden|InternalServerError|Duplicate",
         "message": "<error_detail>"
     }
 }

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

@@ -64,23 +64,24 @@ message UpstreamMessage {
 
     message SendToGroupMessage {
         string group = 1;
-        optional int32 ack_id = 2;
+        optional uint64 ack_id = 2;
         MessageData data = 3;
     }
 
     message EventMessage {
         string event = 1;
         MessageData data = 2;
+        optional uint64 ack_id = 3;
     }
     
     message JoinGroupMessage {
         string group = 1;
-        optional int32 ack_id = 2;
+        optional uint64 ack_id = 2;
     }
 
     message LeaveGroupMessage {
         string group = 1;
-        optional int32 ack_id = 2;
+        optional uint64 ack_id = 2;
     }
 }
 
@@ -99,21 +100,21 @@ Format:
 
 Set `join_group_message.group` to the group name.
 
-* `ackId` is optional. It's an incremental integer for this command message. If you specify `ackId`, the service sends an [ack response message](#ack-response) back to the client when the command is executed.
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](./concept-client-protocols.md#ackid-and-ack-response)
 
 ### Leave groups
 
 Format:
 
 Set `leave_group_message.group` to the group name.
 
-* `ackId` is optional. It's an incremental integer for this command message. If you specify `ackId`, the service sends an [ack response message](#ack-response) back to the client when the command is executed.
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](./concept-client-protocols.md#ackid-and-ack-response)
 
 ### Publish messages
 
 Format:
 
-* `ackId` is optional. It's an incremental integer for this command message. If you specify `ackId`, the service sends an [ack response message](#ack-response) back to the client when the command is executed.
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](./concept-client-protocols.md#ackid-and-ack-response)
 
 There's an implicit `dataType`, which can be `protobuf`, `text`, or `binary`, depending on the `data` in `MessageData` you set. The receiver clients can use `dataType` to handle the content correctly.
 
@@ -342,7 +343,7 @@ message DownstreamMessage {
     }
     
     message AckMessage {
-        int32 ack_id = 1;
+        uint64 ack_id = 1;
         bool success = 2;
         optional ErrorMessage error = 3;