Protocolos de cliente de WebSocket para Azure Web PubSub

Artículo
03/06/2024

Los clientes se conectan a Azure Web PubSub mediante el protocolo WebSocket estándar.

Puntos de conexión del servicio

El servicio Web PubSub proporciona dos tipos de puntos de conexión a los que se pueden conectar los clientes:

/client/hubs/{hub}
/client/?hub={hub}

{hub} es un parámetro obligatorio que actúa como aislamiento para distintas aplicaciones. Se puede establecer en la ruta o en la consulta.

Authorization

Los clientes se conectan al servicio con un JSON Web Token (JWT). El token puede estar en la cadena de consulta, como /client/?hub={hub}&access_token={token}, o bien en el encabezado, como AuthorizationAuthorization: Bearer {token}.

Este es un flujo de trabajo de autorización general:

El cliente negocia con el servidor de aplicaciones. El servidor de aplicaciones contiene el middleware de autenticación, que controla la solicitud de cliente y firma un JWT para que el cliente se conecte al servicio.
El servidor de aplicaciones devuelve el JWT y la dirección URL del servicio al cliente.
El cliente intenta conectarse al servicio Web PubSub mediante la dirección URL y el token JWT devueltos desde el servidor de aplicaciones.

Notificaciones admitidas

También puede configurar propiedades para la conexión de cliente al generar el token de acceso especificando notificaciones especiales dentro del token JWT:

Descripción	Tipo de notificación	Valor de notificación	Notas
El `userId` para la conexión de cliente	`sub`	el userId	Solo se permite una notificación de `sub`.
La duración del token	`exp`	la hora de expiración	La notificación `exp` (fecha de expiración) identifica la hora de expiración en la que o después de la que el token NO DEBE ser aceptado para su procesamiento.
Los permisos de la conexión de cliente tiene inicialmente	`role`	el valor de rol definido en permisos	Especifique varias notificaciones `role` si el cliente tiene varios permisos.
Los grupos iniciales a los que se une la conexión de cliente una vez que se conecta a Azure Web PubSub	`group`	el grupo al que se va a unir	Especifique varias notificaciones `group` si el cliente forma parte de varios grupos.

También puede agregar notificaciones personalizadas al token de acceso y estos valores se conservan como la propiedad claims en conectar el cuerpo de la solicitud ascendente.

SDK de servidor proporciona API para generar el token de acceso para los clientes.

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 propio subprotocolo personalizado.

Por ejemplo, en JavaScript, puede crear un cliente WebSocket simple 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')

El cliente WebSocket de PubSub

Un cliente WebSocket de PubSub es el cliente de WebSocket que usa los subprotocolos definidos por el servicio Azure Web PubSub:

json.webpubsub.azure.v1
protobuf.webpubsub.azure.v1

Con el subprotocolo compatible con el servicio, los clientes WebSocket de PubSub pueden publicar mensajes directamente en grupos cuando tienen los permisos necesarios.

El subprotocolo `json.webpubsub.azure.v1`

Consulte aquí todos los detalles sobre el subprotocolo JSON.

Creación de un cliente WebSocket de PubSub

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

Unirse a un grupo directamente desde el cliente

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'joinGroup',
        group: 'group1',
        ackId: ++ackId
    }));

Envío de mensajes a un grupo directamente desde el cliente

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'sendToGroup',
        group: 'group1',
        ackId: ++ackId,
        dataType: "json",
        data: {
            "hello": "world"
        }
    }));

El subprotocolo `protobuf.webpubsub.azure.v1`

Los búferes de protocolo (protobuf) son un protocolo basado en binarios e independientes de la plataforma y el lenguaje que simplifica el envío de datos binarios. Protobuf proporciona herramientas a fin de generar clientes para muchos lenguajes como Java, Python, Objective-C, C# y C++. Más información sobre protobuf.

Por ejemplo, en JavaScript, el siguiente código permite crear un cliente WebSocket de PubSub con un subprotocolo protobuf:

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

Consulte aquí todos los detalles sobre el subprotocolo protobuf.

AckId y respuesta de confirmación

El cliente WebSocket de PubSub admite la propiedad ackId para los mensajes joinGroup, leaveGroup, sendToGroup y event. Si usa ackId, puede recibir un mensaje de respuesta de confirmación cuando se procesa la solicitud. Puede optar por omitir ackId en los escenarios del tipo "activar y olvidar". En el artículo, se describen las diferencias de comportamiento si se especifica ackId o si no se hace.

Comportamiento cuando no se especifica `ackId`

Si no se especifica ackId, se produce una situación de "activar y olvidar". Incluso si hay errores al intermediar mensajes, no tiene forma de recibir notificaciones.

Comportamiento cuando se especifica `ackId`

Publicación idempotente

ackId es un número uint64 y debe ser único dentro de un cliente con el mismo identificador de conexión. El servicio Web PubSub registra el ackId y los mensajes con la misma ackId se tratan como el mismo mensaje. El servicio rechaza la intermediación en el mismo mensaje más de una vez, lo que resulta útil para volver a intentar evitar que haya mensajes duplicados. Por ejemplo, si un cliente envía un mensaje con ackId=5 y no recibe una respuesta de confirmación con ackId=5, el cliente vuelve a intentarlo y envía el mismo mensaje de nuevo. En algunos casos, el mensaje ya está asincronizado y la respuesta de confirmación se pierde por algún motivo. El servicio rechaza el reintento y la respuesta de una respuesta de confirmación con Duplicate motivo.

Respuesta de confirmación

El servicio Web PubSub envía una respuesta de confirmación a cada solicitud con ackId.

Formato:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

ackId asocia la solicitud.
success es un valor booleano e indica si el servicio procesa correctamente la solicitud. Si es false, los clientes deben comprobar error.
error solo existe cuando success es false y los clientes deben tener una lógica diferente para diferentes name. Debe suponer que puede haber más tipos de name en el futuro.
- Forbidden: el cliente no tiene permiso para la solicitud. El cliente necesita que se agreguen roles pertinentes.
- InternalServerError: se produjo un error interno en el servicio. Se requiere un reintento.
- Duplicate: el servicio ya ha procesado el mensaje con el mismo ackId.

Permisos

Como habrá observado en la descripción anterior del cliente WebSocket de PubSub, un cliente solo puede publicar en otros cuando está autorizado para hacerlo. Se pueden conceder permisos al cliente cuando se conecta o durante la vigencia de la conexión.

Role	Permiso
No especificado	El cliente puede enviar solicitudes de 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 permiso de un cliente se puede conceder de varias maneras:

1. Asignación del rol al cliente al generar el token de acceso

El cliente puede conectarse al servicio mediante un token JWT. La carga del token puede llevar información como la role del cliente. Al firmar el token JWT en el cliente, puede conceder permisos al cliente mediante la asignación al mismo de roles concretos.

Por ejemplo, vamos a firmar un token JWT que tenga permiso para enviar mensajes a group1 y group2:

let token = await serviceClient.getClientAccessToken({
    roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});

2. Asignación del rol al cliente con el controlador de eventos `connect`

Los roles de los clientes también se pueden establecer cuando se registra el controlador de eventos connect y el controlador de eventos ascendente puede devolver el roles del cliente al servicio Web PubSub al controlar los eventos connect.

Por ejemplo, en JavaScript, puede configurar el evento handleConnect para hacerlo:

let handler = new WebPubSubEventHandler("hub1", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
    });
  },
});

3. Asignación del rol al cliente a través de varias API REST o SDK de servidor durante el tiempo de ejecución

let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });