Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-dominio-realtime-websockets

tpl-dominio-realtime-websockets

Verified

Template do pack (dominio/11-realtime-websockets.md). Orienta o agente em regras de negocio e requisitos de produto alinhado a esse contexto.

DOMAIN: Real-time (WebSockets + Socket.io / SSE)

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: dominio/11-realtime-websockets.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

CONTEXT

Real-time parece simples com Socket.io Hello World — e quebra em produção quando você tem múltiplos servidores, reconexões do cliente causam mensagens duplicadas, e backpressure de volume alto de mensagens derruba o servidor. A decisão entre WebSockets e SSE muda a arquitetura inteira — escolher errado custa caro de corrigir.

STACK ASSUMPTIONS

  • WebSockets: Socket.io 4.x (com Redis adapter para escala) ou WS nativo
  • SSE: EventSource API (nativo nos browsers)
  • Pub/Sub: Redis (ou NATS para throughput muito alto)
  • Auth: JWT validado no handshake (não em cada mensagem)
  • Backend: Node.js (event loop eficiente) ou Go (goroutines)

CORE CONCEPTS

  • Room: agrupamento de conexões WebSocket que recebem as mesmas mensagens
  • Namespace: partição lógica do servidor Socket.io (evita poluição de eventos)
  • Presence: rastrear quais usuários estão online (com Redis HSET por room)
  • Reconnection: cliente reconecta automaticamente — servidor deve suportar isso elegantemente
  • Backpressure: fila de mensagens maior que o cliente consegue consumir
  • Redis Adapter: sincronizar rooms e eventos entre múltiplas instâncias Node.js
  • SSE: server-sent events — unidirecional (server→client), HTTP, sem handshake extra
  • Message Ordering: TCP garante ordem por conexão, não entre reconexões

ARCHITECTURE RULES

SSE vs WebSockets Decision

CritérioSSEWebSocket
DireçãoServer → Client apenasBidirecional
ProtocoloHTTP/1.1 + HTTP/2WS (upgrade do HTTP)
ReconexãoAutomática (browser)Manual (library)
Proxy/FirewallMelhor compatibilidadePode ser bloqueado
ComplexidadeBaixaAlta
Casos de usoFeeds, notificações, dashboardsChat, games, colaboração

Use SSE para: dashboards em tempo real, feeds de atividade, progresso de jobs Use WebSocket para: chat, colaboração em tempo real, jogos, presença

Authentication for WS

// Socket.io: autenticar no handshake, não em cada evento
io.use(async (socket, next) => {
  const token = socket.handshake.auth.token;
  try {
    const user = await verifyJWT(token);
    socket.user = user; // disponível em todos os handlers
    next();
  } catch (err) {
    next(new Error('Authentication error'));
  }
});

Room Management

  • Naming convention: {resource_type}:{resource_id} → post:123, org:456
  • Join/Leave rooms: sempre validar que usuário tem permissão para o resource
  • Cleanup: ao desconectar, remover de todas as rooms (Socket.io faz automaticamente)
  • Rooms efêmeras: criadas sob demanda, sem persistência no banco

Presence Tracking

HSET presence:room:123 { userId: connectionId, joinedAt: timestamp }
EXPIRE presence:room:123 300  // TTL de segurança

On connect: HSET presence:room:123 userId {connectionId, online: true}
On disconnect: HDEL presence:room:123 userId (se não há outra conexão do mesmo user)

Reconnection Handling

  • Stateless: mensagens perdidas durante desconexão recuperadas via REST API no reconnect
  • Stateful (cursor): cliente envia lastEventId → servidor reenvia mensagens após cursor
  • Não tentar reconstruir estado completo via WebSocket na reconexão

Scaling com Redis Adapter

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

const pubClient = createClient({ url: process.env.REDIS_URL });
const subClient = pubClient.duplicate();
io.adapter(createAdapter(pubClient, subClient));
// Agora eventos emitidos em qualquer instância chegam a todos os clients

ROUTING TABLE

