Merge pull request #268721 from vicancy/patch-13

prmerger-automator[bot] · web-flow · commit ed29dcc3dff4 · 2024-03-12T13:13:19.000Z
Update reference-cloud-events.md
diff --git a/articles/azure-web-pubsub/reference-cloud-events.md b/articles/azure-web-pubsub/reference-cloud-events.md
@@ -38,7 +38,7 @@ Or:
 
 `WebHook-Allowed-Origin: xxx.webpubsub.azure.com`
 
-For now, [WebHook-Request-Rate](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#414-webhook-request-rate) and [WebHook-Request-Callback](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#413-webhook-request-callback) are not supported.
+For now, [WebHook-Request-Rate](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#414-webhook-request-rate) and [WebHook-Request-Callback](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#413-webhook-request-callback) aren't supported.
 
 
 ## Web PubSub CloudEvents attribute extension
@@ -57,12 +57,12 @@ This extension defines attributes used by Web PubSub for every event it produces
 | `connectionId` | `string` | The connectionId is unique for the client connection | |
 | `eventName` | `string` | The name of the event without prefix | |
 | `subprotocol` | `string` | The subprotocol the client is using if any | |
-| `connectionState` | `string` | Defines the state for the connection. You can use the same response header to reset the value of the state. Multiple `connectionState` headers are not allowed. Do base64 encode the string value if it contains complex characters inside, for example, you can `base64(jsonString)` to pass complex object using this attribute.| |
-| `signature` | `string` | The signature for the upstream webhook to validate if the incoming request is from the expected origin. The service calculates the value using both primary access key and secondary access key as the HMAC key: `Hex_encoded(HMAC_SHA256(accessKey, connectionId))`. The upstream should check if the request is valid before processing it. | |
+| `connectionState` | `string` | Defines the state for the connection. You can use the same response header to reset the value of the state. Multiple `connectionState` headers aren't allowed. Do base64 encode the string value if it contains complex characters inside, for example, `base64(jsonString)` to pass complex object using this attribute.| |
+| `signature` | `string` | The signature for the upstream webhook to validate if the incoming request is from the expected origin. The service calculates the value using both primary access key and secondary access key as the `HMAC` key: `Hex_encoded(HMAC_SHA256(accessKey, connectionId))`. The upstream should check if the request is valid before processing it. | |
 
 ## Events
 
-There are two types of events, one is *blocking* events that the service waits for the response of the event to continue. One is *unblocking* events that the service doesn't wait for the response of such event before processing the next message.
+There are two types of events. One is *blocking* events that the service waits for the response of the event to continue. One is *unblocking* events that the service doesn't wait for the response of such event before processing the next message.
 
 - Blocking events
     - [System `connect` event](#connect)
@@ -111,11 +111,29 @@ ce-eventName: connect
 ```
 
 #### Success response format:
+* Header `ce-connectionState`: If this header exists, the connection state of this connection will be updated to the value of the header. Only *blocking* events can update the connection state. The below sample uses base64 encoded JSON string to store the complex state for the connection.
+
 * Status code:
     * `204`: Success, with no content.
     * `200`: Success, the content SHOULD be a JSON format, with following properties allowed:
-* Header `ce-connectionState`: If this header exists, the connection state of this connection will be updated to the value of the header. Please note that only *blocking* events can update the connection state. The below sample uses base64 encoded JSON string to store the complex state for the connection.
-*
+        * `subprotocols`
+
+            The `connect` event forwards the subprotocol and authentication information to Upstream from the client. Web PubSub service uses the status code to determine if the request will be upgraded to WebSocket protocol.
+
+            If the request contains the `subprotocols` property, the server should return one subprotocol it supports. If the server doesn't want to use any subprotocols, it should **not** send the `subprotocol` property in response. [Sending a blank header is invalid](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#Subprotocols).
+
+        * `userId`: `{auth-ed user ID}`
+
+            As the service allows anonymous connections, it's the `connect` event's responsibility to tell the service the user ID of the client connection. The service reads the user ID from the response payload `userId` if it exists. The connection is dropped if the user ID can't be read from the request claims nor the `connect` event's response payload.
+
+        * `groups`: `{groups to join}`
+
+            The property provides a convenient way for user to add this connection to one or multiple groups. In this way, there's no need to have another call to add this connection to some group.
+
+        * `roles`: `{roles the client has}`
+        
+            The property provides a way for the upstream Webhook to authorize the client.   There are different roles to grant initial permissions for PubSub WebSocket clients. Details about the permissions are described in [Client permissions](./concept-client-protocols.md#permissions).
+
 ```HTTP
 HTTP/1.1 200 OK
 ce-connectionState: eyJrZXkiOiJhIn0=
@@ -129,26 +147,6 @@ ce-connectionState: eyJrZXkiOiJhIn0=
 
 ```
 
-* `subprotocols`
-
-    The `connect` event forwards the subprotocol and authentication information to Upstream from the client. Web PubSub service uses the status code to determine if the request will be upgraded to WebSocket protocol.
-
-    If the request contains the `subprotocols` property, the server should return one subprotocol it supports. If the server doesn't want to use any subprotocols, it should **not** send the `subprotocol` property in response. [Sending a blank header is invalid](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#Subprotocols).
-
-* `userId`: `{auth-ed user ID}`
-
-    As the service allows anonymous connections, it's the `connect` event's responsibility to tell the service the user ID of the client connection. The service will read the user ID from the response payload `userId` if it exists. The connection will be dropped if the user ID cannot be read from the request claims nor the `connect` event's response payload.
-
-<a name="connect_response_header_group"></a>
-
-* `groups`: `{groups to join}`
-
-    The property provides a convenient way for user to add this connection to one or multiple groups. In this way, there's no need to have another call to add this connection to some group.
-
-* `roles`: `{roles the client has}`
-
-    The property provides a way for the upstream Webhook to authorize the client.   There are different roles to grant initial permissions for PubSub WebSocket clients. Details about the permissions are described in [Client permissions](./concept-client-protocols.md#permissions).
-
 #### Error response format:
 
 * `4xx`: Error, the response from Upstream will be returned as the response for the client request.
@@ -184,7 +182,7 @@ ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-sec
 ce-userId: {userId}
 ce-connectionId: {connectionId}
 ce-hub: {hub}
-ce-eventName: connect
+ce-eventName: connected
 ce-subprotocol: abc
 ce-connectionState: eyJrZXkiOiJhIn0=
 
@@ -196,7 +194,7 @@ ce-connectionState: eyJrZXkiOiJhIn0=
 
 `2xx`: success response.
 
-`connected` is an asynchronous event, when the response status code is not success, the service logs an error.
+`connected` is an asynchronous event, when the response status code isn't success, the service logs an error.
 
 ```HTTP
 HTTP/1.1 200 OK
@@ -227,7 +225,7 @@ ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-sec
 ce-userId: {userId}
 ce-connectionId: {connectionId}
 ce-hub: {hub}
-ce-eventName: disconnect
+ce-eventName: disconnected
 ce-subprotocol: abc
 ce-connectionState: eyJrZXkiOiJhIn0=
 
@@ -246,7 +244,7 @@ ce-connectionState: eyJrZXkiOiJhIn0=
 
 `2xx`: success response.
 
-`disconnected` is an asynchronous event, when the response status code is not success, the service logs an error.
+`disconnected` is an asynchronous event, when the response status code isn't success, the service logs an error.
 
 ```HTTP
 HTTP/1.1 200 OK
@@ -293,7 +291,7 @@ UserPayload
     * `200`: Success, the format of the `UserResponsePayload` depends on the `Content-Type` of the response.
 * `Content-Type`: `application/octet-stream` for binary frame; `text/plain` for text frame;
 * Header `Content-Type`: `application/octet-stream` for binary frame; `text/plain` for text frame;
-* Header `ce-connectionState`: If this header exists, the connection state of this connection will be updated to the value of the header. Please note that only *blocking* events can update the connection state. The below sample uses base64 encoded JSON string to store complex state for the connection.
+* Header `ce-connectionState`: If this header exists, the connection state of this connection will be updated to the value of the header. Only *blocking* events can update the connection state. The below sample uses base64 encoded JSON string to store complex state for the connection.
 
 When the `Content-Type` is `application/octet-stream`, the service sends `UserResponsePayload` to the client using `binary` WebSocket frame. When the `Content-Type` is `text/plain`, the service sends `UserResponsePayload` to the client using `text` WebSocket frame.
 
@@ -307,7 +305,7 @@ UserResponsePayload
 ```
 
 #### Error response format
-When the status code is not success, it is considered to be error response. The connection would be **dropped** if the `message` response status code is not success.
+When the status code isn't success, it's considered to be error response. The connection would be **dropped** if the `message` response status code isn't success.
 
 ### User custom event `{custom_event}` for PubSub WebSocket clients
 <a name="custom_event"></a>
@@ -434,7 +432,7 @@ UserResponsePayload
 * Status code
     * `204`: Success, with no content.
     * `200`: Success, data sending to the PubSub WebSocket client depends on the `Content-Type`;
-* Header `ce-connectionState`: If this header exists, the connection state of this connection will be updated to the value of the header. Please note that only *blocking* events can update the connection state. The below sample uses base64 encoded JSON string to store the complex state for the connection.
+* Header `ce-connectionState`: If this header exists, the connection state of this connection will be updated to the value of the header. Only *blocking* events can update the connection state. The below sample uses base64 encoded JSON string to store the complex state for the connection.
 * When Header `Content-Type` is `application/octet-stream`, the service sends `UserResponsePayload` back to the client using `dataType` as `binary` with payload base64 encoded. A sample response:
     ```json
     {
@@ -449,7 +447,7 @@ UserResponsePayload
 
 
 #### Error response format
-When the status code is not success, it is considered to be error response. The connection would be **dropped** if the `{custom_event}` response status code is not success.
+When the status code isn't success, it's considered to be error response. The connection would be **dropped** if the `{custom_event}` response status code isn't success.
 
 ## Next steps
 
