Elementi interni del servizio Azure Web PubSub

Articolo
08/21/2024

Il servizio Web PubSub di Azure offre un modo semplice per pubblicare/sottoscrivere messaggi usando semplici connessioni WebSocket.

I client possono essere scritti in qualsiasi linguaggio con supporto Websocket.
All'interno di una singola connessione sono supportati messaggi sia di testo che binari.
Un protocollo semplice consente ai clienti di pubblicare massaggi direttamente l'uno all'altro.
Il servizio gestisce automaticamente le connessioni WebSocket.

Terms

Servizio: servizio Azure Web PubSub.

Connessione: una connessione, nota anche come client o connessione client, è una relazione logica tra un client e il servizio Web PubSub. Tramite una "connessione", il client e il servizio si impegnano in una serie di interazioni con stato. Le connessioni che usano protocolli diversi possono comportarsi in modo diverso, ad esempio alcune connessioni sono limitate alla durata di una connessione di rete, mentre altre possono estendersi tra più connessioni di rete successive tra un client e il servizio.
Hub: un hub è un concetto logico per un insieme di connessioni client. In genere si usa un hub per uno scenario, ad esempio un hub di chat o un hub di notifica. Quando una connessione client si connette, si connette a un hub e per tutta la sua durata appartiene a tale hub. Quando una connessione client si connette all'hub, l'hub esiste. Diverse applicazioni possono condividere un servizio Web PubSub di Azure usando nomi di hub diversi. Anche se non esiste un limite rigoroso per il numero di hub, un hub usa un carico di servizio maggiore rispetto a un gruppo. È consigliabile avere un set predeterminato di hub anziché generarli in modo dinamico.
Gruppo: un gruppo è un subset di connessioni all'hub. È possibile aggiungere una connessione client a un gruppo o rimuovere la connessione client dal gruppo in qualsiasi momento. Ad esempio, quando un client si unisce a una chat room o quando un client lascia la chat room, questa chat room può essere considerata un gruppo. Un client può partecipare a più gruppi e un gruppo può contenere più client. Il gruppo è simile a una "sessione" di gruppo; la sessione di gruppo viene creata una volta che un utente si unisce al gruppo e viene eliminata quando nessuno si trova nel gruppo. I messaggi inviati al gruppo vengono recapitati a tutti i client connessi al gruppo.
Utente: le connessioni a Web PubSub possono appartenere a un utente. Un utente potrebbe avere più connessioni, ad esempio quando un singolo utente è connesso tra più dispositivi o più schede del browser.
Messaggio: quando il client è connesso, può inviare messaggi all'applicazione upstream o ricevere messaggi dall'applicazione upstream, tramite la connessione WebSocket. I messaggi possono essere in formato testo normale, binario o JSON e hanno una dimensione massima di 1 MB.
Eventi client: eventi vengono creati durante il ciclo di vita di una connessione client. Ad esempio, una semplice connessione client WebSocket crea un evento connect quando tenta di connettersi al servizio, un evento connected quando è connessa correttamente al servizio, un evento message quando invia messaggi al servizio e un evento disconnected quando si disconnette dal servizio. I dettagli sugli eventi client sono illustrati nella sezione Protocollo client.
Gestore eventi: il gestore eventi contiene la logica per gestire gli eventi client. Registrare e configurare in anticipo i gestori eventi nel servizio tramite il portale o l'interfaccia della riga di comando di Azure. I dettagli sono descritti nella sezione Gestore eventi.
Listener di eventi (anteprima): il listener di eventi è in ascolto solo degli eventi client, ma non può interferire con la durata dei client tramite la loro risposta. I dettagli sono descritti nella sezione Listener di eventi.
Server: il server può gestire gli eventi client, gestire le connessioni client o pubblicare messaggi in gruppi. Sia il gestore eventi che il listener di eventi sono considerati lato server. I dettagli sul server sono descritti nella sezione Protocollo server.

Workflow

Diagramma che mostra il flusso di lavoro del servizio Web PubSub.

Flusso di lavoro come illustrato nel grafico precedente:

Un client si connette a un endpoint /client del servizio usando il trasporto WebSocket. Il servizio inoltra ogni frame WebSocket all’upstream (server) configurato. La connessione WebSocket può connettersi a qualsiasi sottoprotocollo personalizzato affinché il server lo gestisca oppure può connettersi con il sottoprotocollo supportato dal servizio json.webpubsub.azure.v1, che consente ai client di eseguire direttamente pub/sub. I dettagli sono descritti nel protocollo client.
In eventi client diversi, il servizio richiama il server usando il protocollo CloudEvents. CloudEvents è una definizione standardizzata e libera dai protocolli dalla struttura e della descrizione dei metadati degli eventi ospitati dalla Cloud Native Computing Foundation (CNCF). L'implementazione dettagliata del protocollo CloudEvents si basa sul ruolo del server, descritto in protocollo server.
Il server Web PubSub può richiamare il servizio usando l'API REST per inviare messaggi ai client o per gestire i client connessi. I dettagli sono descritti in protocollo server

Protocollo client

Una connessione client si connette all'endpoint /client del servizio usando il protocollo WebSocket. Il protocollo WebSocket fornisce canali di comunicazione full-duplex su una singola connessione TCP ed è stato standardizzato da IETF come RFC 6455 nel 2011. La maggior parte dei linguaggi include il supporto nativo per avviare connessioni WebSocket.

Il servizio Microsoft supporta due tipi di client:

Uno è detto semplice WebSocket semplice
L'altro è detto client WebSocket PubSub

Client WebSocket semplice

Un client WebSocket semplice, come indicato dal nome, è una semplice connessione WebSocket. Può anche avere un sottoprotocollo personalizzato.

Ad esempio, in JS è possibile creare un client WebSocket semplice usando il codice seguente.

// 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 semplice client WebSocket segue un'architettura client-server<>, come illustrato nel diagramma di sequenza seguente: Diagramma che mostra la sequenza per una connessione client.

Quando il client avvia un handshake WebSocket, il servizio tenta di richiamare il gestore eventi connect per l'handshake WebSocket. Gli sviluppatori possono usare questo gestore per gestire l'handshake WebSocket, determinare il sottoprotocollo da usare, autenticare il client e aggiungere il client ai gruppi.
Quando il client è connesso correttamente, il servizio richiama un gestore eventi connected. Funziona come notifica e non impedisce al client di inviare messaggi. Gli sviluppatori possono usare questo gestore per eseguire l'archiviazione dei dati e possono rispondere con messaggi al client. Il servizio esegue anche il push di un evento connected a tutti gli eventuali listener di eventi.
Quando il client invia messaggi, il servizio attiva un message evento al gestore eventi. Questo evento contiene i messaggi inviati in un frame WebSocket. Il codice deve inviare i messaggi all'interno di questo gestore eventi. Se il gestore eventi restituisce un codice di risposta non riuscito, il servizio elimina la connessione client. Il servizio esegue anche il push di un message evento a tutti i listener di eventi interessati, se presenti. Se il servizio non riesce a trovare server registrati per ricevere i messaggi, il servizio elimina anche la connessione client.
Quando il client si disconnette, il servizio tenta di attivare l'evento disconnected per il gestore eventi dopo aver rilevato la disconnessione. Il servizio esegue anche il push di un evento disconnected a tutti gli eventuali listener di eventi.

Scenari

Queste connessioni possono essere usate in una tipica architettura client-server in cui il client invia messaggi al server e il server gestisce i messaggi in ingresso usando gestori eventi. Può essere usato anche quando i clienti applicano sottoprotocolli esistenti nella logica dell'applicazione.

Client WebSocket PubSub

Il servizio supporta anche un sottoprotocollo specifico denominato json.webpubsub.azure.v1, che consente ai client la pubblicazione/sottoscrizione diretta anziché un round trip al server upstream. La connessione WebSocket con il sottoprotocollo json.webpubsub.azure.v1 viene detta client WebSocket PubSub. Per altre informazioni, vedere la specifica del client Web PubSub su GitHub.

Ad esempio, in JS è possibile creare un client WebSocket PubSub usando il codice seguente.

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

Un client WebSocket PubSub può:

Unirsi a un gruppo, ad esempio:

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

Abbandonare un gruppo, ad esempio:

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

Pubblicare messaggi in un gruppo, ad esempio:

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

Inviare eventi personalizzati al server upstream, ad esempio:

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

Il sottoprotocollo WebSocket PubSub contiene i dettagli del sottoprotocollo json.webpubsub.azure.v1.

Si è notato che per un semplice client WebSocket, il server deve avere un ruolo per ricevere gli message eventi dai client. Una connessione WebSocket semplice attiva sempre un evento message quando invia messaggi e si basa sempre sul lato server per elaborare i messaggi ed eseguire altre operazioni. Con l'ausilio del sottoprotocollo json.webpubsub.azure.v1, un client autorizzato può unirsi a un gruppo e pubblicare i messaggi direttamente in un gruppo. Può anche instradare i messaggi a gestori eventi/listener di eventi diversi personalizzando l'evento a cui appartiene il messaggio.

Scenari

Tali client possono essere usati quando i client desiderano comunicare tra loro. I messaggi vengono inviati da client2 al servizio e il servizio recapita il messaggio direttamente a client1 se i client sono autorizzati a farlo.

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

Come illustrato nell'esempio precedente, client2 invia i dati direttamente al client1 pubblicando messaggi nel Group1 in cui si trova il client1.

Riepilogo degli eventi client

Gli eventi client rientrano in due categorie:

Eventi sincroni (bloccanti). Gli eventi sincroni bloccano il flusso di lavoro client.
- connect: questo evento è solo per il gestore eventi. Quando il client avvia un handshake WebSocket, l’evento viene attivato e gli sviluppatori possono usare il gestore eventi connect per gestire l’handshake WebSocket, detterminare il sottoprotocollo da usare, autenticare il client e unire il client ai gruppi.
- message: questo evento viene attivato quando un client invia un messaggio.
Gli eventi asincroni (non bloccanti) non bloccano il flusso di lavoro client. Invece, inviano una notifica al server. Quando l’attivazione di un evento non riesce, il servizio registra i dettagli dell'errore.
- connected: questo evento viene attivato quando un client si connette correttamente al servizio.
- disconnected: questo evento viene attivato quando un client si disconnette dal servizio.

Limite dei messaggi client

La dimensione massima consentita dei messaggi per un singolo frame WebSocket è 1 MB.

Autenticazione client

Flusso di lavoro di autenticazione

Il client usa un token JWT firmato per connettersi al servizio. L’upstream può anche rifiutare il client quando è il gestore eventi connect del client in ingresso. Il gestore eventi autentica il client specificando l’userId e i role che ha il client risposta del webhook oppure rifiuta il client con un errore 401. La sezione Gestore eventi lo descrive in dettaglio.

Il grafico seguente descrive il flusso di lavoro.

Diagramma che mostra il flusso di lavoro di autenticazione client.

Un client può pubblicare in altri client solo quando è autorizzato a. Gli roleoggetti del client determinano le autorizzazioni iniziali di cui dispone il client:

Ruolo	Autorizzazione
Non specificato	Il client può inviare eventi.
`webpubsub.joinLeaveGroup`	Il client può unirsi o abbandonare qualsiasi gruppo.
`webpubsub.sendToGroup`	Il client può pubblicare messaggi in qualsiasi gruppo.
`webpubsub.joinLeaveGroup.<group>`	Il client può unirsi o abbandonare il gruppo `<group>`.
`webpubsub.sendToGroup.<group>`	Il client può pubblicare messaggi nel gruppo `<group>`.

Il lato server può anche concedere o revocare le autorizzazioni del client in modo dinamico tramite il protocollo server, come illustrato in una sezione successiva.

Protocollo server

Il protocollo server fornisce al server la funzionalità per gestire gli eventi client e gestire le connessioni client e i gruppi.

In generale, il protocollo server contiene tre ruoli:

Gestore dell'evento
Connection manager
Listener di eventi

Gestore di eventi

Il gestore eventi gestisce gli eventi client in ingresso. I gestori eventi sono registrati e configurati nel servizio tramite il portale o l'interfaccia della riga di comando di Azure. Quando viene attivato un evento client, il servizio può identificare se l'evento deve essere gestito o meno. Ora viene usata la PUSH modalità per richiamare il gestore eventi. Il gestore eventi lato server espone un endpoint accessibile pubblicamente per il servizio da richiamare quando viene attivato l'evento. Funge da webhook.

Il servizio Web PubSub recapita gli eventi client al webhook upstream usando il protocollo HTTP CloudEvents.

Per ogni evento, il servizio formula una richiesta HTTP POST all'upstream registrato e prevede una risposta HTTP.

I dati inviati dal servizio al server sono sempre in formato binary CloudEvents.

Diagramma che mostra la modalità push degli eventi del servizio Web PubSub.

Upstream e convalida

I gestori eventi devono essere registrati e configurati nel servizio tramite il portale o l'interfaccia della riga di comando di Azure. Quando viene attivato un evento client, il servizio può identificare se l'evento deve essere gestito o meno. Per l’anteprima pubblica, viene usata la modalità PUSH per richiamare il gestore eventi. Il gestore eventi lato server espone un endpoint accessibile pubblicamente per il servizio da richiamare quando viene attivato l'evento. Funge da webhook upstream.

L'URL può usare il parametro {event} per definire un modello di URL per il gestore webhook. Il servizio calcola in modo dinamico il valore dell'URL del webhook quando arriva la richiesta del client. Ad esempio, quando arriva una richiesta /client/hubs/chat, con un modello di URL del gestore eventi configurato http://host.com/api/{event} per l'hub chat, quando il client si connette eseguirà prima il POST a questo URL: http://host.com/api/connect. Questo comportamento può essere utile quando un client WebSocket PubSub invia eventi personalizzati e il gestore facilita l’invio di eventi diversi a upstream diversi. Il parametro {event} non è consentito nel nome di dominio URL.

Quando si configura il gestore eventi upstream tramite il portale o l'interfaccia della riga di comando di Azure, il servizio segue la protezione dagli abusi di CloudEvents per convalidare il webhook upstream. L'intestazione della richiesta WebHook-Request-Origin è impostata sul nome di dominio del servizio xxx.webpubsub.azure.com e prevede che la risposta abbia intestazione WebHook-Allowed-Origin per contenere questo nome di dominio.

Quando si esegue la convalida, il parametro {event} viene risolto in validate. Ad esempio, quando si tenta di impostare l'URL su http://host.com/api/{event}, il servizio tenta OPTIONS per una richiesta a http://host.com/api/validate e solo quando la risposta è valida la configurazione può essere impostata correttamente.

Per il momento WebHook-Request-Rate e WebHook-Request-Callback non sono supportati.

Autenticazione/autorizzazione tra il servizio e il webhook

Per stabilire l'autenticazione sicura e l'autorizzazione tra il servizio e il webhook, prendere in considerazione le opzioni e i passaggi seguenti:

Modalità anonima
L'autenticazione semplice, con cui code è fornito tramite l'URL del webhook configurato.
Usare l’autorizzazione di Microsoft Entra. Per informazioni più dettagliate, vedere come l’identità gestita.

Abilitare l'identità per il servizio Web PubSub.
Selezionare un'applicazione Microsoft Entra esistente che rappresenta l'app Webhook.

Connection manager

Il server è per natura un utente autorizzato. Con l'ausilio del ruolo di gestore eventi, il server riconosce i metadati dei client, ad esempio connectionId e userId, in modo che possa:

Chiudere una connessione client
Inviare messaggi a un client
Inviare messaggi ai client che appartengono allo stesso utente
Aggiungere un client a un gruppo
Aggiungere client autenticati come lo stesso utente a un gruppo
Rimuovere un server da un gruppo
Rimuovere client autenticati come lo stesso utente da un gruppo
Pubblicare messaggi in un gruppo

Può anche concedere o revocare le autorizzazioni di pubblicazione/unione per un client PubSub:

Concedere autorizzazioni di pubblicazione/unione a un gruppo specifico o a tutti i gruppi
Revocare autorizzazioni di pubblicazione/unione per un gruppo specifico o per tutti i gruppi
Controllare se il client dispone dell'autorizzazione per unirsi o pubblicare in un gruppo specifico o in tutti i gruppi

Il servizio fornisce API REST per il server per la gestione delle connessioni.

Diagramma che mostra il flusso di lavoro del gestore connessioni del servizio Web PubSub.

Il protocollo dell'API REST dettagliato è definito qui.

Listener di eventi

Nota

La funzionalità del listener di eventi è in anteprima.

Il listener di eventi è in ascolto degli eventi client in ingresso. Ogni listener di eventi contiene un filtro per specificare i tipi di eventi di pertinenza e un endpoint a cui inviare gli eventi.

Attualmente è supportato Hub eventi come endpoint del listener di eventi.

È necessario registrare in anticipo i listener di eventi, in modo che quando viene attivato un evento client, il servizio può eseguire il push dell'evento nei listener di eventi corrispondenti. Vedere questo documento per informazioni su come configurare un listener di eventi con un endpoint dell'hub eventi.

È possibile configurare più listener di eventi. L'ordine in cui vengono configurate non influisce sulla relativa funzionalità. Se un evento corrisponde a più listener, l'evento viene inviato a tutti i listener corrispondenti. Per un esempio, vedere il diagramma seguente. Ad esempio, se si configurano quattro listener di eventi contemporaneamente, ogni listener che riceve una corrispondenza elabora l'evento. Un evento client che corrisponde a tre di questi listener viene inviato a tre listener, con il listener rimanente ignorato.

Esempio di diagramma del flusso di dati di un listener di eventi

È possibile combinare un gestore eventi e listener di eventi per lo stesso evento. In questo caso, sia il gestore eventi che i listener di eventi ricevono l'evento.

Il servizio Web PubSub fornisce eventi client ai listener di eventi usando l’estensione AMQP CloudEvents per Azure Web PubSub.

Riepilogo

Il ruolo gestore eventi gestisce la comunicazione dal servizio al server mentre il ruolo di gestione gestisce la comunicazione dal server al servizio. Dopo aver combinato i due ruoli, il flusso di dati tra il servizio e il server è simile al diagramma seguente usando il protocollo HTTP.

Diagramma che mostra il flusso di lavoro bidirezionale del servizio Web PubSub.