Guia de Migração: De socket.io-redis para @socket.io/redis-adapter

O Adaptador Redis para Socket.IO constitui um componente essencial para o desenvolvimento de aplicações em tempo real escaláveis. Este componente permite a transmissão de eventos entre múltiplas instâncias de servidores Socket.IO. O presente guia oferece instruções detalhadas para realizar a migração do pacote antigo socket.io-redis para o novo @socket.io/redis-adapter, garantindo uma transição tranquila e eficiente.

Motivos para Realizar a Migração

A evolução do ecossistema Socket.IO resultou no lançamento do pacote oficial @socket.io/redis-adapter, que substitui completamente a versão anterior. Esta nova versão traz melhorias significativas:

• Otimização de Desempenho: Redução de riscos de vazamentos de memória e melhoria na eficiência da transmissão de mensagens.
• Suporte a Recursos Avançados: Compatibilidade com o recurso Sharded Pub/Sub do Redis 7.0+.
• API Simplificada: Configuração mais intuitiva e opções reduzidas, facilitando o aprendizado.
• Manejo de Erros Aprimorado: Mecanismos mais robustos para tratamento de exceções, aumentando a estabilidade do sistema.

Preparação para a Migração

Antes de iniciar o processo, analise a arquitetura atual do seu sistema. O adaptardor Redis funciona como um barramento de mensagens, conectando diversas instâncias do servidor Socket.IO. Cada instância mantém suas próprias conexões de cliente, mas através do adaptardor, é possível compartilhar informações de salas e transmitir mensagens entre elas.

Verificação da Versão Atual

Confirme qual versão do socket.io-redis está instalada no seu projeto:

npm list socket.io-redis

Backup das Configurações

Realize o backup das configurações atuais do adaptardor, incluindo:

• Parâmetros de conexão com o Redis
• Opções de configuração do adaptardor
• Configurações personalizadas de serialização

Procedimento de Migração

Etapa 1: Atualização das Dependências

Modifique o arquivo package.json para incluir a nova dependência:

// Estrutura antiga
"dependencies": {
  "socket.io-redis": "^6.0.0"
}

// Nova estrutura
"dependencies": {
  "@socket.io/redis-adapter": "^8.0.0"
}

Em seguida, execute os comandos de instalação:

npm uninstall socket.io-redis
npm install @socket.io/redis-adapter

Etapa 2: Atualização das Declarações de Importação

Ajuste as instruções de importação no código fonte:

// Forma antiga
const redisAdapter = require('socket.io-redis');
const adapter = redisAdapter({ host: 'localhost', port: 6379 });

// Nova forma
const { createAdapter } = require('@socket.io/redis-adapter');
const { createClient } = require('redis');

Etapa 3: Reestruturação da Lógica de Criação do Adaptador

A nova versão apresenta uma arquitetura分开 de clientes:

// Configuração antiga
const io = require('socket.io')(server);
io.adapter(redisAdapter({ host: 'localhost', port: 6379 }));

// Nova configuração
const pubClient = createClient({ url: 'redis://localhost:6379' });
const subClient = pubClient.duplicate();

await Promise.all([
  pubClient.connect(),
  subClient.connect()
]);

const io = new Server({
  adapter: createAdapter(pubClient, subClient)
});

Etapa 4: Ajuste de Opções de Configuração

Algunas opções foram renomeadas ou substituídas:

Opção Antiga	Nova Opção	Descrição
key	channelPrefix	Prefixo dos canais Redis Pub/Sub
requestsTimeout	requestsTimeout	Tempo limite para requisições (mantido)
—	publishOnSpecificResponseChannel	Novo: Publicação em canal de resposta específico

Novos Recursos

Suporte a Sharded Pub/Sub

O Redis 7.0 introduziu o recurso Sharded Pub/Sub, agora suportado completamente pelo novo adaptardor:

const { createShardedAdapter } = require('@socket.io/redis-adapter');

const io = new Server({
  adapter: createShardedAdapter(pubClient, subClient)
});

Serializador Personalizado

A nova versão permite a utilização de serializadores personalizados. O serializador padrão está disponível em lib/util.ts e pode ser estendido conforme necessário.

Tratamento de Erros

O novo adaptardor implementa um tratamento de erros mais seguro, eliminando a emissão direta de eventos de "error" que podiam causar exceções não capturadas.

Considerações de Compatibilidade

Tabela de Versões

Versão do Adaptador	Versão do Socket.IO
4.x	1.x
5.x	2.x
6.0.x	3.x
6.1.x	4.x
7.x ou superior	4.3.1 ou superior

Alterações Incompatíveis

1. Métodos Removidos: APIs marcadas como depreciadas foram removidas.
2. Tratamento de Erros: Alteração na forma de tratamento de exceções.
3. Simplificação de Configurações: Algumas opções foram renomeadas ou eliminadas.

Validação da Migração

Execução de Testes

O projeto inclui um conjunto completo de testes:

npm test

Os testes estão localizados no diretório test/:

• test/index.ts — Casos de teste principais
• test/specifics.ts — Testes de funcionalidades específicas
• test/custom-parser.ts — Testes de serializadores personalizados

Verificação de Funcionalidades

Após a migração, confirme o funcionamento de:

• Transmissão de mensagens entre múltiplos servidores
• Funcionalidade de salas
• Gerenciamento de conexões e desconexões de clientes
• Mecanismos de tratamanto de erros

Otimizações de Desempenho

Utilização de Connection Pool

Para cenários de alta concorrência, configure um pool de conexões Redis:

const pubClient = createClient({
  url: 'redis://localhost:6379',
  socket: {
    keepAlive: 5000
  }
});

Monitoramento de Desempenho

O adaptardor oferece funcionalidades de depuração:

const debug = require('debug')('socket.io-redis-adapter');

Perguntas Frequentes

Problemas de Conexão Após Migração

Caso encontre problemas de conexão, verifique a configuração do Redis, garantindo que ambos os clientes (pubClient e subClient) possam estabelecer conexão corretamente. Examine a lógica de tratamento de conexões em lib/sharded-adapter.ts.

Reversão para Versão Anterior

Se necessário, é possível reverter temporariamente:

npm uninstall @socket.io/redis-adapter
npm install socket.io-redis@6.1.0

Melhorias no Uso de Memória

A nova versão corrige diversos problemas de vazamentos de memória, especialmente no modo Sharded Pub/Sub, onde o gerenciamento otimizado de assinaturas reduz o consumo de memória.