Tutorial: como criar um serviço de chat WebSocket para o Cloud Run

Neste tutorial, você vai aprender a criar um serviço de chat em tempo real com várias salas usando WebSockets com uma conexão persistente para comunicação bidirecional. Com WebSockets, o cliente e o servidor podem enviar mensagens uns para os outros sem procurar atualizações no servidor.

Embora seja possível configurar o Cloud Run para usar a afinidade da sessão, isso fornece uma afinidade de melhor esforço, o que significa que qualquer nova solicitação ainda poderá ser possivelmente roteada para uma instância diferente. Consequentemente, as mensagens dos usuários no serviço de chat precisam ser sincronizadas em todas as instâncias, não apenas entre os clientes conectados a uma instância.

Design para um serviço de chat em tempo real

Este serviço de chat de amostra usa uma instância do Memorystore para Redis para armazenar e sincronizar mensagens de usuários em todas as instâncias. O Redis usa um mecanismo Pub/Sub, não confundir com o produto Cloud Pub/Sub, para enviar dados a clientes inscritos conectados a qualquer instância, eliminando a pesquisa de HTTP para atualizações.

No entanto, mesmo com atualizações push, qualquer instância de contêiner ativada receberá apenas novas mensagens enviadas ao contêiner. Para carregar mensagens anteriores, o histórico de mensagens precisaria ser armazenado e recuperado de uma solução de armazenamento permanente. Neste exemplo, usamos a funcionalidade convencional do Redis de um armazenamento de objetos para armazenar em cache e recuperar o histórico de mensagens.

A instância do Redis é protegida da Internet usando IPs privados com acesso controlado e limitado a serviços em execução na mesma rede privada virtual que a instância do Redis. Recomendamos que você use a saída direta da VPC.

Limitações

• Neste tutorial, não mostramos a autenticação do usuário final ou o armazenamento em cache da sessão. Para saber mais sobre a autenticação de usuários finais, consulte o tutorial do Cloud Run sobre autenticação do usuário final.

• Neste tutorial, não implementamos um banco de dados como o Firestore para armazenamento e recuperação indefinidos do histórico de mensagens do chat.

• São necessários elementos adicionais para que este serviço de amostra esteja pronto para produção. Uma instância do Redis de nível padrão é recomendada para fornecer alta disponibilidade usando a replicação e o failover automático.

Objetivos

• Gravar, criar e implantar um serviço do Cloud Run que usa WebSockets.

• Conecte-se a uma instância do Memorystore para Redis para publicar e assinar novas mensagens em instâncias de contêiner.

• Conecte o serviço do Cloud Run com o Memorystore usando a saída VPC direta.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

• Cloud Build
• Artifact Registry
• Memorystore
• Cloud Run

Para gerar uma estimativa de custo baseada na sua projeção de uso, utilize a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Antes de começar

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. Instale e inicialize a gcloud CLI.

Funções exigidas

Para conseguir as permissões necessárias a fim de concluir o tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Leitor do Artifact Registry (roles/artifactregistry.reader)
• Editor do Cloud Build (roles/cloudbuild.builds.editor)
• Administrador do Cloud Memorystore para Redis (roles/redis.admin)
• Administrador do Cloud Run (roles/run.admin)
• Criar contas de serviço (roles/iam.serviceAccountCreator)
• Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
• Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
• Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Observação: os papéis básicos do IAM também podem conter permissões para concluir o tutorial. Não conceda papéis básicos em um ambiente de produção, mas é possível fazer isso em um ambiente de desenvolvimento ou teste.

Configurar os padrões da gcloud

Para configurar a gcloud com os padrões do serviço do Cloud Run, realize as etapas a seguir:

1. Defina seu projeto padrão:

   gcloud config set project PROJECT_ID

   Substitua PROJECT_ID pelo nome do projeto que você criou para este tutorial.

2. Configure a gcloud para a região escolhida:

   gcloud config set run/region REGION

   Substitua REGION pela região compatível do Cloud Run.

Locais do Cloud Run

O Cloud Run é regional, o que significa que a infraestrutura que executa seus serviços do Cloud Run está localizada em uma região específica e é gerenciada pelo Google para estar disponível de maneira redundante em todas as zonas da região.

Atender aos seus requisitos de latência, disponibilidade ou durabilidade são os principais fatores para selecionar a região em que seus serviços do Cloud Run são executados. Geralmente, é possível selecionar a região mais próxima de seus usuários, mas considere a localização dos outros Google Cloud produtos usados pelo serviço do Cloud Run. O uso de produtos do Google Cloud em vários locais pode afetar a latência e o custo do serviço.

O Cloud Run está disponível nas regiões a seguir:

Sujeitas aos preços do nível 1

• asia-east1 (Taiwan)
• asia-northeast1 (Tóquio)
• asia-northeast2 (Osaka)
• asia-south1 (Mumbai, Índia)
• europe-north1 (Finlândia) Baixo CO₂
• europe-north2 (Estocolmo) Baixo CO₂
• europe-southwest1 (Madri) Baixo CO₂
• europe-west1 (Bélgica) Baixo CO₂
• europe-west4 (Países Baixos) Baixo CO₂
• europe-west8 (Milão)
• europe-west9 (Paris) Baixo CO₂
• me-west1 (Tel Aviv)
• northamerica-south1 (México)
• us-central1 (Iowa) Baixo CO₂
• us-east1 (Carolina do Sul)
• us-east4 (Norte da Virgínia)
• us-east5 (Columbus)
• us-south1 (Dallas) Baixo CO₂
• us-west1 (Oregon) Baixo CO₂

Sujeitas aos preços do nível 2

• africa-south1 (Johannesburgo)
• asia-east2 (Hong Kong)
• asia-northeast3 (Seul, Coreia do Sul)
• asia-southeast1 (Singapura)
• asia-southeast2 (Jacarta)
• asia-south2 (Déli, Índia)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Varsóvia, Polônia)
• europe-west10 (Berlim)
• europe-west12 (Turim)
• europe-west2 (Londres, Reino Unido) Baixo CO₂
• europe-west3 (Frankfurt, Alemanha)
• europe-west6 (Zurique, Suíça) Baixo CO₂
• me-central1 (Doha)
• me-central2 (Damã)
• northamerica-northeast1 (Montreal) Baixo CO₂
• northamerica-northeast2 (Toronto) Baixo CO₂
• southamerica-east1 (São Paulo, Brasil) Baixo CO₂
• southamerica-west1 (Santiago, Chile) Baixo CO₂
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

Se você já criou um serviço do Cloud Run, é possível visualizar a região no painel do Cloud Run no console doGoogle Cloud .

OK

Recuperar a amostra de código

Para recuperar o exemplo de código para uso, siga estas etapas:

1. Clone o repositório de amostra na máquina local:

   Node.js

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

   Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

2. Mude para o diretório que contém o código de amostra do Cloud Run:

   Node.js

   cd nodejs-docs-samples/run/websockets/

Entenda o código do WebSocket

O Socket.io é uma biblioteca que permite a comunicação bidirecional em tempo real entre o navegador e o servidor. Embora o Socket.io não seja uma implementação WebSocket, ele une a funcionalidade para fornecer uma API mais simples para vários protocolos de comunicação com recursos adicionais, como maior confiabilidade, reconexão automática e transmissão para todos ou um subconjunto de clientes.

Integração no lado do cliente

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

O cliente instancia uma nova instância de soquete para cada conexão. Como este exemplo é renderizado no servidor, o URL do servidor não precisa ser definido. A instância de soquete pode emitir e ouvir eventos.

// 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');
});

Observação: para uma arquitetura de várias instâncias sem afinidade da sessão, o Socket.io precisa usar apenas o transporte Websocket. Se o Socket.io voltar à pesquisa longa, ele enviará várias solicitações HTTP durante a vida útil da sessão. A primeira solicitação estabelece um "handshake" com informações importantes como o ID da sessão. Após a primeira solicitação, as solicitações podem ser roteadas para outra instância que vai gerar um erro porque o ID da sessão é desconhecido para o servidor.

Integração no servidor

No servidor, o servidor Socket.io é inicializado e anexado ao servidor HTTP. Semelhante ao lado do cliente, uma vez que o servidor Socket.io faz uma conexão com o cliente, uma instância de soquete é criada para cada conexão que pode ser usada para emitir e ouvir mensagens. Ele também oferece uma interface para criar "salas" ou um canal arbitrário em que os soquetes podem entrar e sair.

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

O Socket.io também fornece um adaptador Redis para transmitir eventos para todos os clientes, independentemente de qual servidor está veiculando o soquete. O Socket.io usa apenas o mecanismo Pub/Sub do Redis e não armazena dados.

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

O adaptador Redis do Socket.io pode reutilizar o cliente Redis usado para armazenar o histórico de mensagens da sala. Cada contêiner cria uma conexão com a instância do Redis e o Cloud Run pode criar um grande número de instâncias. Isso está dentro das 65.000 conexões compatíveis com o Redis.

Observação: o ciclo de vida do contêiner do Cloud Run não considera solicitações de saída, como conexões do Redis. Portanto, uma conexão ativa com o Redis não impede que o contêiner seja reduzido.

Reconexão

O Cloud Run tem um tempo limite máximo de 60 minutos. Portanto, você precisa adicionar a lógica de reconexão para possíveis tempos limite. Em alguns casos, o Socket.io tenta se reconectar automaticamente após eventos de desconexão ou erro de conexão. Não há garantia de que o cliente se reconectará à mesma instância de contêiner.

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

As instâncias vão persistir se houver uma conexão ativa até que todas as solicitações sejam encerradas ou expirem. Mesmo que você use a afinidade da sessão do Cloud Run, é possível que novas solicitações tenham a carga balanceada para contêineres ativos. Isso permite a redução do reduzir escalonamento horizontal. Se você estiver preocupado com um grande número de contêineres que persistem após um pico de tráfego, diminua o valor máximo de tempo limite para que os soquetes não utilizados sejam limpos com mais frequência.

Enviar o serviço

1. Crie uma instância do Memorystore para Redis:

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

   Substitua:

   • INSTANCE_ID: o nome da instância, por exemplo, my-redis-instance.
   • REGION_ID: a região de todos os seus recursos e serviços, por exemplo, europe-west1.

   A instância receberá automaticamente um intervalo de IP do intervalo de rede de serviço padrão. Neste tutorial, 1 GB de memória é usado para o cache local de mensagens na instância do Redis. Saiba mais sobre Como determinar o tamanho inicial de uma instância do Memorystore para seu caso de uso.

2. Defina uma variável de ambiente com o endereço IP da rede autorizada da instância do Redis:

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

   Observação: este tutorial usa o valor padrão para a porta do Redis, 6379.

3. Crie uma conta de serviço para servir como a identidade de serviço. Por padrão, ela não tem privilégios além da associação ao projeto.

   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. Encontre o nome da rede VPC autorizada pela instância do Redis executando o seguinte comando:

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

   Substitua:

   • INSTANCE_ID: o nome da instância, por exemplo, my-redis-instance.
   • REGION_ID: a região de todos os seus recursos e serviços, por exemplo, europe-west1.

   Anote o nome da rede VPC.

5. Crie e implante a imagem do contêiner no 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

   Substitua:

   • NETWORK é o nome da rede VPC autorizada a que a instância do Redis está anexada.
   • SUBNET é o nome da sub-rede. A sub-rede precisa ser /26 ou maior. A saída de VPC direta é compatível com intervalos IPv4 RFC 1918, RFC 6598 e classe E.

   Responda a todas as solicitações para instalar as APIs necessárias respondendo ao y quando solicitado. Você só precisa fazer isso uma vez para um projeto. Responda a outras solicitações fornecendo a plataforma e a região, se você não tiver definido os padrões delas, conforme descrito na página de configuração. Saiba mais sobre como implantar a partir do código-fonte.

Testar o serviço

Para testar o serviço completo:

1. Navegue até o URL fornecido pela etapa de implantação.

2. Adicione seu nome e uma sala de chat para fazer login.

3. Envie uma mensagem para a sala.

Sucesso: você criou um serviço de chat em tempo real com várias salas usando WebSockets para manter uma conexão persistente para comunicação bidirecional.

Se você optar por continuar desenvolvendo esses serviços, lembre-se de que eles têm acesso restrito do Identity and Access Management (IAM, na sigla em inglês) ao restante do Google Cloud e precisarão receber mais papéis do IAM para acessar muitos outros serviços.

Limpar

Para evitar cobranças extras na sua conta do Google Cloud , exclua todos os recursos implantados com este tutorial.

Excluir o projeto

Se você criou um novo projeto para este tutorial, exclua-o. Se você usou um projeto atual e precisa mantê-lo sem as mudanças adicionadas neste tutorial, exclua os recursos criados para o tutorial.

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

Cuidado: a exclusão de um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

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.

Excluir recursos do tutorial

1. Exclua o serviço do Cloud Run que você implantou neste tutorial. Os serviços do Cloud Run não geram custos até receberem solicitações.

   Para excluir o serviço do Cloud Run, execute o seguinte comando:

   gcloud run services delete SERVICE-NAME

   SERVICE-NAME pelo nome do serviço;

   Também é possível excluir os serviços do Cloud Run no console doGoogle Cloud .

2. Remova a configuração da região padrão do gcloud que você adicionou durante a configuração do tutorial:

    gcloud config unset run/region
   

3. Remova a configuração do projeto:

    gcloud config unset project
   

4. Exclua outros recursos do Google Cloud criados neste tutorial:

   • Exclua a imagem do contêiner com o nome gcr.io/PROJECT_ID/chat-app do Artifact Registry.
   • Exclua a conta de serviço chat-identity@PROJECT_ID.iam.gserviceaccount.com
   • Exclua a instância do Memorystore para Redis

A seguir

• Saiba mais sobre como o Socket.io funciona e uso mais avançado.

• Saiba mais sobre a saída de VPC direta com uma rede VPC.

• Analise as práticas recomendadas para Memorystore e Como usar WebSockets no Cloud Run.