Elementos internos del servicio Azure Web PubSub

Artículo
06/01/2023

El servicio Azure Web PubSub ofrece una manera sencilla de publicar y suscribir mensajes mediante conexiones WebSocket sencillas.

Los clientes se pueden escribir en cualquier lenguaje que tenga compatibilidad con WebSocket.
Se admiten tanto los mensajes de texto como binarios dentro de una conexión.
Hay un protocolo simple para que los clientes realicen la publicación directa de mensajes de cliente a cliente.
El servicio administra las conexiones de WebSocket automáticamente.

Términos

Servicio: Azure Web PubSub.

Conexión: una conexión, también conocida como "cliente" o "conexión de cliente", representa una conexión WebSocket individual conectada al servicio Web PubSub. Cuando se conecta correctamente, el servicio Web PubSub asigna un identificador de conexión único a esta conexión.
Centro de conectividad: un centro de conectividad es un concepto lógico relativo a un conjunto de conexiones de clientes. Normalmente, se usa un centro para un escenario, por ejemplo, un centro de chat o un centro de notificaciones . Cuando se establece una conexión de cliente, esta se realiza con un centro de conectividad y, durante su vigencia, pertenece a dicho centro. Una vez que una conexión de cliente se conecta al centro, el centro existe. Diferentes aplicaciones pueden compartir un servicio de Azure Web PubSub mediante el uso de nombres de centros de conectividad diferentes. Aunque no hay ningún límite estricto en el número de concentradores, un centro consume más carga de servicio en comparación con un grupo. Se recomienda tener un conjunto predeterminado de concentradores en lugar de generarlos dinámicamente.
Grupo: un grupo es un subconjunto de conexiones al centro de conectividad. Puede agregar una conexión de cliente a un grupo o quitarla de este cuando quiera. Por ejemplo, cuando un cliente se une a una sala de chat o sale de ella, dicha sala puede considerarse un grupo. Un cliente puede unirse a varios grupos, y un grupo puede contener varios clientes. El grupo es como una"sesión" de grupo. La sesión de grupo se crea cuando alguien se une al grupo y la sesión desaparece cuando no hay nadie en el grupo. Los mensajes enviados al grupo se entregan a todos los clientes conectados al grupo.
Usuario: las conexiones a Web PubSub pueden pertenecer a un usuario. Un usuario puede tener varias conexiones, por ejemplo, cuando está conectado a través de varios dispositivos o distintas pestañas del explorador.
Mensaje: cuando el cliente está conectado, puede enviar mensajes a la aplicación de nivel superior o recibir mensajes de esta, mediante la conexión WebSocket. Los mensajes pueden estar en formato de texto sin formato, binario o JSON y tener un tamaño máximo de 1 MB.
Conexión del cliente y ConnectionId: Un cliente se conecta al punto de conexión /client, cuando está conectado, el servicio genera un único connectionId como identidad única de la conexión del cliente. A continuación, los usuarios pueden administrar la conexión del cliente mediante este connectionId. En la sección Protocolo del cliente se describen más detalles.
Eventos del cliente: Los eventos se crean durante el ciclo de vida de una conexión del cliente. Por ejemplo, una conexión del cliente WebSocket simple crea un evento connect cuando intenta conectarse al servicio, un evento connected cuando se conecta correctamente al servicio, un evento message cuando envía mensajes al servicio y un evento disconnected cuando se desconecta del servicio. En la sección Protocolo del cliente se describen más detalles sobre los eventos del cliente.
Controlador de eventos: El controlador de eventos contiene la lógica para controlar los eventos del cliente. Registre y configure controladores de eventos en el servicio a través del portal o la CLI de Azure de antemano. En la sección Controlador de eventos se describen más detalles.
Cliente de escucha de eventos (versión preliminar): el cliente de escucha de eventos solo escucha los eventos de cliente, pero no puede interferir en la duración de los clientes mediante su respuesta. En la sección Cliente de escucha de eventos se describen más detalles.
Servidor: el servidor puede controlar eventos de cliente, administrar las conexiones del cliente o publicar mensajes en grupos. Tanto el controlador de eventos como el agente de escucha de eventos se consideran del lado servidor. En la sección Protocolo del servidor se describen más detalles sobre el servidor.

Flujo de trabajo

Diagram showing the Web PubSub service workflow.

Flujo de trabajo como se muestra en el gráfico anterior:

Un cliente se conecta al punto de conexión /client del servicio mediante el transporte de WebSocket. El servicio reenvía cada marco de WebSocket al servidor ascendente configurado. La conexión de WebSocket puede conectarse con cualquier subprotocolo personalizado para que el servidor lo controle, o bien puede conectarse con el subprotocolo json.webpubsub.azure.v1 compatible con el servicio, que permite a los clientes publicar o suscribir directamente. En Protocolo del cliente se describen los detalles.
En eventos de cliente diferentes, el servicio invoca el servidor mediante el protocolo CloudEvents. CloudEvents es una definición del protocolo, estandarizada e independiente de la estructura, y una descripción de metadatos de los eventos hospedados por Cloud Native Computing Foundation (CNCF). La implementación detallada del protocolo CloudEvents se basa en el rol de servidor, que se describe en el protocolo de servidor.
El servidor de Web PubSub puede invocar el servicio mediante la API REST para enviar mensajes a los clientes o para administrar los clientes conectados. Los detalles se describen en Protocolo del servidor.

Protocolo del cliente

Una conexión del cliente se conecta al punto de conexión /client del servicio mediante el protocolo de WebSocket. El protocolo de WebSocket ofrece canales de comunicación dúplex completos a través de una única conexión TCP, e IETF lo estandarizó como RFC 6455 en 2011. La mayoría de los lenguajes tienen compatibilidad nativa para iniciar conexiones WebSocket.

Nuestro servicio admite dos tipos de cliente:

Uno se denomina cliente simple de WebSocket.
El otro se denomina cliente WebSocket de PubSub.

Cliente simple de WebSocket

Un cliente simple de WebSocket, como indica la nomenclatura, es una conexión simple de WebSocket. También puede tener su subprotocolo personalizado.

Por ejemplo, en JS, se puede crear un cliente simple de WebSocket mediante el código siguiente.

// simple WebSocket client1
var client1 = new WebSocket("wss://test.webpubsub.azure.com/client/hubs/hub1");

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "custom.subprotocol"
);

Un cliente webSocket simple sigue una arquitectura de servidor cliente<>, como se muestra en el diagrama de secuencia siguiente: Diagram showing the sequence for a client connection.

Cuando el cliente inicia un protocolo de enlace WebSocket, el servicio intenta invocar el controlador de eventos connect para el protocolo de enlace WebSocket. Los desarrolladores pueden usar este controlador para controlar el protocolo de enlace WebSocket, determinar el subprotocolo que se va a usar, autenticar el cliente y unir el cliente a algunos grupos.
Cuando el cliente se conecta correctamente, el servicio invoca un controlador de eventos connected. Funciona como una notificación y no impide al cliente el envío de mensajes. Los desarrolladores pueden usar este controlador para almacenar datos y pueden responder con mensajes al cliente. El servicio también inserta un evento connected en todos los clientes de escucha de eventos relativos, si los hay.
Cuando el cliente envía mensajes, el servicio desencadena un evento message al controlador de eventos para controlar los mensajes enviados. Este es un evento general que contiene los mensajes enviados en un marco de WebSocket. El código tiene que enviar los mensajes dentro de este controlador de eventos. Si el controlador de eventos devuelve código de respuesta no correcto, el servicio quita la conexión de cliente. El servicio también inserta un evento message en todos los clientes de escucha de eventos relativos, si los hay. Si el servicio no encuentra ningún servidor registrado para recibir los mensajes, el servicio también quita la conexión.
Cuando el cliente se desconecta, el servicio intenta desencadenar el evento disconnected en el controlador de eventos una vez que detecta la desconexión. El servicio también inserta un evento disconnected en todos los clientes de escucha de eventos relativos, si los hay.

Escenarios

Estas conexiones se pueden usar en una arquitectura habitual de cliente-servidor, donde el cliente envía mensajes al servidor y el servidor controla los mensajes entrantes mediante controladores de eventos. También se puede usar cuando los clientes aplican subprotocolos existentes en su lógica de aplicación.

El cliente WebSocket de PubSub

El servicio también admite un subprotocolo específico denominado json.webpubsub.azure.v1, que permite a los clientes publicar o suscribirse directamente en lugar de realizar un recorrido de ida y vuelta al servidor ascendente. Llamamos a la conexión de WebSocket con el subprotocolo json.webpubsub.azure.v1 un cliente WebSocket de PubSub. Para obtener más información, consulte la especificación de cliente de Web PubSub en GitHub.

Por ejemplo, en JS, se puede crear un cliente de WebSocket de PubSub mediante el código siguiente.

// PubSub WebSocket client
var pubsub = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);

Un cliente WebSocket de PubSub puede:

Unirse a un grupo, por ejemplo:

{
  "type": "joinGroup",
  "group": "<group_name>"
}

Abandonar un grupo, por ejemplo:

{
  "type": "leaveGroup",
  "group": "<group_name>"
}

Publicar mensajes en un grupo, por ejemplo:

{
  "type": "sendToGroup",
  "group": "<group_name>",
  "data": { "hello": "world" }
}

Enviar eventos personalizados al servidor ascendente, por ejemplo:

{
  "type": "event",
  "event": "<event_name>",
  "data": { "hello": "world" }
}

El subprotocolo WebSocket de PubSub contiene los detalles del subprotocolo json.webpubsub.azure.v1.

Puede que haya observado que, para un cliente simple de WebSocket, el servidor es un rol imprescindible para recibir los eventos message de los clientes. Una conexión simple de WebSocket siempre desencadena un evento message cuando envía mensajes, y siempre se basa en el lado servidor para procesar mensajes y realizar otras operaciones. Con la ayuda del subprotocolo json.webpubsub.azure.v1, un cliente autorizado puede unirse a un grupo y publicar mensajes en un grupo directamente. También puede enrutar mensajes a distintos controladores de eventos/clientes de escucha de eventos personalizando el evento al que pertenece el mensaje.

Escenarios

Estos clientes se pueden usar cuando los clientes quieren comunicarse entre sí. Los mensajes se envían de client2 al servicio, y el servicio entrega el mensaje directamente a client1 si los clientes están autorizados para hacerlo.

Client1:

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

Client2:

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

Como se muestra en el ejemplo anterior, client2 envía datos directamente a client1 mediante la publicación de mensajes en Group1 donde se encuentra client1.

Resumen de eventos de cliente

Los eventos de cliente se dividen en dos categorías:

Eventos sincrónicos (bloqueo). Los eventos sincrónicos bloquean el flujo de trabajo del cliente.
- connect: este evento es solo para el controlador de eventos. Cuando el cliente inicia un protocolo de enlace de WebSocket, el evento se desencadena y los desarrolladores pueden usar el controlador de eventos connect para controlar el protocolo de enlace WebSocket, determinar el subprotocolo que se va a usar, autenticar el cliente y unir el cliente a grupos.
- message: este evento se desencadena cuando un cliente envía un mensaje.
Eventos asincrónicos (sin bloqueo). Los eventos asincrónicos no bloquean el flujo de trabajo del cliente, actúan como una notificación al servidor. Cuando se produce un error en este tipo de desencadenador de eventos, el servicio registra los detalles del error.
- connected: este evento se desencadena cuando un cliente se conecta al servicio correctamente.
- disconnected: este evento se desencadena cuando un cliente se desconecta con el servicio.

Límite de mensajes del cliente

El tamaño máximo permitido de mensaje para un marco WebSocket es de 1 MB.

Autenticación de clientes

Flujo de trabajo de autenticación

