Elementos internos do serviço Azure Web PubSub

Artigo
10/17/2024

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

Os clientes podem ser gravados em qualquer linguagem que dê suporte ao Websocket.
O texto e as mensagens binárias têm suporte em uma conexão.
Um protocolo simples permite que os clientes publiquem massagens diretamente entre si.
O serviço gerencia as conexões WebSocket para você.

Terms

Serviço: Serviço Azure Web PubSub.

Conexão: uma conexão, também conhecida como cliente ou conexão do cliente, é uma relação lógica entre um cliente e o serviço Web PubSub. Em uma "conexão", o cliente e o serviço se envolvem em uma série de interações com estado. Conexões usando diferentes protocolos podem se comportar de maneira diferente, por exemplo, algumas conexões são limitadas à duração de uma conexão de rede, enquanto outras podem se estender por várias conexões de rede sucessivas entre um cliente e o serviço.
Hub: um hub é um conceito lógico para um conjunto de conexões de cliente. Geralmente, você usa um hub para um cenário, por exemplo, um hub de chat ou um hub de notificação. Quando a conexão cliente é estabelecida, ela se conecta a um hub e, durante seu tempo de vida, pertence a esse hub. O hub existe depois que uma conexão de cliente se conecta a ele. Aplicativos diferentes podem compartilhar o mesmo serviço Azure Web PubSub usando nomes de hub diferentes. Embora não haja um limite rígido para o número de hubs, um hub consome mais carga do serviço em comparação com um grupo. É recomendável 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 removê-la do grupo sempre que desejar. 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, que é criada quando alguém entra nele e desaparece quando não há ninguém nesse grupo. As mensagens enviadas ao 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 apenas um usuário está conectado a vários dispositivos ou a várias guias do navegador.
Mensagem: quando o cliente está conectado, ele pode enviar mensagens ao aplicativo upstream ou receber mensagens do aplicativo upstream por meio da conexão do WebSocket. As mensagens podem estar no formato de texto sem formatação, binário ou JSON e ter um tamanho máximo de 1 MB.
Eventos de 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 connect quando ele tenta se conectar ao serviço, um evento connected quando ele se conectou com êxito ao serviço, um evento message quando ele envia mensagens para o serviço e um evento disconnected quando ele se desconecta do serviço. Detalhes sobre eventos de cliente são ilustrados na seção Protocolo de 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 CLI do Azure antecipadamente. Os detalhes são descritos na seção Manipulador de eventos.
Ouvinte de Eventos (versão prévia): o ouvinte de eventos apenas escuta os eventos do cliente, mas não pode interferir no tempo de vida de seus clientes por meio da 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. O manipulador de eventos e o ouvinte de eventos são considerados como estando do lado do servidor. Detalhes sobre o servidor são descritos na seção Protocolo do servidor.

Fluxo de trabalho

Diagrama mostrando o fluxo de trabalho do serviço Web PubSub.

Fluxo de trabalho, conforme exibido no grafo acima:

Um cliente se conecta ao ponto de extremidade de serviço /client usando o transporte WebSocket. O serviço encaminha cada quadro do WebSocket para o upstream configurado (servidor). A conexão WebSocket pode se conectar a qualquer subprotocolo personalizado para o servidor tratar ou pode se conectar com o subprotocolo com suporte do serviço json.webpubsub.azure.v1, o que permite que os clientes façam o pub/sub diretamente. Os detalhes estão descritos em protocolo de cliente.
Em eventos cliente diferentes, o serviço invoca o servidor usando o protocolo HTTP CloudEvents. O CloudEvents é uma definição padronizada e independente de protocolo da estrutura e da descrição de metadados dos eventos hospedados pela CNCF (Cloud Native Computing Foundation). A implementação detalhada do protocolo CloudEvents depende da função de servidor, descrita no protocolo do servidor.
O servidor do 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 em protocolo de servidor

Protocolo do cliente

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

Nosso serviço dá suporte a dois tipos de clientes:

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

O cliente WebSocket simples

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

Por exemplo, no 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 seguinte diagrama de sequência: Diagrama mostrando a sequência de uma conexão de cliente.

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

Cenários

Essas conexões podem ser usadas em uma arquitetura de cliente-servidor típica, onde o cliente envia mensagens para o servidor e o servidor trata as mensagens de entrada usando Manipuladores de eventos. Também pode ser usada quando os clientes aplicam subprotocolos existentes na lógica do aplicativo.

O cliente WebSocket PubSub

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

Por exemplo, no JS, um cliente WebSocket do PubSub 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 WebSocket PubSub pode:

Ingressar em um grupo, por exemplo:

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

Deixar um grupo, por exemplo:

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

Publicar mensagens em um grupo, por exemplo:

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

Enviar eventos personalizados para o servidor upstream, por exemplo:

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

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

Você notou que, para um cliente WebSocket simples, o servidor é uma função imprescindível para receber os eventos message dos clientes. Uma conexão WebSocket simples sempre dispara um evento message quando envia mensagens e sempre se baseia no lado do servidor para processar mensagens e realizar outras operações. Com a ajuda do subprotocolo json.webpubsub.azure.v1, um cliente autorizado pode ingressar em um grupo e publicar mensagens diretamente em um grupo. Também pode rotear mensagens para diferentes manipuladores de eventos/ouvintes de evento personalizando o evento ao qual a mensagem pertence.

Cenários

Esses clientes podem ser usados quando os clientes desejam se comunicar entre si. As mensagens são enviadas de client2 para o serviço e o serviço entrega a mensagem diretamente para client1 se os clientes estiverem autorizados a fazer isso.

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 mostra o exemplo acima, client2 envia dados diretamente para client1 ao publicar mensagens para Group1 nos qual o client1 está.

Resumo de eventos do cliente

Os eventos cliente se enquadram em duas categorias:

Eventos síncronos (bloqueio) de eventos Síncronos bloqueiam o fluxo de trabalho do cliente.
- connect: esse evento se destina apenas ao manipulador de eventos. Quando o cliente inicia um handshake WebSocket, o evento é disparado e os desenvolvedores podem usar o manipulador de eventos connect para manipular o handshake webSocket, determinar o subprotocolo a ser usado, autenticar o cliente e ingressar o cliente em grupos.
- message: esse evento é disparado quando um cliente envia uma mensagem.
Eventos assíncronos (sem bloqueio) Eventos assíncronos não bloqueiam o fluxo de trabalho do cliente. Em vez disso, eles enviam uma notificação para o servidor. Quando esse gatilho de evento falha, o serviço registra em log os detalhes do erro.
- connected: esse evento é disparado quando um cliente se conecta ao serviço com êxito.
- disconnected: esse evento é disparado quando um cliente é desconectado do serviço.

Limite de mensagens do cliente

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

Autenticação do 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 é um manipulador de eventos connect do cliente de entrada. O manipulador de eventos autentica o cliente especificando userId e os roles que o cliente tem na resposta do webhook ou recusa o cliente com 401. A seção do Manipulador de eventos descreve isso em detalhes.

O grafo a seguir descreve o fluxo de trabalho.

Diagrama mostrando o fluxo de trabalho de autenticação de cliente.

Um cliente só pode publicar em outros clientes quando está autorizado. As roles do cliente determinam as permissões iniciais do cliente:

Função	Permissão
Não especificado	O cliente pode enviar eventos.
`webpubsub.joinLeaveGroup`	O cliente pode ingressar/sair de qualquer grupo.
`webpubsub.sendToGroup`	O cliente pode publicar mensagens em qualquer grupo.
`webpubsub.joinLeaveGroup.<group>`	O cliente pode ingressar/sair de qualquer 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 por meio do protocolo de servidor a serem ilustradas em uma seção posterior.

Protocolo de servidor

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

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

Manipulador de eventos
Connection manager
Ouvinte de eventos

Manipulador de eventos

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

O serviço do 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 do CloudEvents binary.

Diagrama mostrando o modo de push de evento do serviço Web PubSub.

Upstream e validação

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

A URL pode usar o parâmetro {event} 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 de URL do manipulador de eventos http://host.com/api/{event} configurado para o hub chat, quando o cliente se conecta, ele primeiro POSTA a URL: http://host.com/api/connect. Este comportamento pode ser útil quando um cliente PubSub WebSocket envia eventos personalizados, que o manipulador de eventos ajuda a expedir eventos diferentes para upstream diferente. O parâmetro {event} não é permitido no nome de domínio da URL.

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

Ao fazer a validação, o parâmetro {event} é resolvido para validate. Por exemplo, ao tentar definir a URL como http://host.com/api/{event}, o serviço tenta OPÇÕES para 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 damos suporte para WebHook-Request-Rate e WebHook-Request-Callback.

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

Para estabelecer a autenticação segura e a autorização entre o serviço e o webhook, considere as seguintes opções e etapas:

Modo anônimo
Autenticação simples code, é fornecida por meio da URL do Webhook configurada.
Use a autorização do Microsoft Entra. Para obter mais informações, confira como usar a identidade gerenciada.

Habilitar Identidade para o serviço Web PubSub.
Selecione entre os aplicativos do Microsoft Entra existentes aquele que representa o seu aplicativo Web de webhook.

Gerenciador de conexões

O servidor é, por natureza, um usuário autorizado. Com a ajuda da função de manipulador de eventos, o servidor conhece os metadados dos clientes, por exemplo, connectionId e userId, para que ele possa:

Fechar uma conexão de cliente
Enviar mensagens para 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 para publicar/ingressar para um cliente PubSub:

Conceder permissões para publicar/ingressar para algum grupo específico ou para todos os grupos
Revogar permissões para publicar/ingressar de algum grupo específico ou de todos os grupos
Verifique se o cliente tem permissão para ingressar ou publicar em algum grupo específico ou em todos os grupos

O serviço fornece APIs REST para que o servidor faça o gerenciamento de conexões.

Diagrama mostrando o fluxo de trabalho do gerenciador de conexões do serviço Web PubSub.

O protocolo de API REST detalhado é definido aqui.

Ouvinte de eventos

Observação

O recurso de ouvinte de eventos está em versão prévia.

O ouvinte de eventos escuta os eventos de cliente de entrada. Cada ouvinte de eventos contém um filtro para especificar a quais tipos de eventos ele se refere, um ponto de extremidade sobre para onde enviar os eventos.

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

Você precisa registrar ouvintes de eventos com antecedência para que, quando um evento cliente for disparado, o serviço possa enviar o evento por push para os ouvintes de eventos correspondentes. Confira 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 na qual você os configura não afeta a funcionalidade. Se um evento corresponder a vários ouvintes, o evento será enviado para todos os ouvintes correspondentes. Veja um exemplo no diagrama a seguir. Por exemplo, se você configurar quatro ouvintes de eventos simultaneamente, cada ouvinte que recebe uma correspondência processará o evento. Um evento cliente que corresponde a três desses ouvintes é enviado para três ouvintes, com o ouvinte restante ignorado.

Exemplo de diagrama de fluxo de dados do ouvinte de eventos

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

A função de manipulador de eventos manipula a comunicação do serviço com o servidor enquanto a função de gerente lida com a comunicação do servidor com o serviço. Depois de combinar as duas funções, o fluxo de dados entre o serviço e o servidor será semelhante ao diagrama a seguir usando o protocolo HTTP.

Diagrama mostrando o fluxo de trabalho bidirecional do serviço Web PubSub.