Update

Author: Y-Sindo

articles/azure-web-pubsub/howto-connect-mqtt-websocket-client.md

@@ -1,14 +1,14 @@
 ---
-title: How to Connect MQTT Clients to Azure Web PubSub
-description: How to Connect MQTT Clients to Azure Web PubSub
+title: How to connect MQTT clients to Azure Web PubSub
+description: How to connect MQTT clients to Azure Web PubSub
 author: Y-Sindo
 ms.author: zityang
 ms.service: azure-web-pubsub
 ms.date: 06/17/2024
 ms.topic: how-to
 ---
 
-# How To connect MQTT clients to Azure Web PubSub
+# How to connect MQTT clients to Azure Web PubSub
 
 MQTT is a lightweight pub/sub messaging protocol designed for devices with constrained resources.
 
@@ -28,7 +28,7 @@ If client library doesn't accept a URI, then you probably need to split the info
 * Port: 443
 * Transport: WebSockets with [TLS](https://wikipedia.org/wiki/Transport_Layer_Security).
 
-[!INCLUDE [MQTT-Connection-Parameters](includes/mqtt-connection-Parameters.md)]
+[!INCLUDE [MQTT-Connection-parameters](includes/mqtt-connection-parameters.md)]
 
 By default MQTT clients don't have any permissions to publish or subscribe to any topics. You need to grant [permissions](#permissions) to MQTT clients.
 
@@ -45,17 +45,17 @@ A client can publish to other clients only when it's *authorized* to do so. A cl
 | `webpubsub.sendToGroup.<group>` | The client can publish messages to group `<group>`. |
 | | |
 
-## Authentication and Authorization
+## Authentication and authorization
 
 There are two workflows supported by Web PubSub to authenticate and authorize MQTT clients, so that they have proper permissions.
 
 These workflows can be used individually or in combination. If they're used in together, the auth result in the latter workflow would be honored by the service.
 
-### 1. JWT Workflow
+### 1. JWT workflow
 
 This is the default workflow, shown as follows:
 
-![Diagram of MQTT Auth Workflow With JWT.](./media/howto-connect-mqtt-websocket-client/mqtt-jwt-auth-workflow.png)
+![Diagram of MQTT auth workflow with JWT.](./media/howto-connect-mqtt-websocket-client/mqtt-jwt-auth-workflow.png)
 
 1. The client negotiates with your auth server. The auth server contains the authorization middleware, which handles the client request and signs a JWT for the client to connect to the service.
 1. The auth server returns the JWT to the client.
@@ -131,11 +131,11 @@ You could also add custom claims into the access token, and these values are pre
      ```
 ---
 
-### 2. Upstream Server Workflow
+### 2. Upstream server workflow
 
 The MQTT client sends an MQTT CONNECT packet after it establishes a WebSocket connection with the service, then the service calls an API in the upstream server. The upstream server can auth the client according to the username and password fields in the MQTT connection request, and the TLS certificate from the client.
 
-![Diagram of MQTT Auth Workflow With Upstream Server](./media/howto-connect-mqtt-websocket-client/mqtt-upstream-auth-workflow.png)
+![Diagram of MQTT auth workflow with upstream server](./media/howto-connect-mqtt-websocket-client/mqtt-upstream-auth-workflow.png)
 
 This workflow needs explicit configuration.
 * [Tutorial - Authenticate and authorize MQTT clients based on client certificates](./tutorial-upstream-auth-mqtt-client.md)

articles/azure-web-pubsub/includes/mqtt-term-mappings.md

@@ -6,7 +6,7 @@ ms.topic: include
 ms.date: 07/19/2024
 ---
 
-| MQTT Terms| Corresponding Web PubSub Terms | Relationship |
+| MQTT terms| Corresponding Web PubSub terms | Relationship |
 | --- | --- | --- |
 | Server/MQTT Broker | Web PubSub Service  |  Web PubSub service work as MQTT brokers to serve MQTT connections. Please note that we usually use the term *server* to refer to the upstream server instead of the MQTT brokers in the documents. |
 | Session | Connection  | *Connection* in Web PubSub is a logical concept that represents a stateful relationship between the client and service, and one *Connection* is corresponding to one *Session*. Usually these two words are interchangeable.  |

articles/azure-web-pubsub/media/quickstarts-pubsub-among-mqtt-clients/live-trace.png

@@ -1,5 +1,5 @@
 ---
-title: MQTT support in Azure Web PubSub Service
+title: MQTT support in Azure Web PubSub service
 description: Get an overview of Azure Web PubSub's support for the MQTT protocols, understand typical use case scenarios to use MQTT in Azure Web PubSub, and learn the key benefits of MQTT in Azure Web PubSub.
 keywords: MQTT, MQTT on Azure Web PubSub, MQTT over WebSocket
 author: Y-Sindo
@@ -21,57 +21,59 @@ You can use MQTT protocols in Web PubSub service for the following scenarios:
 > [!NOTE]
 > MQTT support in Azure Web PubSub is in preview stage.
 
-## Key Features
+## Key features
 
-### Standard MQTT Protocols Support
+### Standard MQTT protocols support
 
 Web PubSub service supports MQTT 3.1.1 and 5.0 protocols in a standard way that any MQTT SDK with WebSocket transport support can connect to Web PubSub. Users who wish to use Web PubSub in a programming language that doesn't have a native Web PubSub SDK can still connect and communicate using MQTT.
 
-### Cross-Protocol Communication
+### Cross-protocol communication
 
 MQTT clients can communicate with clients of other Web PubSub protocols. Find more details [here](./reference-mqtt-cross-protocol-communication.md)
 
-### Easy MQTT adoption for Current Web PubSub Users
+### Easy MQTT adoption for current Web PubSub users
 
 Current users of Azure Web PubSub can use MQTT protocol with minimal modifications to their existing upstream servers. The Web PubSub REST API is already equipped to handle MQTT connections, simplifying the transition process.
 
-### Client-to-Server Request/Response Model
+### Client-to-server request/response model
 
 In addition to the client-to-client pub/sub model provided by the MQTT protocols, Web PubSub also support a client-to-server request/response model. Basically Web PubSub converts a specific kind of MQTT application messages into HTTP requests to registered webhooks, and sends the HTTP responses as application messages back to the MQTT clients.
 
 For more details, see [MQTT custom event handler protocol](./reference-mqtt-cloud-events.md#user-custom_event-event).
 
-## MQTT Feature Support Status
+## MQTT feature support status
+
 Web PubSub support MQTT protocol version 3.1.1 and 5.0. The supported features include but not limited to:
 
 * All the levels of Quality Of Service including at most once, at least once and exactly once.
 * Persistent session. MQTT sessions are preserved for up to 30 seconds when client connections are interrupted.
 * Last Will & Testament
 * Client Certificate Authentication
 
-### Additional Features Supported For MQTT 5.0
+### Additional features supported for MQTT 5.0
 
 * Message Expiry Interval and Session Expiry Interval
 * Subscription Identifier.
 * Assigned Client ID.
 * Flow Control
 * Server-Sent Disconnect
 
-### Not Supported Feature
+### Not supported feature
+
 * Wildcard subscription
 * Retained messages
 * Topic alias
 * Shared subscription
 
-## How MQTT Is Adapted Into Web PubSub's System
+## How MQTT is adapted into Web PubSub's system
 
 This section assumes you have basic knowledge about MQTT protocols and Web PubSub. You can find the definitions of MQTT terms in [MQTT V5.0.0 Spec](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901003). You can also learn basic concepts of Web PubSub in [Basic Concepts](./key-concepts.md).
 
 The following table shows similar or equivalent term mappings between MQTT and Web PubSub. It helps you understand how we adapt MQTT concepts into the Web PubSub's system. It's essential if you want to use the [data-plane REST API](./reference-rest-api-data-plane.md) or [client event handlers](./howto-develop-eventhandler.md) to interact with MQTT clients.
 
 [!INCLUDE [MQTT-Term-Mappings](includes/mqtt-term-mappings.md)]
 
-## Client Authentication And Authorization
+## Client authentication and authorization
 
 In general, a server to authenticate and authorize MQTT clients is required. There are two workflows supported by Web PubSub to authenticate and authorize MQTT clients.
 
@@ -88,22 +90,23 @@ These two workflows can be used individually or in combination. If they're used
 
 For details on client authentication and authorization, see [How To Connect MQTT Clients to Web PubSub](./howto-connect-mqtt-websocket-client.md).
 
-## Client Lifetime Event Notification
+## Client lifetime event notification
 
 You can register event handlers to get notification when a Web PubSub client connection is started or ended, that is, an MQTT session started or ended.
 
 * [Event handler in Azure Web PubSub service](./howto-develop-eventhandler.md)
 * [MQTT CloudEvents Protocol](./reference-mqtt-cloud-events.md)
 
-## REST API Support
+## REST API support
 
 You can use REST API to do the following things:
+
 * Publish messages to a topic, a connection, a Web PubSub user, or all the connections.
 * Manage client permissions and subscriptions.
 
 [REST API specification for MQTT](./reference-rest-api-mqtt.md)
 
-## Event Listener Support
+## Event listener support
 
 > [!NOTE]
 > Sending MQTT client events to Event Hubs is not supported yet.
@@ -115,4 +118,3 @@ You can use REST API to do the following things:
 
 > [!div class="nextstepaction"]
 > [How To Connect MQTT Clients to Web PubSub](./howto-connect-mqtt-websocket-client.md)
-

articles/azure-web-pubsub/overview-mqtt.md

@@ -1,5 +1,5 @@
 ---
-title: Reference - CloudEvents Extension for Azure Web PubSub MQTT Event Handler with HTTP Protocol
+title: Reference - CloudEvents extension for Azure Web PubSub MQTT event handler with HTTP protocol
 description: This reference describes CloudEvents extensions for the Azure Web PubSub MQTT event handler with HTTP protocol.
 author: Y-Sindo
 ms.author: zityang

articles/azure-web-pubsub/reference-mqtt-cloud-events.md

@@ -9,25 +9,25 @@ ms.service: azure-web-pubsub
 ms.topic: reference
 ---
 
-# Cross-protocol Communication Between MQTT Clients and Web PubSub Clients
+# Cross-protocol communication between MQTT clients and Web PubSub clients
 
 Sometimes you'd like to have MQTT clients and other clients using Azure Web PubSub's protocols together in one hub, enabling cross-protocol communication. This document defines how such communication works.
 
 ## Concepts
 
 First, let's clarify the concepts in the context of cross-protocol communication.
 
-* **MQTT Clients**: Clients using [MQTT](https://mqtt.org/) protocols.
-* **Web PubSub Clients**: Clients using Web PubSub's own protocols with pub/sub capabilities. Examples include `json.webpubsub.azure.v1`, `protobuf.webpubsub.azure.v1`, `json.reliable.webpubsub.azure.v1`, and `protobuf.reliable.webpubsub.azure.v1`. You can find an overview of Web PubSub's client protocols [here](./concept-client-protocols.md).
-* **Reliable Web PubSub Clients**: A subset of Web PubSub Clients using Web PubSub reliable protocols, specifically `json.reliable.webpubsub.azure.v1`, and `protobuf.reliable.webpubsub.azure.v1`.
+* **MQTT clients**: Clients using [MQTT](https://mqtt.org/) protocols.
+* **Web PubSub clients**: Clients using Web PubSub's own protocols with pub/sub capabilities. Examples include `json.webpubsub.azure.v1`, `protobuf.webpubsub.azure.v1`, `json.reliable.webpubsub.azure.v1`, and `protobuf.reliable.webpubsub.azure.v1`. You can find an overview of Web PubSub's client protocols [here](./concept-client-protocols.md).
+* **Reliable Web PubSub clients**: A subset of Web PubSub clients using Web PubSub reliable protocols, specifically `json.reliable.webpubsub.azure.v1`, and `protobuf.reliable.webpubsub.azure.v1`.
 
-## Concept Mappings
+## Concept mappings
 
-### Message Routing Behavior
+### Message routing behavior
 
 From the [Overview: MQTT in Azure Web PubSub Service](./overview-mqtt.md), we learn that joining a group in Web PubSub's protocols works the same as subscribing to the same named topic in MQTT. Similarly, sending to a group means publishing to the same named topic. This means if a client using Web PubSub protocols joins group `a`, it'll' get messages from MQTT clients sending to topic `a`, and vice versa.
 
-### Message Content Type Conversion
+### Message content type conversion
 
 In Web PubSub protocols, there are four message data types: Text, Binary, JSON, and Protobuf.
 
@@ -43,26 +43,26 @@ Here's the conversion between the MQTT "content type" field and Web PubSub messa
 | `application/octet-stream`     | Binary                         |
 | Absent or MQTT 3.1.1           | Binary                         |
 
-### Message Content Conversion
+### Message content conversion
 
 For text-based Web PubSub message data types, including `Text` and `Json`, they convert to and from MQTT by UTF-8 encoding. For binary-based Web PubSub message data types, including `Protobuf` and `Binary`, they remain exactly the same in the MQTT message content.
 
-### Message Quality of Service (QoS) Conversion
+### Message quality of service (QoS) conversion
 
 In Web PubSub protocols, the QoS of a message a client receives is determined by the client's protocol. Reliable clients get only QoS 1 messages, while other clients get only QoS 0 messages.
 
 In MQTT protocols, the QoS of a message a client receives is determined by both the message QoS (sending QoS) and the granted subscription QoS, specifically the smaller value of the two.
 
 When messages transfer across protocols, the received QoS is defined as follows:
 
-| Message Sender | Message Receiver | QoS Evaluation |
+| Message sender | Message receiver | QoS evaluation |
 |----------------|------------------|----------------|
-| MQTT Clients   | Reliable Web PubSub Clients | QoS is always 1 |
-| MQTT Clients   | Other Web PubSub Clients    | QoS is always 0 |
-| Web PubSub Clients | MQTT Clients           | Min(1, granted subscription QoS) |
+| MQTT clients   | Reliable Web PubSub clients | QoS is always 1 |
+| MQTT clients   | Other Web PubSub clients    | QoS is always 0 |
+| Web PubSub clients | MQTT clients           | Min(1, granted subscription QoS) |
 
 ### Others
 
 Message properties listed here take effect across protocols. The others don't.
 
-* MQTT Message expiry interval
+* MQTT message expiry interval

articles/azure-web-pubsub/reference-mqtt-cross-protocol-communication.md

@@ -1,5 +1,5 @@
 ---
-title: Azure Web PubSub service data plane REST API Specification for MQTT
+title: Azure Web PubSub service data plane REST API specification for MQTT
 description: Clarifies the meanings of the Web PubSub data-plane REST API in the context of MQTT
 author: Y-Sindo
 ms.author: zityang
@@ -12,27 +12,27 @@ ms.date: 07/23/2024
 
 This document clarifies the meanings of the Web PubSub data-plane REST API in the context of MQTT. The existing Web PubSub REST API documentation is focused on Web PubSub’s own protocols, which may make its application to MQTT unclear.
 
-## Term Mappings
+## Term mappings
 
 To begin, familiarize yourself with the term mappings between Web PubSub and MQTT. If you are already familiar with these terms, you may skip this section.
 
 [!INCLUDE [MQTT-Term-Mappings](includes/mqtt-term-mappings.md)]
 
-## Operation Mappings
+## Operation mappings
 
 For a comprehensive list of available operations, refer to the [REST API reference](/rest/api/webpubsub/dataplane/web-pub-sub).
 
 The REST API operations are categorized into the following groups:
 
-* [Message Sending Operations](#message-sending-operations)
-* [Subscription Management Operations](#subscription-management-operations)
-* [Permission Management Operations](#permission-management-operations)
-* [Existence Management Operations](#existence-management-operations)
-* [Client Token Generation Operations](#client-token-generation-operations)
+* [Message sending operations](#message-sending-operations)
+* [Subscription management operations](#subscription-management-operations)
+* [Permission management operations](#permission-management-operations)
+* [Existence management operations](#existence-management-operations)
+* [Client token generation operations](#client-token-generation-operations)
 
 Each of these categories is defined below.
 
-### Message Sending Operations
+### Message sending operations
 
 | REST API Operation | Effect on MQTT |
 | ------------------ | -------------- |
@@ -41,7 +41,7 @@ Each of these categories is defined below.
 
 Messages are published with a QoS of 1. The QoS of received messages may be downgraded based on the clients' subscription options, following the standard MQTT downgrading rules.
 
-### Subscription Management Operations
+### Subscription management operations
 
 | REST API Operation | Effect on MQTT |
 | ------------------ | -------------- |
@@ -51,21 +51,21 @@ Messages are published with a QoS of 1. The QoS of received messages may be down
 
 The group name corresponds to the MQTT topic filter. When adding connections or users to groups, default MQTT subscription options are used.
 
-### Permission Management Operations
+### Permission management operations
 
 These operations are straightforward in the context of MQTT and thus the definition is ignored.
 * Check Permission
 * Grant Permission
 * Revoke Permission
 
-### Existence Management Operations
+### Existence management operations
 
 | REST API Operation | Effect on MQTT |
 | ------------------ | -------------- |
 | Connection Exists<br>Group Exists<br>User Exists | Checks whether a session exists for the specified connection, user, or group. Note that this differs from checking if a connection is currently online. |
 | Close All Connections<br>Close Group Connections<br>Close User Connections | Ends the specified sessions and terminates the corresponding physical connections. |
 
-### Client Token Generation Operations
+### Client token generation operations
 
 | REST API Operation | Effect on MQTT |
 | ------------------ | -------------- |

articles/azure-web-pubsub/reference-rest-api-mqtt.md

@@ -20,7 +20,7 @@ In this tutorial, you'll learn how to write a .NET web server to authenticate an
 * [.NET Runtime](https://dotnet.microsoft.com/download/dotnet) installed.
 * [Node.js](https://nodejs.org)
 
-## Deploy Azure Web PubSub Service
+## Deploy Azure Web PubSub service
 
 Here are the Bicep/Azure Resource Manager templates to deploy an Azure Web PubSub service with client certificate authentication enabled and event handlers configured.
 
@@ -139,7 +139,7 @@ resource hub 'Microsoft.SignalRService/WebPubSub/hubs@2023-03-01-preview' = {
 
 ---
 
-## Set Up Auth Server
+## Set up auth server
 
 We've provided an auth server sample [here](https://github.com/Azure/azure-webpubsub/tree/main/samples/csharp/mqttAuthServer). Please download the project.
 
@@ -193,7 +193,7 @@ dotnet run
 ```
 
 
-### Expose Server Endpoint To Public Network
+### Expose server endpoint to public network
 
 #### Download and install awps-tunnel
 The tool runs on [Node.js](https://nodejs.org/) version 16 or higher.
@@ -208,7 +208,7 @@ export WebPubSubConnectionString="<your connection string>"
 awps-tunnel run --hub {hubName} --upstream http://localhost:{portExposedByYourAuthServer}
 ```
 
-## Implement MQTT Clients
+## Implement MQTT clients
 
 We will implement the client side in Node.JS.