Realtime
O realtime entrega ao app o que o gateway publica por WebSocket: saldo, notificações e, nos pacotes de produto, mercados e ordens. Fica num entry separado, @getenginex/sdk/realtime, para que quem não usa WebSocket não pague os bytes dele.
import { createRealtime, coreTopics } from '@getenginex/sdk/realtime'
const realtime = createRealtime(enginex) // always the same instance for the same client
const off = realtime.subscribe(coreTopics.balance(), (update, meta) => {
console.log(update.available, meta.kind) // 'event' (or 'snapshot'/'delta' in sequenced mode)
})
realtime.onResync(coreTopics.balance(), () => reloadBalance()) // reload the baseline over HTTP
realtime.onStatus((status) => showBanner(status))
off() // cancels only this subscriptionTópicos
Um tópico é um descritor tipado, criado por uma fábrica: coreTopics.balance() e coreTopics.notification() no core; predictionsTopics no @getenginex/sdk-predictions. A mensagem chega validada e em camelCase, no modo de validação do client (strict descarta uma mensagem fora do schema; warn a entrega recuperada campo a campo e avisa por onValidationIssue; veja Validação de respostas). Um erro lançado no handler não afeta o SDK.
Conexão preguiçosa
Nada conecta ao criar o realtime. A conexão abre no primeiro subscribe, é uma só para todos os tópicos do client e fecha cerca de 1 s depois do último off(). O client.dispose() fecha a conexão e, depois dele, subscribe lança CONFIGURATION_ERROR.
A URL vem da opção wsUrl do client; sem ela, do baseUrl (http→ws, https→wss, mais /ws) e, sem baseUrl, da origem da página. O SDK acrescenta o access token em ?token= (renovado antes de conectar se estiver expirado); o token nunca aparece em hooks, avisos ou erros.
createEnginexClient({ baseUrl: 'https://api.operador.com', wsUrl: 'wss://ws.operador.com/ws' })Status
realtime.status() e realtime.onStatus(listener) informam o estado da conexão:
| Status | Significado |
|---|---|
connecting | Primeira conexão em andamento. |
open | Conectado. |
reconnecting | Caiu; tentando de novo com backoff exponencial e jitter (1 s até 30 s), sem limite. |
closed | Sem inscritos, depois de dispose(), ou o gateway recusou os tópicos privados (abaixo). |
unavailable | Sem WebSocket disponível ou sem URL: subscribe vira um no-op e nunca lança por isso. |
closed por recusa vale para todos os tópicos
Depois de um unauthorized repetido num tópico privado (veja Tópicos privados), a conexão é fechada para todos os tópicos, inclusive os públicos (market, orderbook...): nenhum handler recebe mais nada até a sessão ganhar um access token novo (novo login ou um refresh) ou o usuário mudar. O hooks.onError recebe UNAUTHENTICATED: é a hora de pedir login de novo.
Reconexão e onResync
Depois de uma queda, o SDK reconecta, reinscreve todos os tópicos e dispara o onResync uma vez por tópico ativo. O gateway não reenvia o que se perdeu durante a queda: use o onResync para recarregar a base por HTTP (ex.: wallet.getBalance()) e só então continuar aplicando as mensagens. O Saldo ao vivo mostra o padrão completo.
// one topic: pass the same descriptor as subscribe (on a private one, it applies to the session's user)
const off = realtime.onResync(coreTopics.balance(), () => reloadBalance())
// all topics: the listener receives the full topic, e.g. 'market:m-1'
realtime.onResync((topic) => console.log('reload', topic))Trate o descritor (Topic) como opaco: crie-o com a fábrica (coreTopics.balance(), predictionsTopics.orderbook({ marketId })) e passe-o ao subscribe/onResync, sem ler os campos dele.
Também dispara o onResync o modo sequenciado (abaixo) quando um snapshot pedido não chega em 10 s. Uma conexão sem resposta a um ping (a cada 30 s, com 10 s de tolerância) é dada como morta e reconectada.
Se o gateway responder com erro a um subscribe por outro motivo (ex.: rate_limited, limite de mensagens), o hooks.onError recebe o erro (RESOURCE_EXHAUSTED no rate_limited) e o SDK reenvia esse subscribe sozinho, na mesma conexão, com o mesmo backoff (1 s, 2 s, 4 s... por tópico).
Tópicos privados
balance e notification são do próprio usuário: o descritor não recebe id e o realtime usa o sub da sessão (balance:<sub>). Sem sessão, subscribe lança UNAUTHENTICATED. Quando o usuário da sessão muda (logout, login de outra conta), o realtime reconecta com o token novo e descarta as inscrições privadas do usuário anterior: o handler dele nunca recebe mensagem do próximo. Reaja à troca com enginex.session.subscribe e assine de novo. Um refresh de token não reconecta.
O gateway valida o token só ao abrir a conexão e rebaixa um token inválido a anônimo em silêncio. Se responder unauthorized num tópico privado com sessão ativa, o SDK renova o token e tenta uma vez mais; se repetir, o status vira closed (para todos os tópicos, inclusive os públicos) e o hooks.onError recebe UNAUTHENTICATED. Nunca há loop de reconexão. Se a própria renovação falhar (rede, gateway fora), a tentativa extra não é gasta: o SDK tenta de novo com o backoff crescendo até 30 s, e volta ao normal quando um tópico privado é aceito.
Modo multi-tenant sem sequência
Em produção o gateway roda multi-tenant: mensagens simples (meta.kind === 'event'), sem número de sequência e sem snapshot. Uma mensagem perdida não é detectável; por isso a base sempre se recarrega por HTTP no onResync e ao assinar. Em ambientes single-tenant (WS_SEQUENCED), chegam snapshot, delta e heartbeat com seq: o SDK detecta gap (seq maior que o último + 1), pede snapshot_request, descarta os deltas até o snapshot e descarta duplicatas. Se o snapshot não chegar em 10 s, o onResync dispara e o próximo delta passa a ser a nova base da sequência. O handler recebe o mesmo formato nos dois modos, com meta.kind e meta.seq.
O snapshot de balance não é entregue
No modo sequenciado o snapshot de balance: é o protobuf cru de GetBalance, de outro formato que o balance_update. coreTopics.balance() ignora esse snapshot (sem aviso de validação e sem chegar ao handler); os delta seguem normalmente. Carregue o saldo inicial com wallet.getBalance().
Sem WebSocket disponível
O realtime usa globalThis.WebSocket ou a opção webSocket do client. O Node 22+ tem WebSocket global, então num servidor Node moderno o realtime não fica unavailable. Sem nenhum WebSocket (runtimes antigos, ou nada passado em webSocket), o status é unavailable e subscribe devolve um no-op. Mesmo assim, crie o realtime e assine só no browser (ex.: dentro de um useEffect): uma conexão aberta durante a renderização no servidor não faz sentido, e o off() precisa rodar na desmontagem.
useEffect(() => {
const realtime = createRealtime(enginex)
const off = realtime.subscribe(coreTopics.balance(), (update) => setBalance(update.available))
return off
}, [])Fora do browser: o Origin
O gateway resolve o tenant da conexão pelo header Origin, que o browser envia sozinho e um cliente Node não. Por isso, num servidor ou script, nem o WebSocket global do Node nem o pacote ws funcionam passados direto: a conexão é recusada antes de abrir e o status fica em reconnecting. Passe em webSocket um construtor que acrescente o Origin do site do operador (o realtime chama só new webSocket(url)):
// Node 22+: the global WebSocket (undici) accepts `{ headers }` as the second argument.
type NodeWebSocket = new (url: string, init: { headers: Record<string, string> }) => WebSocket
class OriginWebSocket extends (globalThis.WebSocket as unknown as NodeWebSocket) {
constructor(url: string) {
super(url, { headers: { Origin: 'https://casino.operador.com' } })
}
}
createEnginexClient({ baseUrl, webSocket: OriginWebSocket })Com o pacote ws (ou outra implementação), o padrão é o mesmo:
import WebSocket from 'ws'
class OriginWebSocket extends WebSocket {
constructor(url: string) {
super(url, { origin: 'https://casino.operador.com' })
}
}
createEnginexClient({ baseUrl, webSocket: OriginWebSocket })No React e no Vue
Os adapters envolvem esta API em hooks (@getenginex/sdk-react, reexportados também por @getenginex/sdk-next) e composables (@getenginex/sdk-vue) com os mesmos nomes:
import { coreTopics } from '@getenginex/sdk/realtime'
import { useRealtime, useRealtimeStatus, useRealtimeSync } from '@getenginex/sdk-react'
export function RealtimeBridge() {
useRealtimeSync() // balance and notifications kept fresh in the TanStack cache, resync included
const status = useRealtimeStatus()
useRealtime(coreTopics.notification(), (notification) => toast(notification.title))
return status === 'reconnecting' ? <Banner>Reconnecting...</Banner> : null
}useRealtime(topic, handler)assina enquanto o componente está montado e cancela ao desmontar; um tópico privado espera um usuário na sessão e reassina na troca de usuário.useRealtimeStatus()devolve o status da conexão, sem abri-la.useRealtimeSync()é a versão pronta do padrão deonResyncacima para o TanStack Query: invalida a query de saldo a cadabalance_update, as queries denotificationsa cada notificação e as queries dewalletenotificationsdepois de uma reconexão. Tópicos de produto (ex.:predictionsTopics.orderbook) entram na opçãotopics, com as chaves que cada um alimenta.
Detalhes e a forma em Vue em React e Vue.
Testes
createMockRealtime() de @getenginex/sdk/testing traz um WebSocket falso, com controles para enviar mensagens, derrubar a conexão e simular tópicos recusados. Veja Testes.