Edit

Azure Web PubSub basic concepts

  • Article

Azure Web PubSub service helps you build real-time messaging web applications. The clients connect to the service using the standard WebSocket protocol, and the service exposes REST APIs and SDKs for you to manage these clients.

Terms

Here are some important terms used by the service:

  • Connection: A connection, also known as a client or a client connection, represents an individual WebSocket connection connected to the Web PubSub service. When successfully connected, a unique connection ID is assigned to this connection by the Web PubSub service.

  • Hub: A hub is a logical concept for a set of client connections. Usually you use one hub for one scenario, for example, a chat hub, or a notification hub. When a client connection connects, it connects to a hub, and during its lifetime it belongs to that hub. Once a client connection connects to the hub, the hub exists. Different applications can share one Azure Web PubSub service by using different hub names. While there is no strict limit on the number of hubs, a hub consumes more service load comparing to a group. It is recommended to have a predetermined set of hubs rather than generating them dynamically.

  • Group: A group is a subset of connections to the hub. You can add a client connection to a group, or remove the client connection from the group, anytime you want. For example, when a client joins a chat room, or when a client leaves the chat room, this chat room can be considered to be a group. A client can join multiple groups, and a group can contain multiple clients. The group is like a group "session", the group session is created once someone joins the group, and the session is gone when no one is in the group. Messages sent to the group are delivered to all of the clients connected to the group.

  • User: Connections to Web PubSub can belong to one user. A user might have multiple connections, for example when a single user is connected across multiple devices or multiple browser tabs.

  • 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 Connection and ConnectionId: A client connects to the /client endpoint, when connected, a unique connectionId is generated by the service as the unique identity of the client connection. Users can then manage the client connection using this connectionId. Details are described in 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 and a disconnected event when it disconnects from the service. Details about client events are illustrated in 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 section.

  • Event Listener(preview): The event listener just listens to the client events but can't interfere the lifetime of your clients through their response. Details are described in Event listener section.

  • Server: The server can handle client events, manage client connections, or publish messages to groups. Both event handler and event listener are considered to be server-side. Details about server are described in the Server protocol section.

Important

Hub, Group, UserId are important roles when you manage clients and send messages. They will be required parameters in different REST API calls as plain text. So DO NOT put sensitive information in these fields. For example, credentials or bearer tokens which will have high leak risk.

Workflow

A typical workflow using the service is shown as below:

Diagram showing the Web PubSub service workflow.

As illustrated by the above workflow 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 subprotocols (e.g. json.webpubsub.azure.v1) that enable the clients to do pub/sub directly. Details are described in client protocols.

  2. The service invokes the server using CloudEvents protocol on different client events. CloudEvents is a standardized and protocol-agnostic definition of the structure and metadata description of events hosted by the Cloud Native Computing Foundation (CNCF). Details are described in server protocol.

  3. Server can invoke the service using REST API to send messages to clients or to manage the connected clients. Details are described in server protocol