Internos do serviço Azure Web PubSub

Artigo
10/26/2023

O Serviço Azure Web PubSub fornece uma maneira fácil de publicar/assinar mensagens usando conexões WebSocket simples.

Os clientes podem ser escritos em qualquer idioma que tenha suporte a Websocket.
Mensagens de texto e binárias são suportadas em uma conexão.
Há um protocolo simples para os clientes fazerem a publicação direta de mensagens de cliente para cliente.
O serviço gerencia as conexões WebSocket para você.

Termos

Serviço: Azure Web PubSub Service.

Conexão: Uma conexão, também conhecida como uma conexão de cliente ou de cliente, representa uma conexão WebSocket individual conectada ao serviço Web PubSub. Quando conectado com êxito, um ID de conexão exclusivo é atribuído a essa conexão pelo serviço Web PubSub.
Hub: Um hub é um conceito lógico para um conjunto de conexões de cliente. Normalmente, você usa um hub para um cenário, por exemplo, um hub de chat ou um hub de notificação. Quando uma conexão de cliente se conecta, ela se conecta a um hub e, durante sua vida útil, pertence a esse hub. Depois que uma conexão de cliente se conecta ao hub, o hub existe. Aplicativos diferentes podem compartilhar um serviço Azure Web PubSub usando nomes de hub diferentes. Embora não haja um limite estrito para o número de hubs, um hub consome mais carga de serviço em comparação com um grupo. Recomenda-se ter um conjunto predeterminado de hubs em vez de gerá-los dinamicamente.
Grupo: um grupo é um subconjunto de conexões com o hub. Você pode adicionar uma conexão de cliente a um grupo ou remover a conexão de cliente do grupo, sempre que quiser. Por exemplo, quando um cliente entra em uma sala de chat, ou quando um cliente sai da sala de chat, essa sala de chat pode ser considerada um grupo. Um cliente pode ingressar em vários grupos e um grupo pode conter vários clientes. O grupo é como uma "sessão" de grupo, a sessão de grupo é criada quando alguém se junta ao grupo, e a sessão desaparece quando ninguém está no grupo. As mensagens enviadas para o grupo são entregues a todos os clientes conectados ao grupo.
Usuário: As conexões com o Web PubSub podem pertencer a um usuário. Um usuário pode ter várias conexões, por exemplo, quando um único usuário está conectado em vários dispositivos ou várias guias do navegador.
Mensagem: Quando o cliente está conectado, ele pode enviar mensagens para o aplicativo upstream, ou receber mensagens do aplicativo upstream, através da conexão WebSocket. As mensagens podem ser em formato de texto simples, binário ou JSON e têm um tamanho máximo de 1 MB.
Client Connection e ConnectionId: Um cliente se conecta /client ao ponto de extremidade, quando conectado, um exclusivo connectionId é gerado pelo serviço como a identidade exclusiva da conexão do cliente. Os usuários podem gerenciar a conexão do cliente usando este connectionId. Os detalhes são descritos na seção Protocolo do cliente .
Eventos do cliente: os eventos são criados durante o ciclo de vida de uma conexão de cliente. Por exemplo, uma conexão de cliente WebSocket simples cria um evento quando tenta se conectar ao serviço, um evento quando se conecta com êxito ao serviço, um evento quando envia mensagens para o serviço e um connectconnectedmessagedisconnected evento quando se desconecta do serviço. Os detalhes sobre os eventos do cliente são ilustrados na seção Protocolo do cliente.
Manipulador de eventos: O manipulador de eventos contém a lógica para manipular os eventos do cliente. Registre e configure manipuladores de eventos no serviço por meio do portal ou da CLI do Azure previamente. Os detalhes são descritos na seção Manipulador de eventos.
Ouvinte de eventos (visualização): o ouvinte de eventos apenas ouve os eventos do cliente, mas não pode interferir no tempo de vida dos seus clientes através da sua resposta. Os detalhes são descritos na seção Ouvinte de eventos.
Servidor: O servidor pode manipular eventos de cliente, gerenciar conexões de cliente ou publicar mensagens em grupos. Tanto o manipulador de eventos quanto o ouvinte de eventos são considerados do lado do servidor. Os detalhes sobre o servidor são descritos na seção Protocolo do servidor.

Fluxo de trabalho

Diagram showing the Web PubSub service workflow.

Fluxo de trabalho como mostrado no gráfico acima:

