artubss/SKILLS-CLAUDE-CODE / favorites/tpl-dominio-realtime-websockets
tpl-dominio-realtime-websockets
VerifiedTemplate do pack (dominio/11-realtime-websockets.md). Orienta o agente em regras de negocio e requisitos de produto alinhado a esse contexto.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
SKILL.md
View on GitHub---
name: tpl-dominio-realtime-websockets
description: Template do pack (dominio/11-realtime-websockets.md). Orienta o agente em regras de negocio e requisitos de produto alinhado a esse contexto.
metadata:
version: 1.0.0
source_template: dominio/11-realtime-websockets.md
generated_by: install_pack_templates_as_claude_skills
---
# 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ério | SSE | WebSocket |
|---------|-----|-----------|
| Direção | Server → Client apenas | Bidirecional |
| Protocolo | HTTP/1.1 + HTTP/2 | WS (upgrade do HTTP) |
| Reconexão | Automática (browser) | Manual (library) |
| Proxy/Firewall | Melhor compatibilidade | Pode ser bloqueado |
| Complexidade | Baixa | Alta |
| Casos de uso | Feeds, notificações, dashboards | Chat, 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
```javascript
// 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
```javascript
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
| Trigger | Action |
|---------|--------|
| WS connect | Autenticar JWT → associar user ao socket → emitir confirmação |
| WS: join_room | Validar permissão → `socket.join(room)` → atualizar presence |
| WS: leave_room | `socket.leave(room)` → remover de presence |
| WS: message (chat) | Validar → persistir no DB → broadcast para room |
| WS: typing_start | Broadcast para room sem persistir (efêmero) |
| WS: disconnect | Limpar presence → notificar room se relevante |
| GET /sse/feed | Criar SSE stream → autenticar → subscrever canal Redis |
| GET /sse/jobs/:id | SSE para progresso de job → fechar ao completar |
| Redis event: new_message | Broadcast para room correspondente via Redis adapter |
| Redis event: job_progress | Emitir para SSE subscribers do job |
| Business logic: notify user | `io.to(userRoom).emit('notification', data)` |
| GET /rooms/:id/history | REST 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |