Conceptos básicos

La API WebSocket de finlight.me proporciona un flujo continuo en tiempo real de artículos de noticias financieras, entregados en el momento en que están disponibles. A diferencia de los endpoints REST tradicionales, que requieren sondeos periódicos, el enfoque WebSocket te permite mantener una conexión persistente y recibir actualizaciones sin hacer solicitudes repetidas. Esto se traduce en una entrega de datos más rápida, un uso eficiente de los recursos y una mejor experiencia de usuario.

En esta guía aprenderás los pasos fundamentales para conectarte, autenticarte y mantener viva la conexión con la API WebSocket de finlight.me.

Nota: Para usar las funciones de WebSocket, necesitas una suscripción de pago. El plan gratuito no incluye la función WebSocket. Necesitas al menos una suscripción con funciones de WebSocket.

Conectarse al WebSocket

Para empezar a recibir actualizaciones de noticias financieras en tiempo real, debes establecer una conexión WebSocket con el servidor de finlight.me. Esta conexión permanece abierta hasta que tú o el servidor la cierren. En cuanto se establece la conexión, puedes empezar a suscribirte a flujos de artículos y recibir mensajes a medida que se publican nuevos artículos.

NOTA: La API WebSocket se desconecta técnicamente después de 2 horas. Sin embargo, nuestra biblioteca cliente de TypeScript o Python gestiona esto automáticamente reconectándose por ti. También puedes reconectarte manualmente si lo necesitas.

Endpoint de WebSocket:
wss://wss.finlight.me

Puntos clave:

Datos en tiempo real: El protocolo WebSocket habilita una conexión full-duplex, lo que significa que los datos pueden fluir hacia y desde el servidor en tiempo real.
Modelo de publicación/suscripción: Una vez conectado, puedes especificar tu consulta (p. ej., query: "nvidia") y el servidor enviará de inmediato el artículo más reciente que coincida, seguido de cualquier nuevo artículo a medida que esté disponible.
Sin sondeos repetidos: En lugar de sondear continuamente el servidor en busca de nuevos datos, el servidor te envía nuevos artículos, lo que reduce la sobrecarga y la latencia.

Gestión de los límites de conexión con Takeover

Cada nivel de suscripción incluye un número fijo de conexiones WebSocket paralelas. Si intentas abrir más conexiones de las que permite tu nivel, tienes dos opciones:

Comportamiento predeterminado (takeover: false): El nuevo intento de conexión será rechazado y recibirás un error que indica que has alcanzado tu límite de conexiones.
Modo takeover (takeover: true): La conexión existente más antigua se cerrará automáticamente y la nueva conexión ocupará su lugar.

Ejemplo con Takeover habilitado:

const { FinlightApi } = require('finlight-client')

const client = new FinlightApi(
  {
    apiKey: 'YOUR_API_KEY',
    logger: console,
    logLevel: 'info',
  },
  {
    // WebSocket-specific options
    takeover: true, // Automatically close oldest connection when limit is reached
  },
)

client.websocket.connect(
  { query: 'nvidia', language: 'en' },
  (article) => {
    console.log('New article received:', article)
  },
)

Cuándo usar Takeover:

Desarrollo/Pruebas: Útil cuando reinicias tu aplicación con frecuencia y no quieres cerrar manualmente las conexiones existentes.
Una sola instancia activa: Cuando quieres asegurarte de que solo la instancia de conexión más reciente esté activa.
Migración automática: Al migrar entre servidores o volver a desplegar tu aplicación.

Cuándo evitar Takeover:

Entornos de producción: Donde quieres un control explícito sobre la gestión de conexiones.
Múltiples conexiones legítimas: Cuando ejecutas intencionadamente varias instancias de conexión para distintos fines.
Depuración: Cuando necesitas entender por qué se están alcanzando los límites de conexión.

Autenticación

Para garantizar un acceso seguro y autorizado, todas las conexiones WebSocket a finlight.me deben autenticarse con tu clave de API. Esta clave verifica que tienes los permisos y derechos de acceso necesarios para recibir contenido en tiempo real.

Incluye tu clave de API en los encabezados de la solicitud inicial de handshake de WebSocket. La mayoría de las bibliotecas cliente de WebSocket te permiten especificar encabezados adicionales al crear la conexión.

Encabezado:
x-api-key: YOUR_API_KEY

Cómo obtener una clave de API:

Regístrate en el panel de finlight.
Navega a la sección API Keys para crear y gestionar tus claves.

Fragmento de código (ejemplo en Node.js):

const WebSocket = require('ws')

const socket = new WebSocket('wss://wss.finlight.me', {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
  },
})

socket.on('open', () => {
  console.log('Connected to finlight.me WebSocket!')
  // You can now send a subscription request to start receiving articles
})

socket.on('error', (err) => {
  console.error('WebSocket error:', err)
})

Mantener viva la conexión (mecanismo Ping/Pong)

Las conexiones WebSocket pueden permanecer abiertas durante largos periodos, pero las condiciones de red, los proxies y los firewalls pueden cerrar las conexiones inactivas. Para mitigarlo, finlight.me admite un mecanismo de keep-alive ping/pong.

Cómo funciona:

El cliente envía ping: A intervalos regulares (p. ej., cada 8 minutos), el cliente envía un mensaje ping al servidor.
El servidor responde pong: El servidor responde con un mensaje pong, lo que indica que la conexión sigue viva.
Gestión de no respuesta: Si el cliente no recibe un pong en un plazo determinado, puede asumir que la conexión se perdió e intentar reconectarse.

Este sencillo latido garantiza que tanto el cliente como el servidor sepan que la conexión sigue activa y puedan intercambiar datos sin interrupciones.

Ejemplo (Node.js con setInterval):

socket.on('open', () => {
  console.log('Connected to finlight WebSocket')

  // Send a ping every 8 minutes
  const pingInterval = setInterval(
    () => {
      if (socket.readyState === WebSocket.OPEN) {
        console.log('Sending ping...')
        socket.send(JSON.stringify({ action: 'ping' }))
      }
    },
    8 * 60 * 1000,
  ) // 8 minutes in milliseconds

  socket.on('message', (data) => {
    const message = JSON.parse(data)
    if (message.action === 'pong') {
      console.log('Received pong, connection is alive.')
    } else {
      // Handle other messages, such as incoming articles
      console.log('Received message:', message)
    }
  })

  socket.on('close', () => {
    clearInterval(pingInterval)
    console.log('WebSocket connection closed.')
  })
})

¿Por qué es importante Ping/Pong?

Conexiones de larga duración: Muchas aplicaciones dependen de conexiones WebSocket en ejecución continua. Sin un mecanismo de keep-alive, estas conexiones pueden fallar de forma silenciosa.
Fiabilidad de la red: Las comprobaciones ping/pong garantizan que los problemas transitorios de red no dejen al cliente sin saber que una conexión está rota.
Eficiencia de recursos: Detectar rápidamente una conexión perdida ayuda al cliente a conservar recursos al no esperar indefinidamente nuevos datos que nunca llegarán.

Límites de duración de la conexión

La infraestructura WebSocket de finlight.me funciona con AWS API Gateway, que impone una duración máxima de conexión estricta de 2 horas por sesión WebSocket. Este es un límite a nivel de plataforma: independientemente de la actividad, todas las conexiones son cerradas por AWS después de 2 horas.

Qué significa esto para ti

Tu conexión se cerrará automáticamente después de 2 horas, incluso si está recibiendo datos activamente o enviando pings.
Este comportamiento es esperado y no indica un error ni un problema de red.
Para mantener una experiencia fluida, debes reconectarte después de cada ventana de 2 horas.

Lo tenemos cubierto

Tanto nuestra biblioteca cliente de Python como la de TypeScript gestionan esto de forma transparente:

Cuando el servidor cierra la conexión después de 2 horas, el cliente detecta la desconexión.
Luego intenta reconectarse automáticamente, preservando tu flujo con una interrupción mínima.
Esto garantiza un flujo de datos continuo sin intervención manual.

Si estás construyendo tu propio cliente sin usar nuestras bibliotecas, asegúrate de implementar la lógica de reconexión por tu parte para gestionar el límite de 2 horas con elegancia.

Al entender estos conceptos básicos —conectarte de forma segura, autenticar tus solicitudes y mantener la conexión con un latido ping/pong— estás bien encaminado para integrar de forma eficiente la API WebSocket de finlight.me en tu aplicación. A partir de aquí, puedes explorar los mensajes de suscripción, filtros como source o language, y gestionar los artículos entrantes para crear experiencias ricas de noticias financieras en tiempo real.