Realtime
El realtime entrega a la app lo que el gateway publica por WebSocket: saldo, notificaciones y, en los paquetes de producto, mercados y órdenes. Está en un entry separado, @getenginex/sdk/realtime, para que quien no usa WebSocket no pague sus bytes.
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
Un tópico es un descriptor tipado, creado por una fábrica: coreTopics.balance() y coreTopics.notification() en el core; predictionsTopics en @getenginex/sdk-predictions. El mensaje llega validado y en camelCase, en el modo de validación del cliente (strict descarta un mensaje fuera del schema; warn lo entrega recuperado campo por campo y avisa por onValidationIssue; consulta Validación de respuestas). Un error lanzado en el handler no afecta al SDK.
Conexión perezosa
Nada se conecta al crear el realtime. La conexión se abre en el primer subscribe, es una sola para todos los tópicos del cliente y se cierra cerca de 1 s después del último off(). client.dispose() cierra la conexión y, después de él, subscribe lanza CONFIGURATION_ERROR.
La URL viene de la opción wsUrl del cliente; sin ella, de baseUrl (http→ws, https→wss, más /ws) y, sin baseUrl, del origen de la página. El SDK agrega el access token en ?token= (renovado antes de conectar si está expirado); el token nunca aparece en hooks, avisos ni errores.
createEnginexClient({ baseUrl: 'https://api.operador.com', wsUrl: 'wss://ws.operador.com/ws' })Estado
realtime.status() y realtime.onStatus(listener) informan el estado de la conexión:
| Estado | Significado |
|---|---|
connecting | Primera conexión en curso. |
open | Conectado. |
reconnecting | Se cayó; intentando de nuevo con backoff exponencial y jitter (de 1 s a 30 s), sin límite. |
closed | Sin suscriptores, después de dispose(), o el gateway rechazó los tópicos privados (abajo). |
unavailable | Sin WebSocket disponible o sin URL: subscribe se vuelve un no-op y nunca lanza por eso. |
closed por rechazo aplica a todos los tópicos
Después de un unauthorized repetido en un tópico privado (consulta Tópicos privados), la conexión se cierra para todos los tópicos, incluidos los públicos (market, orderbook...): ningún handler recibe nada más hasta que la sesión obtenga un access token nuevo (un nuevo inicio de sesión o un refresh) o el usuario cambie. hooks.onError recibe UNAUTHENTICATED: es el momento de pedir iniciar sesión de nuevo.
Reconexión y onResync
Después de una caída, el SDK reconecta, reinscribe todos los tópicos y dispara onResync una vez por tópico activo. El gateway no reenvía lo que se perdió durante la caída: usa onResync para recargar la base por HTTP (p. ej., wallet.getBalance()) y solo entonces seguir aplicando los mensajes. Saldo en vivo muestra el patrón 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))Trata el descriptor (Topic) como opaco: créalo con la fábrica (coreTopics.balance(), predictionsTopics.orderbook({ marketId })) y pásalo a subscribe/onResync, sin leer sus campos.
onResync también se dispara en el modo secuenciado (abajo) cuando un snapshot solicitado no llega en 10 s. Una conexión sin respuesta a un ping (cada 30 s, con 10 s de tolerancia) se da por muerta y se reconecta.
Si el gateway responde con error a un subscribe por otro motivo (p. ej., rate_limited, límite de mensajes), hooks.onError recibe el error (RESOURCE_EXHAUSTED en rate_limited) y el SDK reenvía ese subscribe por sí solo, en la misma conexión, con el mismo backoff (1 s, 2 s, 4 s... por tópico).
Tópicos privados
balance y notification son del propio usuario: el descriptor no recibe id y el realtime usa el sub de la sesión (balance:<sub>). Sin sesión, subscribe lanza UNAUTHENTICATED. Cuando el usuario de la sesión cambia (cierre de sesión, inicio de sesión con otra cuenta), el realtime reconecta con el token nuevo y descarta las suscripciones privadas del usuario anterior: su handler nunca recibe mensajes del siguiente. Reacciona al cambio con enginex.session.subscribe y suscríbete de nuevo. Un refresh de token no reconecta.
El gateway valida el token solo al abrir la conexión y degrada un token inválido a anónimo en silencio. Si responde unauthorized en un tópico privado con sesión activa, el SDK renueva el token e intenta una vez más; si se repite, el estado pasa a closed (para todos los tópicos, incluidos los públicos) y hooks.onError recibe UNAUTHENTICATED. Nunca hay un bucle de reconexión. Si la propia renovación falla (red, gateway caído), el intento extra no se gasta: el SDK intenta de nuevo con el backoff creciendo hasta 30 s, y vuelve a la normalidad cuando se acepta un tópico privado.
Modo multi-tenant sin secuencia
En producción el gateway corre multi-tenant: mensajes simples (meta.kind === 'event'), sin número de secuencia y sin snapshot. Un mensaje perdido no es detectable; por eso la base siempre se recarga por HTTP en onResync y al suscribirse. En entornos single-tenant (WS_SEQUENCED), llegan snapshot, delta y heartbeat con seq: el SDK detecta el salto (seq mayor que el último + 1), pide snapshot_request, descarta los deltas hasta el snapshot y descarta duplicados. Si el snapshot no llega en 10 s, onResync se dispara y el siguiente delta pasa a ser la nueva base de la secuencia. El handler recibe el mismo formato en los dos modos, con meta.kind y meta.seq.
El snapshot de balance no se entrega
En el modo secuenciado el snapshot de balance: es el protobuf crudo de GetBalance, de un formato distinto al de balance_update. coreTopics.balance() ignora ese snapshot (sin aviso de validación y sin llegar al handler); los delta siguen normalmente. Carga el saldo inicial con wallet.getBalance().
Sin WebSocket disponible
El realtime usa globalThis.WebSocket o la opción webSocket del cliente. Node 22+ tiene WebSocket global, así que en un servidor Node moderno el realtime no queda unavailable. Sin ningún WebSocket (runtimes antiguos, o nada pasado en webSocket), el estado es unavailable y subscribe devuelve un no-op. Aun así, crea el realtime y suscríbete solo en el browser (p. ej., dentro de un useEffect): una conexión abierta durante el renderizado en el servidor no tiene sentido, y off() necesita ejecutarse al desmontar.
useEffect(() => {
const realtime = createRealtime(enginex)
const off = realtime.subscribe(coreTopics.balance(), (update) => setBalance(update.available))
return off
}, [])Fuera del browser: el Origin
El gateway resuelve el tenant de la conexión por el header Origin, que el browser envía por sí solo y un cliente Node no. Por eso, en un servidor o script, ni el WebSocket global de Node ni el paquete ws funcionan pasados directamente: la conexión se rechaza antes de abrir y el estado queda en reconnecting. Pasa en webSocket un constructor que agregue el Origin del sitio del operador (el realtime solo llama a 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 })Con el paquete ws (u otra implementación), el patrón es el mismo:
import WebSocket from 'ws'
class OriginWebSocket extends WebSocket {
constructor(url: string) {
super(url, { origin: 'https://casino.operador.com' })
}
}
createEnginexClient({ baseUrl, webSocket: OriginWebSocket })En React y Vue
Los adapters envuelven esta API en hooks (@getenginex/sdk-react, reexportados también por @getenginex/sdk-next) y composables (@getenginex/sdk-vue) con los mismos nombres:
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)se suscribe mientras el componente está montado y cancela la suscripción al desmontarse; un tópico privado espera a que haya un usuario en la sesión y se vuelve a suscribir al cambiar de usuario.useRealtimeStatus()devuelve el estado de la conexión, sin abrirla.useRealtimeSync()es la versión lista del patrón deonResyncde arriba para TanStack Query: invalida la query del saldo con cadabalance_update, las queries denotificationscon cada notificación y las queries dewalletynotificationsdespués de una reconexión. Los tópicos de producto (p. ej.,predictionsTopics.orderbook) van en su opcióntopics, con las claves que alimenta cada uno.
Detalles y la forma en Vue en React y Vue.
Pruebas
createMockRealtime() de @getenginex/sdk/testing trae un WebSocket falso, con controles para enviar mensajes, tumbar la conexión y simular tópicos rechazados. Consulta Pruebas.