dare-realtime
Comunicação real-time (WebSocket, SSE) em projetos DARE. Fornece schema validation de eventos, registro central de tipos, reconexão com exponential backoff, e gerenciamento de subscriptions com limpeza garantida (zero ghost listeners).
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- dare-realtime
- description
- Comunicação real-time (WebSocket, SSE) em projetos DARE. Fornece schema validation de eventos, registro central de tipos, reconexão com exponential backoff, e gerenciamento de subscriptions com limpeza garantida (zero ghost listeners).
03 SKILL.md 正文
DARE Realtime Skill
Você é um especialista em comunicação real-time. Seu papel é garantir que toda integração WebSocket/SSE em projeto DARE seja tipada, autorizada, reconectável e sem ghost listeners.
Quando usar esta skill
- Projeto precisa de WebSocket (chat, notifications, live updates)
- Projeto precisa de SSE (logs streaming, métricas em tempo real)
- Você está auditando ghost listeners (memória crescendo após desconexão)
- Você está revisando código que faz
socket.on('event', ...)sem cleanup
Arquitetura recomendada
┌─────────────────────────────────────────────────────────┐
│ Event Registry │
│ - Tipos de evento com schema JSON │
│ - Versionamento (v1, v2…) │
│ - Autorização por evento │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Subscription Manager │
│ - Map<connection_id, Set<event_type>> │
│ - Cleanup garantido on disconnect │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Reconnect Strategy │
│ - Exponential backoff (1s, 2s, 4s, 8s, max 30s) │
│ - Jitter para evitar thundering herd │
│ - Resync de estado após reconectar │
└─────────────────────────────────────────────────────────┘
Os 4 pilares
1. Schema validation de eventos
Todo evento WebSocket/SSE tem schema JSON:
// event_registry.ts
const events = {
'user.created.v1': z.object({
id: z.string().uuid(),
email: z.string().email(),
createdAt: z.string().datetime(),
}),
'message.sent.v1': z.object({
conversationId: z.string().uuid(),
senderId: z.string().uuid(),
body: z.string().max(2000),
sentAt: z.string().datetime(),
}),
};
Server valida antes de emitir, client valida antes de processar. Evento inválido = log + drop.
2. Registro central de tipos
Um único event_registry.ts/py/rs lista todos os event types. Adicionar evento novo passa por PR explícito. Versionamento via sufixo (.v1, .v2).
3. Reconexão com exponential backoff
class ReconnectStrategy {
private attempt = 0;
next(): number {
const base = Math.min(1000 * 2 ** this.attempt, 30_000);
const jitter = Math.random() * 1000;
this.attempt++;
return base + jitter;
}
reset() { this.attempt = 0; }
}
Após reconectar, resync de estado — buscar eventos perdidos via REST ou pedir snapshot via WS.
4. Subscription manager (zero ghost listeners)
Cada subscription rastreada em map, com cleanup automático:
class SubscriptionManager {
private subs = new Map<string, Set<string>>(); // connectionId → events
subscribe(connId: string, event: string) {
if (!this.subs.has(connId)) this.subs.set(connId, new Set());
this.subs.get(connId)!.add(event);
}
unsubscribeAll(connId: string) {
this.subs.delete(connId);
}
// Forçar limpeza on disconnect — SEMPRE
onDisconnect(connId: string) {
this.unsubscribeAll(connId);
}
}
Métricas obrigatórias
| ID | Métrica | Como medir |
|---|---|---|
| M-01 | 100% de event types com JSON Schema definido | grep no registry |
| M-02 | 100% de subscriptions autorizadas | verificar authorize() antes de subscribe() |
| M-03 | 0 ghost listeners após desconexão | métrica subs.size por conexão = 0 após disconnect |
| M-04 | Estratégia de reconexão configurada | grep por ReconnectStrategy ou similar |
Antipatterns
| AP | Antipattern | Sinal | Correção |
|---|---|---|---|
| AP-01 | Evento sem schema | socket.emit('foo', anything) |
Adicionar schema no registry |
| AP-02 | socket.on(...) sem cleanup |
listener fica vivo após disconnect | Usar SubscriptionManager |
| AP-03 | Reconexão sem backoff | reconecta imediatamente em loop | Exponential backoff + jitter |
| AP-04 | Sem autorização de subscription | usuário ouve eventos de outro tenant | authorize(user, event) antes de subscribe() |
| AP-05 | Broadcast sem filtro | io.emit() para todos |
Use rooms / channels por tenant |
| AP-06 | Estado não recuperado após reconectar | UI mostra dados stale | Resync via REST ou snapshot |
Como aplicar
Passo 1: Criar event registry
// src/realtime/event_registry.ts
export const EventRegistry = {
'user.created.v1': { schema: UserCreatedSchema, requires: 'admin' },
'message.sent.v1': { schema: MessageSentSchema, requires: 'participant' },
};
Passo 2: Implementar subscription manager
Use packages/skills/dare-realtime/subscription_manager.ts como template. Garante cleanup on disconnect.
Passo 3: Configurar reconexão no client
const strategy = new ReconnectStrategy({ base: 1000, max: 30_000 });
socket.on('disconnect', () => {
setTimeout(() => socket.connect(), strategy.next());
});
socket.on('connect', () => {
strategy.reset();
resyncState(); // fetch via REST eventos perdidos
});
Passo 4: Adicionar autorização
socket.on('subscribe', (eventType) => {
if (!authorize(socket.user, eventType)) {
socket.emit('error', { code: 'FORBIDDEN' });
return;
}
subscriptionManager.subscribe(socket.id, eventType);
});
Passo 5: Validar eventos no client e server
Server antes de emitir:
const schema = EventRegistry[eventType].schema;
const valid = schema.safeParse(payload);
if (!valid.success) { log.error(...); return; }
io.to(room).emit(eventType, valid.data);
Client antes de processar:
socket.on(eventType, (payload) => {
const valid = EventRegistry[eventType].schema.safeParse(payload);
if (!valid.success) { log.warn(...); return; }
handleEvent(valid.data);
});
Boas práticas
- WebSocket vs SSE — SSE para server→client unidirecional (logs, métricas). WS para bidirectional (chat).
- Rooms/channels por tenant — evita broadcast cross-tenant
- Heartbeat / ping-pong — detectar conexão zumbi (network OK mas peer não responde)
- Backpressure — se client lento, fila no server explode. Drop eventos antigos ou aplicar rate limit.
- Replay limitado — guardar últimos N eventos por room para reconexão recente, não histórico completo
Stack recomendada
| Stack | WebSocket | SSE |
|---|---|---|
| Node | socket.io, ws |
eventsource (client) + endpoint custom |
| Rails | Action Cable | Rack streaming |
| Rust/Axum | tokio-tungstenite, axum ws |
axum::sse::Sse |
| FastAPI | fastapi.WebSocket |
EventSourceResponse |
| Go | gorilla/websocket, melody |
stdlib http.Flusher |
Dicas
- Leia
docs/design/skills/dare-realtime/DESIGN.md - Combine com
dare-securitypara autorização - Use os templates em
packages/skills/dare-realtime/
Esta skill é parte do DARE Method e está sob licença MIT.
04 同仓库更多 Skills
commands
暂无简介
commands
暂无简介
skill-rails-api
Padrões DARE para APIs em Ruby on Rails 8 — API mode, ActiveRecord, Solid Queue, Solid Cable, Action Cable, strong parameters, services (interactors), serializers (Blueprinter/Alba), Devise/JWT, rack-attack, rswag/grape-swagger.
skill-nestjs-api
Padrões DARE para APIs REST em NestJS + TypeScript + Prisma + Swagger. Modules, Controllers, Services, DTOs com class-validator, Guards, Interceptors, exceções globais, Jest + Supertest, OpenAPI auto-gerado, rate limiting com @nestjs/throttler.
skill-mcp-server
Padrões DARE para servidores MCP (Model Context Protocol) em TypeScript ou Python. Define tools, resources, prompts; suporta transports stdio, SSE e HTTP; validação Zod/Pydantic; autorização por tool; tracing estruturado; testes; publicação no MCP registry.
skill-go-gin-api
Padrões DARE para APIs REST em Go + Gin (ou stdlib net/http) + sqlc + PostgreSQL. Handlers, services, repositories, middleware, validação com go-playground/validator, JWT, rate limit, swag (OpenAPI), testes com testify e httptest.