TriggerAction
WS connectAutenticar JWT → associar user ao socket → emitir confirmação
WS: join_roomValidar permissão → socket.join(room) → atualizar presence
WS: leave_roomsocket.leave(room) → remover de presence
WS: message (chat)Validar → persistir no DB → broadcast para room
WS: typing_startBroadcast para room sem persistir (efêmero)
WS: disconnectLimpar presence → notificar room se relevante
GET /sse/feedCriar SSE stream → autenticar → subscrever canal Redis
GET /sse/jobs/:idSSE para progresso de job → fechar ao completar
Redis event: new_messageBroadcast para room correspondente via Redis adapter
Redis event: job_progressEmitir para SSE subscribers do job
Business logic: notify userio.to(userRoom).emit('notification', data)
GET /rooms/:id/historyREST endpoint para mensagens antes do cursor (reconexão)

CRITICAL RULES

  1. Autenticação SEMPRE no handshake WS, nunca em cada mensagem individual
  2. Validar autorização ao entrar em qualquer room (não só ao conectar)
  3. Redis adapter obrigatório se deploy em mais de uma instância
  4. Nunca processar lógica pesada no event handler principal (bloqueia event loop Node.js)
  5. Mensagens efêmeras (typing, cursor) nunca persistidas no banco
  6. Reconexão do cliente não assume estado anterior — buscar via REST para reconstituir
  7. Backpressure: limitar buffer por connection, fechar conexão se constantemente lento
  8. SSE: incluir event:, id: e retry: nos eventos (permite cursor de reconexão)
  9. WS connections têm timeout de inatividade (heartbeat/ping-pong)
  10. Nunca emitir para broadcast.emit() global — sempre para rooms específicas

COMMON PITFALLS

❌ Presença sem TTL → ghost users

// ERRADO: se servidor reiniciar sem disconnect event, usuário fica "online" para sempre
await redis.hset(`presence:room:${roomId}`, userId, JSON.stringify({ online: true }));

// CORRETO: TTL + heartbeat para renovar
await redis.hset(`presence:${roomId}`, userId, Date.now());
await redis.expire(`presence:${roomId}`, 60); // 60s TTL
// Client emite heartbeat a cada 30s, renova TTL

❌ Lógica pesada no event handler

// ERRADO: query ao banco dentro do handler bloqueia outras connexões (Node.js single thread)
socket.on('get_history', async () => {
  const messages = await db.messages.findMany({ ... }); // demorado
  socket.emit('history', messages);
});

// CORRETO: offload para worker thread ou já ter dados cacheados
socket.on('get_history', async () => {
  const messages = await cache.get(`history:${roomId}`)
    ?? await db.messages.findMany({ ... }); // executado mas libera event loop via async
  socket.emit('history', messages);
});

❌ Escalar sem Redis adapter

// ERRADO: com 3 instâncias, socket em instância #1 não recebe evento emitido em #2
io.to(roomId).emit('message', data); // só chega a connections na mesma instância

// CORRETO: Redis adapter sincroniza entre todas as instâncias
io.adapter(createAdapter(pubClient, subClient));
io.to(roomId).emit('message', data); // chega a TODOS os clients do room, qualquer instância

QUALITY GATES

  • Autenticação no handshake com rejeição clara de token inválido
  • Redis adapter configurado antes de deploy multi-instância
  • Rooms com validação de autorização no join
  • Presence com TTL e heartbeat (sem ghost users)
  • Mensagens efêmeras nunca persistidas
  • Reconexão busca histórico via REST (não assume estado anterior)
  • Heartbeat/ping-pong para detectar conexões mortas
  • Backpressure handling (buffer limit por conexão)
  • SSE com id: em cada evento (permite Last-Event-ID no reconnect)
  • Zero broadcast global .emit() sem filtragem por room

FORBIDDEN

  • Autenticação por evento individual (degradação de performance)
  • Deploy multi-instância sem Redis adapter (split-brain de rooms)
  • Lógica síncrona pesada dentro de event handlers WebSocket
  • Presença em Redis sem TTL ou heartbeat
  • socket.broadcast.emit() global em produção sem filtro de room
  • Assumir estado consistente após reconexão sem sincronização
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall