Azure Web PubSub Reliable JSON WebSocket subprotocol
The JSON WebSocket subprotocol, json.reliable.webpubsub.azure.v1
, enables the highly reliable exchange of publish/subscribe messages directly between clients through the service without a round trip to the upstream server.
This document describes the subprotocol json.reliable.webpubsub.azure.v1
.
When WebSocket client connections drop due to intermittent network issues, messages can be lost. In a pub/sub system, publishers are decoupled from subscribers and may not detect a subscribers' dropped connection or message loss.
To overcome intermittent network issues and maintain reliable message delivery, you can use the Azure WebPubSub json.reliable.webpubsub.azure.v1
subprotocol to create a Reliable PubSub WebSocket client.
A Reliable PubSub WebSocket client can:
- recover a connection from intermittent network issues.
- recover from message loss.
- join a group using join requests.
- leave a group using leave requests.
- publish messages directly to a group using publish requests.
- route messages directly to upstream event handlers using event requests.
For example, you can create a Reliable PubSub WebSocket client with the following JavaScript code:
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.reliable.webpubsub.azure.v1');
See How to create reliable clients to implement reconnection and message reliability for publisher and subscriber clients.
When the client is using this subprotocol, both outgoing and incoming data frames must contain JSON payloads.
Permissions
A PubSub WebSocket client can only publish to other clients when it's authorized. The roles
assigned to the client determine the permissions granted to the client:
Role | Permission |
---|---|
Not specified | The client can send event requests. |
webpubsub.joinLeaveGroup |
The client can join/leave any group. |
webpubsub.sendToGroup |
The client can publish messages to any group. |
webpubsub.joinLeaveGroup.<group> |
The client can join/leave the group <group> . |
webpubsub.sendToGroup.<group> |
The client can publish messages to the group <group> . |
The server can dynamically grant or revoke client permissions through REST APIs or server SDKs.
Requests
Join groups
Format:
{
"type": "joinGroup",
"group": "<group_name>",
"ackId" : 1
}
ackId
is the identity of each request and should be unique. The service sends a ack response message to notify the process result of the request. For details, see AckId and Ack Response
Leave groups
Format:
{
"type": "leaveGroup",
"group": "<group_name>",
"ackId" : 1
}
ackId
is the identity of each request and should be unique. The service sends a ack response message to notify the process result of the request. For details, see AckId and Ack Response
Publish messages
Format:
{
"type": "sendToGroup",
"group": "<group_name>",
"ackId" : 1,
"noEcho": true|false,
"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 to notify the process result of the request. For details, see AckId and Ack ResponsenoEcho
is optional. If set to true, this message isn't echoed back to the same connection. If not set, the default value is false.dataType
can be set tojson
,text
, orbinary
:json
:data
can be any type that JSON supports and will be published as what it is; IfdataType
isn't specified, it defaults tojson
.text
:data
should be in string format, and the string data will be published;binary
:data
should be in base64 format, and the binary data will be published;
Case 1: publish text data:
{
"type": "sendToGroup",
"group": "<group_name>",
"dataType" : "text",
"data": "text data",
"ackId": 1
}
- The subprotocol clients in
<group_name>
receive:
{
"type": "message",
"from": "group",
"group": "<group_name>",
"dataType" : "text",
"data" : "text data"
}
- The simple WebSocket clients in
<group_name>
receive the stringtext data
.
Case 2: publish JSON data:
{
"type": "sendToGroup",
"group": "<group_name>",
"dataType" : "json",
"data": {
"hello": "world"
}
}
- The subprotocol clients in
<group_name>
receive:
{
"type": "message",
"from": "group",
"group": "<group_name>",
"dataType" : "json",
"data" : {
"hello": "world"
}
}
- The simple WebSocket clients in
<group_name>
receive the serialized string{"hello": "world"}
.
Case 3: publish binary data:
{
"type": "sendToGroup",
"group": "<group_name>",
"dataType" : "binary",
"data": "<base64_binary>",
"ackId": 1
}
- The subprotocol clients in
<group_name>
receive:
{
"type": "message",
"from": "group",
"group": "<group_name>",
"dataType" : "binary",
"data" : "<base64_binary>",
}
- The simple WebSocket clients in
<group_name>
receive the binary data in the binary frame.
Send custom events
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 to notify the process result of the request. For details, see 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; The default isjson
.text
: data is in string format, and the string data will be published;binary
: data is in base64 format, and the binary data will be published;
Case 1: send event with text data:
{
"type": "event",
"event": "<event_name>",
"ackId": 1,
"dataType" : "text",
"data": "text data",
}
The upstream event handler receives data similar to:
POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
text data
The Content-Type
for the CloudEvents HTTP request is text/plain
when dataType
is text
.
Case 2: send event with JSON data:
{
"type": "event",
"event": "<event_name>",
"ackId": 1,
"dataType" : "json",
"data": {
"hello": "world"
},
}
The upstream event handler receives data similar to:
POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
{
"hello": "world"
}
The Content-Type
for the CloudEvents HTTP request is application/json
when dataType
is json
Case 3: send event with binary data:
{
"type": "event",
"event": "<event_name>",
"ackId": 1,
"dataType" : "binary",
"data": "base64_binary",
}
The upstream event handler receives data similar to:
POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
binary
The Content-Type
for the CloudEvents HTTP request is application/octet-stream
when dataType
is binary
. The WebSocket frame can be text
format for text message frames or UTF8 encoded binaries for binary
message frames.
The Web PubSub service declines the client if the message doesn't match the described format.
Sequence Ack
Format:
{
"type": "sequenceAck",
"sequenceId": "<sequenceId>",
}
Reliable PubSub WebSocket client must send a sequence ack message once it receives a message from the service. For more information, see How to create reliable clients
sequenceId
is an incremental uint64 number from the message received.
Responses
Messages received by the client can be several types: ack
, message
, and system
. Messages with type message
have sequenceId
property. Client must send a Sequence Ack to the service once it receives a message.
Ack response
When the request contains ackId
, the service will return an ack response for this request. The client implementation should handle this ack mechanism, including waiting for the ack response using an async
await
operation, and have a timeout handler when the ack response isn't received during a certain period.
Format:
{
"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 client implementation SHOULD always check if the success
is true
or false
first. Only when success
is false
the client reads from error
.
Message response
Clients can receive messages published from a group the client has joined or from the server, which, operating in a server management role, sends messages to specific clients or users.
The response message from a group:
{ "sequenceId": 1, "type": "message", "from": "group", "group": "<group_name>", "dataType": "json|text|binary", "data" : {} // The data format is based on the dataType "fromUserId": "abc" }
The response message from the server:
{ "sequenceId": 1, "type": "message", "from": "server", "dataType": "json|text|binary", "data" : {} // The data format is based on the dataType }
Case 1: Sending data Hello World
to the connection through REST API with Content-Type
=text/plain
A simple WebSocket client receives a text WebSocket frame with data:
Hello World
;A PubSub WebSocket client receives the message in JSON:
{ "sequenceId": 1, "type": "message", "from": "server", "dataType" : "text", "data": "Hello World", }
Case 2: Sending data { "Hello" : "World"}
to the connection through REST API with Content-Type
=application/json
A simple WebSocket client receives a text WebSocket frame with stringified data:
{ "Hello" : "World"}
;A PubSub WebSocket client receives the message in JSON:
{ "sequenceId": 1, "type": "message", "from": "server", "dataType" : "json", "data": { "Hello": "World" } }
If the REST API is sending a string Hello World
using application/json
content type, the simple WebSocket client receives the JSON string "Hello World"
wrapped in "
.
Case 3: Sending binary data to the connection through REST API with Content-Type
=application/octet-stream
A simple WebSocket client receives a binary WebSocket frame with the binary data.
A PubSub WebSocket client receives the message in JSON:
{ "sequenceId": 1, "type": "message", "from": "server", "dataType" : "binary", "data": "<base64_binary>" }
System response
The Web PubSub service can return system-related responses to the client.
Connected
The response to the client connect request:
{
"type": "system",
"event": "connected",
"userId": "user1",
"connectionId": "abcdefghijklmnop",
"reconnectionToken": "<token>"
}
connectionId
and reconnectionToken
are used for reconnection. Make connect request with uri for reconnection:
wss://<service-endpoint>/client/hubs/<hub>?awps_connection_id=<connectionId>&awps_reconnection_token=<reconnectionToken>
Find more details in Connection Recovery
Disconnected
The response when the server closes the connection or when the service declines the client connection:
{
"type": "system",
"event": "disconnected",
"message": "reason"
}
Next steps
Use these resources to start building your own application: