Elementos internos del servicio Azure Web PubSub

Artigo
08/21/2024

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.
Un protocolo simple permite a los clientes publicar masajes directamente entre sí.
El servicio administra las conexiones de WebSocket automáticamente.

Términos

Servicio: Azure Web PubSub.

Conexión: una conexión, también conocida como un cliente o una conexión de cliente es una relación lógica entre un cliente y el servicio Web PubSub. A través de una "conexión", el cliente y el servicio interactúan en una serie de interacciones con estado. Las conexiones que usan distintos protocolos pueden comportarse de forma diferente, por ejemplo, algunas conexiones están limitadas a la duración de una conexión de red, mientras que otras pueden extenderse a través de múltiples conexiones de red sucesivas entre un cliente y el servicio.
Centro de conectividad: un centro de conectividad es un concepto lógico relativo a un conjunto de conexiones de clientes. Normalmente se utiliza un centro para un escenario, por ejemplo, un centro de chat, o un centro de notificación. 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 existe un límite estricto para el número de centros, un centro consume más carga de servicio en comparación con un grupo. Se recomienda tener un conjunto predeterminado de centros 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.
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

Diagrama que muestra el flujo de trabajo del servicio Web PubSub.

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 cliente<->servidor, como muestra el siguiente diagrama de secuencia: Diagrama que muestra la secuencia de una conexión de cliente.

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. Este evento 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 un código de respuesta que no es 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 afectados, si los hay. Si el servicio no encuentra ningún servidor registrado para recibir los mensajes, el servicio también quita la conexión de cliente.
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.

Ha 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. En su lugar, envían 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.

Diagrama que muestra el flujo de trabajo de autenticación de cliente.

Un cliente puede publicar en otros clientes solo 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.

Diagrama que muestra el modo de inserción de eventos del servicio Web PubSub.

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 webhook ascendente.

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

Para establecer la autenticación y autorización seguras entre el servicio y el webhook, tenga en cuenta las siguientes opciones y pasos:

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.

Habilite la identidad para el servicio Web PubSub.
Seleccione entre la aplicación de Microsoft Entra existente 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.

Diagrama que muestra el flujo de trabajo del administrador de conexiones del servicio Web PubSub.

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 en el que los configura no afecta a su funcionalidad. Si un evento coincide con varios agentes de escucha, el evento se envía a todos los agentes de escucha coincidentes. Consulte el siguiente diagrama para obtener un ejemplo. Por ejemplo, si configura cuatro agentes de escucha de eventos simultáneamente, cada agente de escucha que recibe una coincidencia procesa el evento. Un evento de cliente que coincide con tres de esos agentes de escucha se envía a tres agentes de escucha, con el agente de escucha restante omitido.

Ejemplo de diagrama de flujo de datos del agente de escucha de eventos

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 reciben 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

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. Una vez que combine 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.

Diagrama que muestra el flujo de trabajo bidireccional del servicio Web PubSub.