El cliente usa un token JWT firmado para conectarse al servicio. El servidor ascendente también puede rechazar el cliente cuando es el controlador de eventos connect del cliente entrante. El controlador de eventos autentica el cliente al especificar los valores de userId y role que tiene el cliente en la respuesta del webhook, o bien rechaza el cliente con 401. En la sección Controlador de eventos se describe en detalle.

En el gráfico siguiente se describe el flujo de trabajo.

Diagram showing the client authentication workflow.

Como puede que haya observado cuando se describieron los clientes de WebSocket de PubSub, un cliente solo puede publicar en otros clientes cuando está autorizado. Los valores de role del cliente determinan los permisos iniciales que tiene el cliente:

Role	Permiso
No especificado	El cliente puede enviar eventos.
`webpubsub.joinLeaveGroup`	El cliente puede unirse a cualquier grupo o abandonarlo.
`webpubsub.sendToGroup`	El cliente puede publicar mensajes en cualquier grupo.
`webpubsub.joinLeaveGroup.<group>`	El cliente puede unirse al grupo `<group>` o abandonarlo.
`webpubsub.sendToGroup.<group>`	El cliente puede publicar mensajes en el grupo `<group>`.

El lado servidor también puede conceder o revocar permisos del cliente dinámicamente a través del protocolo del servidor, como se muestra en una sección posterior.

Protocolo del servidor

El protocolo del servidor ofrece la funcionalidad para que el servidor controle los eventos de cliente y administre las conexiones del cliente y los grupos.

En general, el protocolo del servidor contiene dos roles:

Controlador de eventos
Connection manager
Agente de escucha de eventos

Controlador de eventos

El controlador de eventos controla los eventos de cliente entrantes. Los controladores de eventos se registran y configuran en el servicio a través del portal o de la CLI de Azure. Cuando se desencadena un evento de cliente, el servicio puede identificar si el evento se debe controlar o no. Ahora se usa el modo PUSH para invocar el controlador de eventos. El controlador de eventos del lado servidor expone un punto de conexión accesible de forma pública para que el servicio lo invoque cuando se desencadene el evento. Funciona como webhook.

El servicio Web PubSub entrega los eventos de cliente al webhook ascendente mediante el protocolo HTTP de CloudEvents.

Para cada evento, el servicio formula una solicitud HTTP POST al servidor ascendente registrado y espera una respuesta HTTP.

Los datos que se envían del servicio al servidor siempre están en formato binary de CloudEvents.

Diagram showing the Web PubSub service event push mode.

Servidor ascendente y validación

Los controladores de eventos deben registrarse y configurarse en el servicio a través del portal o de la CLI de Azure antes de usarlos por primera vez. Cuando se desencadena un evento de cliente, el servicio puede identificar si el evento se debe controlar o no. Para la versión preliminar pública, se usa el modo PUSH para invocar el controlador de eventos. El controlador de eventos del lado servidor expone un punto de conexión accesible de forma pública para que el servicio lo invoque cuando se desencadene el evento. Funciona como un webhookascendente.

La dirección URL puede usar el parámetro {event} para definir una plantilla de URL para el controlador de webhook. El servicio calcula el valor de la dirección URL del webhook dinámicamente cuando entra la solicitud del cliente. Por ejemplo, cuando llega una solicitud /client/hubs/chat, con un patrón http://host.com/api/{event} de dirección URL de controlador de eventos configurado para el centro chat, cuando el cliente se conecta, primero se aplica POST a esta dirección URL: http://host.com/api/connect. Este comportamiento puede ser útil cuando un cliente de WebSocket de PubSub envía eventos personalizados y el controlador de eventos ayuda a enviar eventos diferentes a diferentes niveles ascendentes. El parámetro {event} no se permite en el nombre de dominio de la dirección URL.

Al configurar el controlador de eventos ascendente a través de Azure Portal o la CLI, el servicio sigue la protección contra abusos de CloudEvents para validar el webhook ascendente. El encabezado de la solicitud WebHook-Request-Origin se establece en el nombre de dominio del servicio xxx.webpubsub.azure.com, y espera que la respuesta que tiene el encabezado WebHook-Allowed-Origin contenga este nombre de dominio.

Al realizar la validación, el parámetro {event} se resuelve en validate. Por ejemplo, al intentar establecer la dirección URL en http://host.com/api/{event}, el servicio intenta aplicar OPTIONS a una solicitud a http://host.com/api/validate, y la configuración se puede establecer correctamente solo cuando la respuesta es válida.

Por ahora, no se admiten WebHook-Request-Rate ni WebHook-Request-Callback.

Autenticación y autorización entre el servicio y el webhook

Modo anónimo
Autenticación simple en la que code se proporciona a través de la dirección URL del webhook configurada.
Use la autorización de Microsoft Entra. Para obtener más información, consulte Cómo usar la identidad administrada.
- Paso 1: Habilite la identidad para el servicio Web PubSub
- Paso 2: selección de una aplicación existente de Microsoft Entra que representa la aplicación web de webhook

Administrador de conexiones

Por naturaleza, el servidor es un usuario autorizado. Con la ayuda del rol de controlador de eventos, el servidor conoce los metadatos de los clientes, por ejemplo, connectionId y userId, para que pueda:

Cierre de una conexión de cliente
Enviar mensajes a un cliente
Enviar mensajes a clientes que pertenecen al mismo usuario
Agregar un cliente a un grupo
Agregar clientes autenticados como el mismo usuario a un grupo
Quitar un cliente de un grupo
Quitar clientes autenticados como el mismo usuario de un grupo
Publicar mensajes en un grupo

También puede conceder o revocar permisos de publicación/unión para un cliente de PubSub:

Conceder permisos de unión o publicación a algún grupo específico o a todos los grupos
Revocar permisos de unión o publicación de algún grupo específico o de todos los grupos
Comprobar si el cliente tiene permiso para unirse o publicar en algún grupo específico o en todos los grupos

El servicio proporciona API REST para que el servidor se encargue de la administración de las conexiones.

Diagram showing the Web PubSub service connection manager workflow.

El protocolo de API REST detallado se define aquí.

Agente de escucha de eventos

Nota:

La característica de cliente de escucha de eventos está en versión preliminar.

El cliente de escucha de eventos escucha los eventos de cliente entrantes. Cada cliente de escucha de eventos contiene un filtro para especificar a qué tipos de eventos se refiere, un punto de conexión sobre dónde enviar los eventos.

Actualmente se admite Event Hubs como punto de conexión del cliente de escucha de eventos.

Debe registrar clientes de escucha de eventos de antemano para que, cuando se desencadene un evento de cliente, el servicio puede insertar el evento en los clientes de escucha de eventos correspondientes. Consulte este documento para ver cómo configurar un cliente de escucha de eventos con un punto de conexión del centro de eventos.

Puede configurar varios clientes de escucha de eventos. El orden de estos clientes de escucha de eventos no importa. Si un evento coincide con varios clientes de escucha de eventos, se enviará a todos los clientes de escucha que coincida. Consulte el siguiente diagrama para obtener un ejemplo. Supongamos que configura cuatro clientes de escucha de eventos al mismo tiempo. A continuación, se enviará un evento de cliente que coincida con tres de esos clientes de escucha a tres agentes de escucha, dejando el resto sin modificar.

Event listener data flow diagram sample

Puede combinar un controlador de eventos y clientes de escucha de eventos para el mismo evento. En este caso, tanto el controlador de eventos como los clientes de escucha de eventos recibirán el evento.

El servicio Web PubSub ofrece eventos de cliente a clientes de escucha de eventos mediante la extensión AMQP de CloudEvents para Azure Web PubSub.

Resumen

Es posible que haya observado que el rol de controlador de eventos controla la comunicación del servicio al servidor, mientras que el rol de administrador controla la comunicación del servidor al servicio. Después de combinar los dos roles, el flujo de datos entre el servicio y el servidor es similar al siguiente diagrama en el que se usa el protocolo HTTP.

Diagram showing the Web PubSub service bi-directional workflow.