You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/azure-web-pubsub/concept-client-protocols.md
+95-29Lines changed: 95 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ author: vicancy
5
5
ms.author: lianwei
6
6
ms.service: azure-web-pubsub
7
7
ms.topic: conceptual
8
-
ms.date: 08/16/2021
8
+
ms.date: 11/08/2021
9
9
---
10
10
11
11
# WebSocket client protocols for Azure Web PubSub
@@ -33,7 +33,7 @@ Here is a general authorization workflow:
33
33
34
34
## The simple WebSocket client
35
35
36
-
A simple WebSocket client, as the naming indicates, is a simple WebSocket connection. It can also have its own custom subprotocol.
36
+
A **simple WebSocket client**, as the naming indicates, is a simple WebSocket connection. It can also have its own custom subprotocol.
37
37
38
38
For example, in JavaScript, you can create a simple WebSocket client by using the following code:
39
39
@@ -47,56 +47,76 @@ var client2 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', '
47
47
48
48
## The PubSub WebSocket client
49
49
50
-
The PubSub WebSocket client supports two subprotocols:
50
+
A **PubSub WebSocket client**, is the WebSocket client using subprotocols defined by the Azure Web PubSub service:
51
+
51
52
*`json.webpubsub.azure.v1`
52
53
*`protobuf.webpubsub.azure.v1`
53
54
54
-
#### The JSON subprotocol
55
+
With the service-supported subprotocol, the **PubSub WebSocket client**s can directly publish messages to groups when they have the [permissions](#permissions).
56
+
57
+
### The `json.webpubsub.azure.v1` subprotocol
55
58
56
-
For example, in JavaScript, you can create a PubSub WebSocket client with a JSON subprotocol by using:
59
+
Check [here for the JSON subprotocol in detail](reference-json-webpubsub-subprotocol.md).
60
+
61
+
#### Create a PubSub WebSocket client
57
62
58
63
```js
59
-
// PubSub WebSocket client
60
-
var pubsub =newWebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');
64
+
var pubsubClient =newWebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');
61
65
```
62
66
63
-
#### The protobuf subprotocol
67
+
#### Join a group from the client directly
68
+
69
+
```js
70
+
let ackId =0;
71
+
pubsubClient.send(
72
+
JSON.stringify({
73
+
type:'joinGroup',
74
+
group:'group1',
75
+
ackId:++ackId
76
+
}));
77
+
```
78
+
79
+
#### Send messages to a group from the client directly
80
+
81
+
```js
82
+
let ackId =0;
83
+
pubsubClient.send(
84
+
JSON.stringify({
85
+
type:'sendToGroup',
86
+
group:'group1',
87
+
ackId:++ackId,
88
+
dataType:"json",
89
+
data: {
90
+
"hello":"world"
91
+
}
92
+
}));
93
+
```
94
+
95
+
### The `protobuf.webpubsub.azure.v1` subprotocol
64
96
65
97
Protocol buffers (protobuf) is a language-neutral, platform-neutral, binary-based protocol that simplifies sending binary data. Protobuf provides tools to generate clients for many languages, such as Java, Python, Objective-C, C#, and C++. [Learn more about protobuf](https://developers.google.com/protocol-buffers).
66
98
67
-
For example, in JavaScript, you can create a PubSub WebSocket client with a protobuf subprotocol by using the following code:
99
+
For example, in JavaScript, you can create a **PubSub WebSocket client** with a protobuf subprotocol by using the following code:
68
100
69
101
```js
70
102
// PubSub WebSocket client
71
103
var pubsub =newWebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'protobuf.webpubsub.azure.v1');
72
104
```
73
105
74
-
When the client is using a subprotocol, both the outgoing and incoming data frames are expected to be JSON payloads. An authorized client can publish messages to other clients directly through the Azure Web PubSub service.
75
-
76
-
### Permissions
106
+
Check [here for the protobuf subprotocol in detail](reference-protobuf-webpubsub-subprotocol.md).
77
107
78
-
As you likely noticed in the earlier PubSub WebSocket client description, a client can publish to other clients only when it's *authorized* to do so. A client's permissions can be granted when it's being connected or during the lifetime of the connection.
79
108
80
-
| Role | Permission |
81
-
|---|---|
82
-
| Not specified | The client can send event requests. |
83
-
|`webpubsub.joinLeaveGroup`| The client can join or leave any group. |
84
-
|`webpubsub.sendToGroup`| The client can publish messages to any group. |
85
-
|`webpubsub.joinLeaveGroup.<group>`| The client can join or leave group `<group>`. |
86
-
|`webpubsub.sendToGroup.<group>`| The client can publish messages to group `<group>`. |
87
-
|||
109
+
### AckId and Ack Response
88
110
89
-
## AckId and Ack Response
111
+
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.
90
112
91
-
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.
92
-
93
-
### Behavior when No `ackId` specified
113
+
#### Behavior when No `ackId` specified
94
114
95
115
If `ackId` is not specified, it's fire-and-forget. Even there're errors when brokering messages, you have no way to get notified.
96
116
97
-
### Behavior when `ackId` specified
117
+
####Behavior when `ackId` specified
98
118
99
-
#### Idempotent publish
119
+
#####Idempotent publish
100
120
101
121
`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.
102
122
@@ -126,10 +146,56 @@ Format:
126
146
-`InternalServerError`: Some internal error happened in the service. Retry is required.
127
147
-`Duplicate`: The message with the same `ackId` has been already processed by the service.
128
148
149
+
### Permissions
129
150
130
-
For more information about the JSON subprotocol, see [JSON subprotocol](./reference-json-webpubsub-subprotocol.md).
151
+
As you likely noticed in the earlier PubSub WebSocket client description, a client can publish to other clients only when it's *authorized* to do so. A client's permissions can be granted when it's being connected or during the lifetime of the connection.
131
152
132
-
For more information about the protobuf subprotocol, see [Protobuf subprotocol](./reference-protobuf-webpubsub-subprotocol.md).
153
+
| Role | Permission |
154
+
|---|---|
155
+
| Not specified | The client can send event requests. |
156
+
|`webpubsub.joinLeaveGroup`| The client can join or leave any group. |
157
+
|`webpubsub.sendToGroup`| The client can publish messages to any group. |
158
+
|`webpubsub.joinLeaveGroup.<group>`| The client can join or leave group `<group>`. |
159
+
|`webpubsub.sendToGroup.<group>`| The client can publish messages to group `<group>`. |
160
+
|||
161
+
162
+
The permission of a client can be granted in several ways:
163
+
164
+
#### 1. Assign the role to the client when generating the access token
165
+
166
+
Client can connect to the service using a JWT token, the token payload can carry information such as the `role` of the client. When signing the JWT token to the client, you can grant permissions to the client by giving the client specific roles.
167
+
168
+
For example, let's sign a JWT token that has the permission to send messages to `group1` and `group2`:
169
+
170
+
```js
171
+
let token =awaitserviceClient.getClientAccessToken({
#### 2. Assign the role to the client with the `connect` event handler
177
+
178
+
The roles of the clients can also be set when the `connect` event handler is registered and the upstream event handler can return the `roles` of the client to the Web PubSub service when handling the `connect` events.
179
+
180
+
For example, in JavaScript, you can configure the `handleConnect` event to do so:
181
+
182
+
```js
183
+
let handler =newWebPubSubEventHandler("hub1", {
184
+
handleConnect: (req, res) => {
185
+
// auth the connection and set the userId of the connection
0 commit comments