Tempo real (SSE)

A API empurra mudanças de estado por Server-Sent Events, não por WebSocket: SSE reconecta sozinho e roda em HTTP puro (AD-010). Atrás dele há Redis Streams, e a tabela events é a fonte da verdade (veja Webhooks e eventos).

Os dois streamsCopy Anchor Link

O stream da pessoa existe à parte porque o da conta é assunto dos responsáveis: nada dele é da pessoa (publish-pairing-event.ts).

O pairing de cada frame do stream da pessoa é este tipo (backend/src/domains/channels/dtos/public-pairing.dto.ts), sem nada sobre os responsáveis:

O ticketCopy Anchor Link

EventSource não manda header, então o Bearer não serve. O fluxo é:

1. POST /accounts/{uid}/events/ticket, com Bearer e sendo membro da conta. Responde 201 com { ticket, url }.
2. Abra o EventSource em url (que já leva ?ticket=) em até 60 segundos.

O ticket é um JWT HS256 com typ: "sse", sub (uid do usuário) e acc (uid da conta). Um access token comum não serve como ticket, e um ticket de outra conta recebe 401. Na conexão, o servidor confere de novo se o usuário ainda é membro vivo; se não for, 404. Gere um ticket por conexão: ao reconectar depois de um erro, peça outro.

Frames, retomada e heartbeatCopy Anchor Link

id: 1760884500000-0
event: event
data: {"id":"01J…","type":"pairing.paired","occurredAt":"…","seatUid":"…","payload":{…}}

event: ping
data:

• id é a posição no Redis Stream (<ms>-<seq>). Pra retomar sem buraco, mande o último id como header Last-Event-ID (o navegador faz isso sozinho ao reconectar o mesmo EventSource) ou como ?since=.
• Quando nada chega em 5 s, sai um event: ping. Isso fica bem abaixo do idleTimeout de 10 s do Bun e dos limites comuns de proxy. A AD-010 fala em 15 s, mas o código usa 5 s.
• Os frames de dados usam event: event. Escute por addEventListener("event", …), não por onmessage.

async function listen(accountUid: string, token: string, since?: string) {
  const res = await fetch(`${API}/accounts/${accountUid}/events/ticket`, {
    method: "POST",
    headers: { authorization: `Bearer ${token}` },
  }).then((r) => r.json());
  const url = new URL(res.data.url, API);
  if (since) url.searchParams.set("since", since);
  const source = new EventSource(url);
  source.addEventListener("event", (e) => {
    const event = JSON.parse(e.data); // EventDto
    lastId = e.lastEventId;
    if (event.type.startsWith("seat.")) refetchSeat(event.seatUid);
  });
  source.onerror = () => {
    source.close();
    setTimeout(() => listen(accountUid, token, lastId), 2000); // ticket novo
  };
}

Catálogo de eventos (stream da conta)Copy Anchor Link

Os eventos de alerta nunca carregam trecho, contraparte nem justificativa (regra P1). No stream da pessoa, os tipos são pairing.started, pairing.challenge, pairing.status, pairing.paired e pairing.ended.

FontesCopy Anchor Link

• backend/src/http/routes/events/stream.route.ts, backend/src/http/routes/events/ticket.route.ts
• backend/src/http/routes/consents/pairing.route.ts (DependentEventStreamRoute)
• backend/src/domains/events/use-cases/publish-event.ts, sse-ticket.ts, entities/event.entity.ts
• backend/src/domains/channels/use-cases/publish-pairing-event.ts, apply-provider-state.ts
• backend/src/domains/consents/use-cases/publish-consent-event.ts, backend/src/domains/ingest/use-cases/publish-queue-event.ts
• backend/src/domains/subscriptions/use-cases/monitoring.ts, backend/src/domains/alerts/use-cases/open-or-attach.ts, backend/src/domains/notifications/use-cases/dispatch.ts
• backend/src/domains/protection/use-cases/state-watch.ts
• backend/src/infra/streams.ts, backend/src/infra/redis.ts
• .specs/features/redesign/api-map.md (§0.4), api-gaps.md (G-11)
• AD-010