Um cliente se conecta ao ponto de extremidade do serviço /client usando o transporte WebSocket. O serviço encaminha cada quadro WebSocket para o upstream (servidor) configurado. A conexão WebSocket pode se conectar com qualquer subprotocolo personalizado para o servidor manipular, ou pode se conectar com o subprotocolo json.webpubsub.azure.v1suportado pelo serviço, que permite que os clientes façam pub/sub diretamente. Os detalhes são descritos no protocolo do cliente.
Em eventos de cliente diferentes, o serviço invoca o servidor usando o protocolo CloudEvents. CloudEvents é uma definição padronizada e independente de protocolo da estrutura e descrição de metadados de eventos hospedados pela Cloud Native Computing Foundation (CNCF). A implementação detalhada do protocolo CloudEvents depende da função de servidor, descrita no protocolo de servidor.
O servidor Web PubSub pode invocar o serviço usando a API REST para enviar mensagens aos clientes ou para gerenciar os clientes conectados. Os detalhes são descritos no protocolo do servidor

Protocolo do cliente

Uma conexão de cliente se conecta /client ao ponto de extremidade do serviço usando o protocolo WebSocket. O protocolo WebSocket fornece canais de comunicação full-duplex através de uma única conexão TCP e foi padronizado pela IETF como RFC 6455 em 2011. A maioria dos idiomas tem suporte nativo para iniciar conexões WebSocket.

O nosso serviço suporta dois tipos de clientes:

Um é chamado de cliente WebSocket simples
O outro é chamado de cliente PubSub WebSocket

O cliente WebSocket simples

Um cliente WebSocket simples, como a nomenclatura indica, é uma conexão WebSocket simples. Ele também pode ter seu subprotocolo personalizado.

Por exemplo, em JS, um cliente WebSocket simples pode ser criado usando o código a seguir.

// 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"
);

Um cliente WebSocket simples segue uma arquitetura cliente-servidor<>, como mostra o diagrama de sequência abaixo: Diagram showing the sequence for a client connection.

Quando o cliente inicia um handshake WebSocket, o serviço tenta invocar o connect manipulador de eventos para handshake WebSocket. Os desenvolvedores podem usar esse manipulador para manipular o handshake WebSocket, determinar o subprotocolo a ser usado, autenticar o cliente e unir o cliente a grupos.
Quando o cliente é conectado com êxito, o serviço invoca um connected manipulador de eventos. Funciona como uma notificação e não impede o cliente de enviar mensagens. Os desenvolvedores podem usar esse manipulador para fazer o armazenamento de dados e podem responder com mensagens para o cliente. O serviço também envia um connected evento para todos os ouvintes de eventos, se houver.
Quando o cliente envia mensagens, o serviço dispara um message evento para o manipulador de eventos para manipular as mensagens enviadas. Este evento é um evento geral que contém as mensagens enviadas em um quadro WebSocket. Seu código precisa enviar as mensagens dentro desse manipulador de eventos. Se o manipulador de eventos retornar o código de resposta sem êxito para, o serviço descartará a conexão do cliente. O serviço também envia um message evento para todos os ouvintes de eventos, se houver. Se o serviço não conseguir encontrar nenhum servidor registrado para receber as mensagens, o serviço também desligará a conexão.
Quando o cliente se desconecta, o serviço tenta disparar o evento para o disconnected manipulador de eventos assim que deteta a desconexão. O serviço também envia um disconnected evento para todos os ouvintes de eventos, se houver.

Cenários

Essas conexões podem ser usadas em uma arquitetura cliente-servidor típica em que o cliente envia mensagens para o servidor e o servidor lida com mensagens de entrada usando manipuladores de eventos. Ele também pode ser usado quando os clientes aplicam subprotocolos existentes em sua lógica de aplicativo.

O cliente PubSub WebSocket

O serviço também suporta um subprotocolo específico chamado json.webpubsub.azure.v1, que permite que os clientes publiquem/assinem diretamente, em vez de uma viagem de ida e volta ao servidor upstream. Chamamos a conexão WebSocket com json.webpubsub.azure.v1 subprotocolo de cliente PubSub WebSocket. Para obter mais informações, consulte a especificação do cliente Web PubSub no GitHub.

Por exemplo, em JS, um cliente PubSub WebSocket pode ser criado usando o código a seguir.

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

Um cliente PubSub WebSocket pode:

Junte-se a um grupo, por exemplo:

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

Saia de um grupo, por exemplo:

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

Publicar mensagens em um grupo, por exemplo:

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

Envie eventos personalizados para o servidor upstream, por exemplo:

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

PubSub WebSocket Subprotocol contém os detalhes do json.webpubsub.azure.v1 subprotocolo.

Você deve ter notado que, para um cliente WebSocket simples, o servidor é uma função obrigatória para receber os message eventos dos clientes. Uma conexão WebSocket simples sempre dispara um message evento quando envia mensagens e sempre depende do lado do servidor para processar mensagens e fazer outras operações. Com a ajuda do json.webpubsub.azure.v1 subprotocolo, um cliente autorizado pode ingressar em um grupo e publicar mensagens diretamente em um grupo. Ele também pode rotear mensagens para diferentes manipuladores de eventos / ouvintes de eventos personalizando o evento ao qual a mensagem pertence.

Cenários

Esses clientes podem ser usados quando os clientes querem falar uns com os outros. As mensagens são enviadas client2 para o serviço e o serviço entrega a mensagem diretamente para client1 se os clientes estão autorizados a fazê-lo.

Cliente1:

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",
    })
  );
};

Cliente2:

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 mostra o exemplo acima, client2 envia dados diretamente para publicando mensagens para Group1client1 as quais client1 está dentro.

Resumo dos eventos do cliente

Os eventos de clientes dividem-se em duas categorias:

Eventos síncronos (bloqueio) Os eventos síncronos bloqueiam o fluxo de trabalho do cliente.
- connect: Este evento é apenas para manipulador de eventos. Quando o cliente inicia um handshake WebSocket, o evento é acionado e os desenvolvedores podem usar connect o manipulador de eventos para manipular o handshake WebSocket, determinar o subprotocolo a ser usado, autenticar o cliente e unir o cliente a grupos.
- message: Este evento é acionado quando um cliente envia uma mensagem.
Eventos assíncronos (sem bloqueio) Os eventos assíncronos não bloqueiam o fluxo de trabalho do cliente, ele age como uma notificação para o servidor. Quando esse gatilho de evento falha, o serviço registra os detalhes do erro.
- connected: Este evento é acionado quando um cliente se conecta ao serviço com êxito.
- disconnected: Este evento é acionado quando um cliente se desconecta do serviço.

Limite de mensagens do cliente

O tamanho máximo de mensagem permitido para um quadro WebSocket é 1MB.

Autenticação de cliente

Fluxo de trabalho de autenticação

O cliente usa um token JWT assinado para se conectar ao serviço. O upstream também pode rejeitar o cliente quando ele é connect manipulador de eventos do cliente de entrada. O manipulador de eventos autentica o cliente especificando o e o roles que o cliente tem na resposta do webhook ou recusa o userId cliente com 401. A seção do manipulador de eventos descreve-o em detalhes.

O gráfico a seguir descreve o fluxo de trabalho.

Diagram showing the client authentication workflow.

Como você deve ter notado quando descrevemos os clientes PubSub WebSocket, um cliente pode publicar para outros clientes somente quando está autorizado . O roles do cliente determina as permissões iniciais que o cliente tem:

Role	Permissão
Não especificado	O cliente pode enviar eventos.
`webpubsub.joinLeaveGroup`	O cliente pode entrar/sair de qualquer grupo.
`webpubsub.sendToGroup`	O cliente pode publicar mensagens em qualquer grupo.
`webpubsub.joinLeaveGroup.<group>`	O cliente pode entrar/sair do grupo `<group>`.
`webpubsub.sendToGroup.<group>`	O cliente pode publicar mensagens no grupo `<group>`.

O lado do servidor também pode conceder ou revogar permissões do cliente dinamicamente através do protocolo do servidor, conforme ilustrado em uma seção posterior.

Protocolo do servidor

O protocolo de servidor fornece a funcionalidade para o servidor manipular eventos de cliente e gerenciar as conexões de cliente e os grupos.

Em geral, o protocolo do servidor contém três funções:

Manipulador de eventos
Gestor de ligações
Ouvinte de eventos

Manipulador de eventos

O manipulador de eventos manipula os eventos de cliente de entrada. Os manipuladores de eventos são registrados e configurados no serviço por meio do portal ou da CLI do Azure. Quando um evento de cliente é acionado, o serviço pode identificar se o evento deve ser tratado ou não. Agora usamos PUSH o modo para invocar o manipulador de eventos. O manipulador de eventos no lado do servidor expõe um ponto de extremidade acessível publicamente para o serviço invocar quando o evento é acionado. Funciona como um gancho de teia.

O serviço Web PubSub fornece eventos de cliente para o webhook upstream usando o protocolo HTTP CloudEvents.

Para cada evento, o serviço formula uma solicitação HTTP POST para o upstream registrado e espera uma resposta HTTP.

Os dados enviados do serviço para o servidor estão sempre no formato CloudEvents binary .

Diagram showing the Web PubSub service event push mode.

Upstream e Validação

Os manipuladores de eventos precisam ser registrados e configurados no serviço por meio do portal ou da CLI do Azure antes do primeiro uso. Quando um evento de cliente é acionado, o serviço pode identificar se o evento deve ser tratado ou não. Para visualização pública, usamos PUSH o modo para invocar o manipulador de eventos. O manipulador de eventos no lado do servidor expõe o ponto de extremidade acessível publicamente para o serviço invocar quando o evento é acionado. Ele atua como um webhookupstream.

A URL pode usar {event} o parâmetro para definir um modelo de URL para o manipulador de webhook. O serviço calcula o valor da URL do webhook dinamicamente quando a solicitação do cliente chega. Por exemplo, quando uma solicitação /client/hubs/chat chega, com um padrão http://host.com/api/{event} de URL do manipulador de eventos configurado para hub chat, quando o cliente se conecta, ele primeiro POST para esta URL: http://host.com/api/connect. Esse comportamento pode ser útil quando um cliente PubSub WebSocket envia eventos personalizados, que o manipulador de eventos ajuda a despachar eventos diferentes para diferentes upstream. O {event} parâmetro não é permitido no nome de domínio da URL.

Ao configurar o manipulador de eventos upstream por meio do portal do Azure ou da CLI, o serviço segue a proteção contra abuso do CloudEvents para validar o webhook upstream. O WebHook-Request-Origin cabeçalho da solicitação é definido como o nome de domínio do serviço e espera que a resposta com cabeçalho WebHook-Allowed-Origin contenha esse nome xxx.webpubsub.azure.comde domínio.

Ao fazer a validação, o {event} parâmetro é resolvido para validate. Por exemplo, ao tentar definir a URL como http://host.com/api/{event}, o serviço tenta OPTIONS uma solicitação para http://host.com/api/validate e somente quando a resposta é válida a configuração pode ser definida com êxito.

Por enquanto, não suportamos WebHook-Request-Rate e WebHook-Request-Callback.

Autenticação/Autorização entre serviço e webhook

Modo anónimo
Autenticação simples fornecida code através do URL Webhook configurado.
Use a autorização do Microsoft Entra. Para obter mais informações, consulte como usar a identidade gerenciada para obter detalhes.
- Etapa 1: Habilitar a identidade para o serviço Web PubSub
- Passo 2: Selecione a partir da aplicação Microsoft Entra existente que representa a sua aplicação web webhook

Gestor de ligações

O servidor é, por natureza, um utilizador autorizado. Com a ajuda da função de manipulador de eventos, o servidor conhece os metadados dos clientes, por exemplo, connectionId e userIdpode:

Fechar uma conexão de cliente
Enviar mensagens a um cliente
Enviar mensagens para clientes que pertencem ao mesmo usuário
Adicionar um cliente a um grupo
Adicionar clientes autenticados como o mesmo usuário a um grupo
Remover um cliente de um grupo
Remover clientes autenticados como o mesmo usuário de um grupo
Publicar mensagens em um grupo

Ele também pode conceder ou revogar permissões de publicação/associação para um cliente PubSub:

Conceder permissões de publicação/ingresso a algum grupo específico ou a todos os grupos
Revogar permissões de publicação/associação para algum grupo específico ou para todos os grupos
Verifique se o cliente tem permissão para participar ou publicar em algum grupo específico ou em todos os grupos

O serviço fornece APIs REST para o servidor fazer o gerenciamento de conexões.

Diagram showing the Web PubSub service connection manager workflow.

O protocolo detalhado da API REST é definido aqui.

Ouvinte de eventos

Nota

O recurso de ouvinte de eventos está em visualização.

O ouvinte de eventos ouve os eventos do cliente de entrada. Cada ouvinte de eventos contém um filtro para especificar os tipos de eventos a que diz respeito, um ponto de extremidade sobre para onde enviar os eventos.

Atualmente, oferecemos suporte a Hubs de Eventos como um ponto de extremidade de ouvinte de eventos.

Você precisa registrar ouvintes de eventos com antecedência, para que, quando um evento de cliente for acionado, o serviço possa enviar o evento para os ouvintes de eventos correspondentes. Consulte este documento para saber como configurar um ouvinte de eventos com um ponto de extremidade do hub de eventos.

Você pode configurar vários ouvintes de eventos. A ordem dos ouvintes do evento não importa. Se um evento corresponder a vários ouvintes de eventos, ele será enviado para todos os ouvintes correspondentes. Veja o diagrama a seguir para obter um exemplo. Digamos que você configure quatro ouvintes de eventos ao mesmo tempo. Em seguida, um evento de cliente que corresponda a três desses ouvintes será enviado para três ouvintes, deixando o restante intocado.

Event listener data flow diagram sample

Você pode combinar um manipulador de eventos e ouvintes de eventos para o mesmo evento. Nesse caso, o manipulador de eventos e os ouvintes de eventos receberão o evento.

O serviço Web PubSub fornece eventos de cliente para ouvintes de eventos usando a extensão AMQP do CloudEvents para o Azure Web PubSub.

Resumo

Você deve ter notado que a função manipulador de eventos lida com a comunicação do serviço para o servidor, enquanto a função de gerente lida com a comunicação do servidor para o serviço. Depois de combinar as duas funções, o fluxo de dados entre o serviço e o servidor é semelhante ao diagrama a seguir usando o protocolo HTTP.

Diagram showing the Web PubSub service bi-directional workflow.