Tutorial sulla creazione di un servizio di chat WebSocket per Cloud Run

Questo tutorial mostra come creare un servizio di chat in tempo reale multistanza utilizzando WebSocket con una connessione persistente per la comunicazione bidirezionale. Con WebSocket, sia il client che il server possono inviarsi messaggi a vicenda senza interrogare il server per gli aggiornamenti.

Sebbene tu possa configurare Cloud Run per utilizzare l'affinità di sessione, questa fornisce un'affinità best effort, il che significa che qualsiasi nuova richiesta può comunque essere potenzialmente indirizzata a un'istanza diversa. Di conseguenza, i messaggi degli utenti nel servizio di chat devono essere sincronizzati in tutte le istanze, non solo tra i client connessi a un'istanza.

Progettare un servizio di chat in tempo reale

Questo servizio di chat di esempio utilizza un'istanza Memorystore for Redis per archiviare e sincronizzare i messaggi degli utenti in tutte le istanze. Redis utilizza un meccanismo Pub/Sub, da non confondere con il prodotto Cloud Pub/Sub, per eseguire il push dei dati ai client abbonati connessi a qualsiasi istanza, in modo da eliminare il polling HTTP per gli aggiornamenti.

Tuttavia, anche con gli aggiornamenti push, qualsiasi istanza creata riceverà solo i nuovi messaggi inviati al contenitore. Per caricare i messaggi precedenti, la cronologia dei messaggi deve essere archiviata e recuperata da una soluzione di archiviazione permanente. Questo esempio utilizza la funzionalità convenzionale di Redis di un archivio di oggetti per memorizzare nella cache e recuperare la cronologia dei messaggi.

L'istanza Redis è protetta da internet tramite IP privati con accesso controllato e limitato ai servizi in esecuzione sulla stessa rete privata virtuale dell'istanza Redis. Ti consigliamo di utilizzare VPC diretto in uscita.

Limitazioni

• Questo tutorial non mostra l'autenticazione degli utenti finali o la memorizzazione nella cache delle sessioni. Per scoprire di più sull'autenticazione degli utenti finali, consulta il tutorial di Cloud Run sull'autenticazione degli utenti finali.

• Questo tutorial non implementa un database come Firestore per l'archiviazione e il recupero indefiniti della cronologia dei messaggi di chat.

• Per rendere questo servizio di esempio pronto per la produzione sono necessari elementi aggiuntivi. Per fornire alta disponibilità tramite la replica e il failover automatico, è consigliata un'istanza Redis di livello standard.

Obiettivi

• Scrivi, crea ed esegui il deployment di un servizio Cloud Run che utilizza WebSocket.

• Connettiti a un'istanza Memorystore for Redis per pubblicare e sottoscrivere nuovi messaggi tra le istanze.

• Collega il servizio Cloud Run a Memorystore utilizzando l'uscita VPC diretto.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Cloud Build
• Artifact Registry
• Memorystore
• Cloud Run

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova gratuita.

Prima di iniziare

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Enable the Cloud Run, Memorystore for Redis, Artifact Registry, and Cloud Build APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

2. Installa e inizializza gcloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare il tutorial, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Lettore Artifact Registry (roles/artifactregistry.reader)
• Editor Cloud Build (roles/cloudbuild.builds.editor)
• Amministratore Cloud Memorystore Redis (roles/redis.admin)
• Cloud Run Admin (roles/run.admin)
• Crea service account (roles/iam.serviceAccountCreator)
• Project IAM Admin (roles/resourcemanager.projectIamAdmin)
• Amministratore service account (roles/iam.serviceAccountAdmin)
• Consumer Service Usage (roles/serviceusage.serviceUsageConsumer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Nota:i ruoli di base IAM potrebbero contenere anche autorizzazioni per completare il tutorial. Non devi concedere ruoli di base in un ambiente di produzione, ma puoi concederli in un ambiente di sviluppo o test.

Configurare i valori predefiniti di gcloud

Per configurare gcloud con i valori predefiniti per il tuo servizio Cloud Run:

1. Imposta il progetto predefinito:

   gcloud config set project PROJECT_ID

   Sostituisci PROJECT_ID con il nome del progetto che hai creato per questo tutorial.

2. Configura gcloud per la regione scelta:

   gcloud config set run/region REGION

   Sostituisci REGION con la regione Cloud Run supportata che preferisci.

Località Cloud Run

Cloud Run è regionale, il che significa che l'infrastruttura che esegue i tuoi servizi Cloud Run si trova in una regione specifica ed è gestita da Google per essere disponibile in modo ridondante in tutte le zone all'interno di quella regione.

Il rispetto dei requisiti di latenza, disponibilità o durabilità sono fattori primari per la selezione della regione in cui vengono eseguiti i servizi Cloud Run. In genere puoi selezionare la regione più vicina ai tuoi utenti, ma devi considerare la posizione degli altri Google Cloud prodotti utilizzati dal tuo servizio Cloud Run. L'utilizzo combinato dei prodotti Google Cloud in più località può influire sulla latenza e sui costi del servizio.

Cloud Run è disponibile nelle seguenti regioni:

Soggetto ai prezzi di Livello 1

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• asia-south1 (Mumbai, India)
• europe-north1 (Finlandia) Bassi livelli di CO₂
• europe-north2 (Stoccolma) Bassi livelli di CO₂
• europe-southwest1 (Madrid) Bassi livelli di CO₂
• europe-west1 (Belgio) Bassi livelli di CO₂
• europe-west4 (Paesi Bassi) Bassi livelli di CO₂
• europe-west8 (Milano)
• europe-west9 (Parigi) Bassi livelli di CO₂
• me-west1 (Tel Aviv)
• northamerica-south1 (Messico)
• us-central1 (Iowa) Bassi livelli di CO₂
• us-east1 (Carolina del Sud)
• us-east4 (Virginia del Nord)
• us-east5 (Columbus)
• us-south1 (Dallas) Bassi livelli di CO₂
• us-west1 (Oregon) Bassi livelli di CO₂

Soggetto ai prezzi di Livello 2

• africa-south1 (Johannesburg)
• asia-east2 (Hong Kong)
• asia-northeast3 (Seul, Corea del Sud)
• asia-southeast1 (Singapore)
• asia-southeast2 (Giacarta)
• asia-south2 (Delhi, India)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Varsavia, Polonia)
• europe-west10 (Berlino)
• europe-west12 (Torino)
• europe-west2 (Londra, Regno Unito) Bassi livelli di CO₂
• europe-west3 (Francoforte, Germania)
• europe-west6 (Zurigo, Svizzera) A basse emissioni di CO₂
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) Bassi livelli di CO₂
• northamerica-northeast2 (Toronto) Bassi livelli di CO₂
• southamerica-east1 (San Paolo, Brasile) Bassi livelli di CO₂
• southamerica-west1 (Santiago, Cile) Bassi livelli di CO₂
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

Se hai già creato un servizio Cloud Run, puoi visualizzare la regione nella dashboard di Cloud Run nella consoleGoogle Cloud .

Ok

Recupera il esempio di codice

Per recuperare l'esempio di codice da utilizzare:

1. Clona il repository di esempio sulla tua macchina locale:

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   In alternativa puoi scaricare l'esempio come file ZIP ed estrarlo.

2. Passa alla directory che contiene il codice campione di Cloud Run:

   Node.js

   cd nodejs-docs-samples/run/websockets/

Comprendere il codice WebSockets

Socket.io è una libreria che consente la comunicazione bidirezionale in tempo reale tra il browser e il server. Sebbene Socket.io non sia un'implementazione di WebSocket, esegue il wrapping della funzionalità per fornire un'API più semplice per più protocolli di comunicazione con funzionalità aggiuntive come affidabilità migliorata, riconnessione automatica e trasmissione a tutti o a un sottoinsieme di client.

Integrazione lato client

<script src="/socket.io/socket.io.js"></script>

Il client crea una nuova istanza socket per ogni connessione. Poiché questo esempio viene sottoposto a rendering lato server, non è necessario definire l'URL del server. L'istanza del socket può emettere ed ascoltare eventi.

// Initialize Socket.io
const socket = io('', {
  transports: ['websocket'],
});

// Emit "sendMessage" event with message
socket.emit('sendMessage', msg, error => {
  if (error) {
    console.error(error);
  } else {
    // Clear message
    $('#msg').val('');
  }
});

// Listen for new messages
socket.on('message', msg => {
  log(msg.user, msg.text);
});

// Listen for notifications
socket.on('notification', msg => {
  log(msg.title, msg.description);
});

// Listen connect event
socket.on('connect', () => {
  console.log('connected');
});

Nota :per un'architettura a più istanze senza affinità sessione, Socket.io deve utilizzare solo il trasporto Websocket. Se Socket.io esegue il fallback al long polling, invierà più richieste HTTP durante la durata della sessione. La prima richiesta stabilisce un "handshake" con informazioni importanti come l'ID sessione. Dopo la prima richiesta, le richieste potrebbero essere indirizzate a un'altra istanza che genererà un errore perché l'ID sessione è sconosciuto al server.

Integrazione lato server

Sul lato server, il server Socket.io viene inizializzato e collegato al server HTTP. Analogamente al lato client, una volta che il server Socket.io stabilisce una connessione al client, viene creata un'istanza socket per ogni connessione che può essere utilizzata per inviare e ascoltare i messaggi. Socket.io fornisce anche un'interfaccia per creare "stanze" o un canale arbitrario a cui i socket possono partecipare e abbandonare.

// Initialize Socket.io
const server = require('http').Server(app);
const io = require('socket.io')(server);

const {createAdapter} = require('@socket.io/redis-adapter');
// Replace in-memory adapter with Redis
const subClient = redisClient.duplicate();
io.adapter(createAdapter(redisClient, subClient));
// Add error handlers
redisClient.on('error', err => {
  console.error(err.message);
});

subClient.on('error', err => {
  console.error(err.message);
});

// Listen for new connection
io.on('connection', socket => {
  // Add listener for "signin" event
  socket.on('signin', async ({user, room}, callback) => {
    try {
      // Record socket ID to user's name and chat room
      addUser(socket.id, user, room);
      // Call join to subscribe the socket to a given channel
      socket.join(room);
      // Emit notification event
      socket.in(room).emit('notification', {
        title: "Someone's here",
        description: `${user} just entered the room`,
      });
      // Retrieve room's message history or return null
      const messages = await getRoomFromCache(room);
      // Use the callback to respond with the room's message history
      // Callbacks are more commonly used for event listeners than promises
      callback(null, messages);
    } catch (err) {
      callback(err, null);
    }
  });

  // Add listener for "updateSocketId" event
  socket.on('updateSocketId', async ({user, room}) => {
    try {
      addUser(socket.id, user, room);
      socket.join(room);
    } catch (err) {
      console.error(err);
    }
  });

  // Add listener for "sendMessage" event
  socket.on('sendMessage', (message, callback) => {
    // Retrieve user's name and chat room  from socket ID
    const {user, room} = getUser(socket.id);
    if (room) {
      const msg = {user, text: message};
      // Push message to clients in chat room
      io.in(room).emit('message', msg);
      addMessageToCache(room, msg);
      callback();
    } else {
      callback('User session not found.');
    }
  });

  // Add listener for disconnection
  socket.on('disconnect', () => {
    // Remove socket ID from list
    const {user, room} = deleteUser(socket.id);
    if (user) {
      io.in(room).emit('notification', {
        title: 'Someone just left',
        description: `${user} just left the room`,
      });
    }
  });
});

Socket.io fornisce anche un adattatore Redis per trasmettere eventi a tutti i client indipendentemente dal server che gestisce il socket. Socket.io utilizza solo il meccanismo Pub/Sub di Redis e non archivia alcun dato.

const {createAdapter} = require('@socket.io/redis-adapter');
// Replace in-memory adapter with Redis
const subClient = redisClient.duplicate();
io.adapter(createAdapter(redisClient, subClient));

L'adattatore Redis di Socket.io può riutilizzare il client Redis utilizzato per archiviare la cronologia dei messaggi della stanza virtuale. Ogni container creerà una connessione all'istanza Redis e Cloud Run può creare un numero elevato di istanze. Questo valore è ben al di sotto delle 65.000 connessioni supportate da Redis.

Nota: il ciclo di vita del container Cloud Run non tiene conto delle richieste in uscita, come le connessioni Redis; pertanto, una connessione attiva a Redis non impedirà lo scale in del container.

Riconnessione

Cloud Run ha un timeout massimo di 60 minuti. Devi quindi aggiungere una logica di riconnessione per i possibili timeout. In alcuni casi, Socket.io tenta automaticamente di riconnettersi dopo eventi di disconnessione o errore di connessione. Non è garantito che il client si riconnetta alla stessa istanza.

// Listen for reconnect event
socket.io.on('reconnect', () => {
  console.log('reconnected');
  // Emit "updateSocketId" event to update the recorded socket ID with user and room
  socket.emit('updateSocketId', {user, room}, error => {
    if (error) {
      console.error(error);
    }
  });
});

// Add listener for "updateSocketId" event
socket.on('updateSocketId', async ({user, room}) => {
  try {
    addUser(socket.id, user, room);
    socket.join(room);
  } catch (err) {
    console.error(err);
  }
});

Le istanze verranno mantenute se è presente una connessione attiva finché tutte le richieste non vengono chiuse o non vanno in timeout. Anche se utilizzi l'affinità di sessione di Cloud Run, è possibile che il bilanciamento del carico delle nuove richieste venga eseguito sui container attivi, il che consente di fare lo scale in i container. Se ti preoccupa il numero elevato di container che persistono dopo un picco di traffico, puoi ridurre il valore massimo del timeout, in modo che i socket inutilizzati vengano puliti più spesso.

Spedire il servizio

1. Crea un'istanza Memorystore for Redis:

   gcloud redis instances create INSTANCE_ID --size=1 --region=REGION

   Sostituisci quanto segue:

   • INSTANCE_ID: il nome dell'istanza, ad esempio my-redis-instance.
   • REGION_ID: la regione per tutte le tue risorse e i tuoi servizi, ad esempio europe-west1.

   All'istanza verrà allocato automaticamente un intervallo IP dall'intervallo di rete di servizio predefinito. Questo tutorial utilizza 1 GB di memoria per la cache locale dei messaggi nell'istanza Redis. Scopri di più su come determinare le dimensioni iniziali di un'istanza Memorystore per il tuo caso d'uso.

2. Definisci una variabile di ambiente con l'indirizzo IP della rete autorizzata della tua istanza Redis:

    export REDISHOST=$(gcloud redis instances describe INSTANCE_ID --region REGION --format "value(host)")

   Nota: questo tutorial utilizza il valore predefinito per la porta Redis, 6379.

3. Crea un account di servizio che funga da identità del servizio. Per impostazione predefinita, questo non ha privilegi diversi dall'appartenenza al progetto.

   gcloud iam service-accounts create chat-identity
   gcloud projects add-iam-policy-binding PROJECT_ID \
   --member=serviceAccount:chat-identity@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/serviceusage.serviceUsageConsumer

4. Trova il nome della rete VPC autorizzata per l'istanza Redis eseguendo questo comando:

     gcloud redis instances describe INSTANCE_ID --region REGION --format "value(authorizedNetwork)"
   

   Sostituisci quanto segue:

   • INSTANCE_ID: il nome dell'istanza, ad esempio my-redis-instance.
   • REGION_ID: la regione per tutte le tue risorse e i tuoi servizi, ad esempio europe-west1.

   Prendi nota del nome della rete VPC.

5. Crea ed esegui il deployment dell'immagine container su Cloud Run:

   gcloud run deploy chat-app --source . \
       --allow-unauthenticated \
       --timeout 3600 \
       --service-account chat-identity \
       --network NETWORK \
       --subnet SUBNET \
       --update-env-vars REDISHOST=$REDISHOST

   Sostituisci quanto segue:

   • NETWORK è il nome della rete VPC autorizzata a cui è collegata l'istanza Redis.
   • SUBNET è il nome della subnet. La subnet deve essere /26 o superiore. L'uscita VPC diretta supporta gli intervalli IPv4 RFC 1918, RFC 6598 e Classe E.

   Rispondi a eventuali richieste di installazione delle API necessarie rispondendo y quando richiesto. Devi farlo solo una volta per progetto. Rispondi agli altri prompt fornendo la piattaforma e la regione, se non hai impostato valori predefiniti per questi elementi come descritto nella pagina di configurazione. Scopri di più sul deployment dal codice sorgente.

Prova il servizio

Per provare il servizio completo:

1. Nel browser, vai all'URL fornito dal passaggio di deployment.

2. Aggiungi il tuo nome e una chat room per accedere.

3. Invia un messaggio alla stanza virtuale.

Operazione riuscita: hai creato un servizio di chat in tempo reale multistanza utilizzando WebSocket per mantenere una connessione persistente per la comunicazione bidirezionale.

Se scegli di continuare a sviluppare questi servizi, ricorda che hanno accesso Identity and Access Management (IAM) limitato al resto di Google Cloud e dovranno essere assegnati ruoli IAM aggiuntivi per accedere a molti altri servizi.

Esegui la pulizia

Per evitare addebiti aggiuntivi al tuo account Google Cloud , elimina tutte le risorse che hai implementato con questo tutorial.

Elimina il progetto

Se hai creato un nuovo progetto per questo tutorial, eliminalo. Se hai utilizzato un progetto esistente e devi conservarlo senza le modifiche che hai aggiunto in questo tutorial, elimina le risorse che hai creato per il tutorial.

Il modo più semplice per eliminare la fatturazione è eliminare il progetto creato per il tutorial.

Per eliminare il progetto:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Elimina le risorse del tutorial

1. Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial. I servizi Cloud Run non comportano costi finché non ricevono richieste.

   Per eliminare il servizio Cloud Run, esegui questo comando:

   gcloud run services delete SERVICE-NAME

   Sostituisci SERVICE-NAME con il nome del servizio.

   Puoi anche eliminare i servizi Cloud Run dalla consoleGoogle Cloud .

2. Rimuovi la configurazione della regione predefinita gcloud che hai aggiunto durante la configurazione del tutorial:

    gcloud config unset run/region
   

3. Rimuovi la configurazione del progetto:

    gcloud config unset project
   

4. Elimina le altre Google Cloud risorse create in questo tutorial:

   • Elimina l'immagine container del servizio denominata gcr.io/PROJECT_ID/chat-app da Artifact Registry
   • Elimina il account di servizio chat-identity@PROJECT_ID.iam.gserviceaccount.com
   • Elimina l'istanza Memorystore for Redis

Passaggi successivi

• Scopri di più su come funziona Socket.io e sull'utilizzo più avanzato.

• Scopri di più sul VPC diretto per il traffico di rete in uscita con una rete VPC.

• Consulta le best practice per Memorystore e per l'utilizzo di WebSocket su Cloud Run.