Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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.

ts
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 subscription

Tó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.

ts
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:

EstadoSignificado
connectingPrimera conexión en curso.
openConectado.
reconnectingSe cayó; intentando de nuevo con backoff exponencial y jitter (de 1 s a 30 s), sin límite.
closedSin suscriptores, después de dispose(), o el gateway rechazó los tópicos privados (abajo).
unavailableSin 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.

ts
// 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.

tsx
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)):

ts
// 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:

ts
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:

tsx
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 de onResync de arriba para TanStack Query: invalida la query del saldo con cada balance_update, las queries de notifications con cada notificación y las queries de wallet y notifications después de una reconexión. Los tópicos de producto (p. ej., predictionsTopics.orderbook) van en su opción topics, 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.