Merge pull request #292998 from xingsy97/wps-simple-client-2025

[Azure Web PubSub] add simple client mode

Author: prmerger-automator[bot]

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

@@ -59,6 +59,25 @@ var client1 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');
 var client2 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'custom.subprotocol')
 ```
 
+Simple WebSocket client has two modes: `sendEvent` and `sendToGroup`. The mode is determined once the connection is established and cannot be changed later.
+
+`sendEvent` is the default mode for the simple WebSocket client. In `sendEvent` mode, every WebSocket frame the client sent is considered as a `message` event. Users can configure [event handlers](./concept-service-internals.md#event-handler) or [event listeners](./concept-service-internals.md#event-listener) to handle these `message` events. 
+
+```javascript
+// Every data frame is considered as a `message` event
+var client3 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');
+
+// Or explicitly set the mode
+var client4 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendEvent');
+```
+
+In `sendToGroup` mode, every WebSocket frame the client sent is considered as a message to be published to a specific group. `group` is a required query parameter in this mode, and only a single value is allowed. The connection should also have corresponding [permissions](#permissions) to send messages to the target group. Both `webpubsub.sendToGroup.<group>` and `webpubsub.sendToGroup` roles work for it.
+
+For example, in JavaScript, you can create a simple WebSocket client in `sendToGroup` mode with `group=group1` by using the following code:
+```javascript
+var client5 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendToGroup&group=group1');
+```
+
 ## The PubSub WebSocket client
 
 A **PubSub WebSocket client** is the WebSocket client using subprotocols defined by the Azure Web PubSub service:

articles/azure-web-pubsub/concept-service-internals.md

@@ -29,7 +29,7 @@ Azure Web PubSub Service provides an easy way to publish/subscribe messages usin
 
 Workflow as shown in the above graph:
 
-1. A _client_ connects to the service `/client` endpoint using WebSocket transport. Service forward every WebSocket frame to the configured upstream(server). The WebSocket connection can connect with any custom subprotocol for the server to handle, or it can connect with the service-supported subprotocol `json.webpubsub.azure.v1`, which empowers the clients to do pub/sub directly. Details are described in [client protocol](#client-protocol).
+1. A _client_ connects to the service `/client` endpoint using WebSocket transport. Service forwards every WebSocket frame to the configured upstream(server) by default, the WebSocket connection can connect with any custom subprotocol for the server to handle. Alternatively, the client could connect with mode `sendToGroup` and send every WebSocket frame to a specific group. The client could also connect with [the service-supported subprotocols](#the-pubsub-websocket-client), which offer features such as sending events to your upstream, joining groups, and directly sending messages to groups. Details are described in [client protocol](#client-protocol).
 2. On different client events, the service invokes the server using **CloudEvents protocol**. [**CloudEvents**](https://github.com/cloudevents/spec/tree/v1.0.1) is a standardized and protocol-agnostic definition of the structure and metadata description of events hosted by the Cloud Native Computing Foundation (CNCF). Detailed implementation of CloudEvents protocol relies on the server role, described in [server protocol](#server-protocol).
 3. The Web PubSub server can invoke the service using the REST API to send messages to clients or to manage the connected clients. Details are described in [server protocol](#server-protocol)
 
@@ -59,7 +59,7 @@ var client2 = new WebSocket(
 );
 ```
 
-A simple WebSocket client follows a client<->server architecture, as the following sequence diagram shows:
+[Simple WebSocket client](#the-simple-websocket-client) has two modes. Its default mode `sendEvent` follows a client<->server architecture, as the below sequence diagram shows:
 ![Diagram showing the sequence for a client connection.](./media/concept-service-internals/simple-client-sequence.png)
 
 1. When the client starts a WebSocket handshake, the service tries to invoke the `connect` event handler for WebSocket handshake. Developers can use this handler to handle the WebSocket handshake, determine the subprotocol to use, authenticate the client, and join the client to groups.
@@ -127,7 +127,7 @@ A PubSub WebSocket client can:
 
 [PubSub WebSocket Subprotocol](./reference-json-webpubsub-subprotocol.md) contains the details of the `json.webpubsub.azure.v1` subprotocol.
 
-You noticed that for a [simple WebSocket client](#the-simple-websocket-client), the _server_ is a **must have** role to receive the `message` events from clients. A simple WebSocket connection always triggers a `message` event when it sends messages, and always relies on the server-side to process messages and do other operations. With the help of the `json.webpubsub.azure.v1` subprotocol, an authorized client can join a group and publish messages to a group directly. It can also route messages to different event handlers / event listeners by customizing the _event_ the message belongs.
+In the dafult mode `sendEvent` of [simple WebSocket client](#the-simple-websocket-client), the _server_ is a **must have** role to receive the `message` events from clients. A simple WebSocket connection in `sendEvent` mode always triggers a `message` event when it sends messages, and always relies on the server-side to process messages and do other operations. The `sendToGroup` mode only empowers clients to publish messages to groups directly without triggering requests to the server, which is still limited. `json.webpubsub.azure.v1` subprotocol empowers clients to do much more without triggering requests to the server. With the help of it, an authorized client can join a group and publish messages to a group directly. It can also route messages to different event handlers / event listeners by customizing the _event_ the message belongs.
 
 #### Scenarios
 

articles/azure-web-pubsub/includes/terms.md

@@ -16,7 +16,7 @@ ms.date: 01/23/2024
 
 - **Message**: When the client is connected, it can send messages to the upstream application, or receive messages from the upstream application, through the WebSocket connection. Messages can be in plain text, binary, or JSON format and have a maximum size of 1 MB.
 
-- **Client Events**: Events are created during the lifecycle of a client connection. For example, a simple WebSocket client connection creates a `connect` event when it tries to connect to the service, a `connected` event when it successfully connected to the service, a `message` event when it sends messages to the service and a `disconnected` event when it disconnects from the service. Details about *client events* are illustrated in [Client protocol](..\concept-service-internals.md#client-protocol) section.
+- **Client Events**: Events are created during the lifecycle of a client connection. For example, a simple WebSocket client connection creates a `connect` event when it tries to connect to the service, a `connected` event when it successfully connected to the service, a `message` event when it sends messages to the service in its default mode `sendEvent` and a `disconnected` event when it disconnects from the service. Details about *client events* are illustrated in [Client protocol](..\concept-service-internals.md#client-protocol) section.
 
 - **Event Handler**: The event handler contains the logic to handle the client events. Register and configure event handlers in the service through the portal or Azure CLI beforehand. Details are described in [Event handler](..\concept-service-internals.md#event-handler) section.