Conceitos básicos

A API WebSocket do finlight.me fornece um fluxo contínuo, em tempo real, de artigos de notícias financeiras, entregues no momento em que ficam disponíveis. Diferentemente dos endpoints REST tradicionais, que exigem sondagens periódicas, a abordagem WebSocket permite manter uma conexão persistente e receber atualizações sem fazer requisições repetidas. Isso resulta em entrega de dados mais rápida, uso eficiente de recursos e uma experiência de usuário aprimorada.

Neste guia, você aprenderá os passos fundamentais para conectar, autenticar e manter a conexão ativa com a API WebSocket do finlight.me.

Observação: Para usar os recursos de WebSocket, você precisa de uma assinatura paga. O plano gratuito não inclui o recurso WebSocket. Você precisa de pelo menos uma assinatura com recursos de WebSocket.

Conectando-se ao WebSocket

Para começar a receber atualizações de notícias financeiras em tempo real, você precisa estabelecer uma conexão WebSocket com o servidor do finlight.me. Esta conexão permanece aberta até que você ou o servidor a fechem. Assim que a conexão é estabelecida, você pode começar a se inscrever em fluxos de artigos e receber mensagens à medida que novos artigos são publicados.

NOTA: A API WebSocket se desconecta tecnicamente após 2 horas. No entanto, nossa biblioteca cliente de TypeScript ou Python lida com isso automaticamente, reconectando por você. Você também pode reconectar manualmente se necessário.

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

Pontos-chave:

Dados em tempo real: O protocolo WebSocket habilita uma conexão full-duplex, o que significa que os dados podem fluir de e para o servidor em tempo real.
Modelo de publicação/assinatura: Após conectar, você pode especificar sua consulta (ex.: query: "nvidia") e o servidor enviará imediatamente o artigo correspondente mais recente, seguido de quaisquer novos artigos à medida que ficarem disponíveis.
Sem sondagens repetidas: Em vez de sondar continuamente o servidor em busca de novos dados, o servidor envia novos artigos a você, reduzindo a sobrecarga e a latência.

Gerenciando os limites de conexão com o Takeover

Cada nível de assinatura inclui um número fixo de conexões WebSocket paralelas. Se você tentar abrir mais conexões do que o seu nível permite, tem duas opções:

Comportamento padrão (takeover: false): A nova tentativa de conexão será rejeitada e você receberá um erro indicando que atingiu seu limite de conexões.
Modo takeover (takeover: true): A conexão existente mais antiga será fechada automaticamente e a nova conexão tomará o seu lugar.

Exemplo com 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)
  },
)

Quando usar o Takeover:

Desenvolvimento/Testes: Útil quando você reinicia sua aplicação com frequência e não quer fechar manualmente as conexões existentes.
Instância ativa única: Quando você quer garantir que apenas a instância de conexão mais recente esteja ativa.
Migração automática: Ao migrar entre servidores ou reimplantar sua aplicação.

Quando evitar o Takeover:

Ambientes de produção: Onde você quer controle explícito sobre o gerenciamento de conexões.
Múltiplas conexões legítimas: Quando você executa intencionalmente várias instâncias de conexão para fins diferentes.
Depuração: Quando você precisa entender por que os limites de conexão estão sendo atingidos.

Autenticação

Para garantir acesso seguro e autorizado, todas as conexões WebSocket ao finlight.me devem ser autenticadas com sua chave de API. Esta chave verifica que você tem as permissões e os direitos de acesso necessários para receber conteúdo em tempo real.

Inclua sua chave de API nos cabeçalhos da requisição inicial de handshake do WebSocket. A maioria das bibliotecas cliente de WebSocket permite especificar cabeçalhos adicionais ao criar a conexão.

Cabeçalho:
x-api-key: YOUR_API_KEY

Como obter uma chave de API:

Cadastre-se no painel do finlight.
Navegue até a seção API Keys para criar e gerenciar suas chaves.

Trecho de código (exemplo em 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)
})

Mantendo a conexão ativa (mecanismo Ping/Pong)

As conexões WebSocket podem permanecer abertas por longos períodos, mas as condições de rede, proxies e firewalls podem encerrar conexões inativas. Para mitigar isso, o finlight.me suporta um mecanismo de keep-alive ping/pong.

Como funciona:

O cliente envia ping: Em intervalos regulares (ex.: a cada 8 minutos), o cliente envia uma mensagem ping ao servidor.
O servidor responde pong: O servidor responde com uma mensagem pong, indicando que a conexão ainda está ativa.
Tratamento de ausência de resposta: Se o cliente não receber um pong dentro de um determinado prazo, pode assumir que a conexão foi perdida e tentar reconectar.

Esse simples batimento garante que tanto o cliente quanto o servidor saibam que a conexão ainda está ativa e possam trocar dados sem interrupção.

Exemplo (Node.js com 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 que o Ping/Pong é importante?

Conexões de longa duração: Muitas aplicações dependem de conexões WebSocket em execução contínua. Sem um mecanismo de keep-alive, essas conexões podem falhar silenciosamente.
Confiabilidade da rede: As verificações ping/pong garantem que problemas transitórios de rede não deixem o cliente sem saber que uma conexão está quebrada.
Eficiência de recursos: Detectar rapidamente uma conexão perdida ajuda o cliente a economizar recursos ao não esperar indefinidamente por novos dados que nunca chegarão.

Limites de duração da conexão

A infraestrutura WebSocket do finlight.me é alimentada pelo AWS API Gateway, que impõe uma duração máxima de conexão rígida de 2 horas por sessão WebSocket. Este é um limite em nível de plataforma — independentemente da atividade, todas as conexões são encerradas pela AWS após 2 horas.

O que isso significa para você

Sua conexão será encerrada automaticamente após 2 horas, mesmo que esteja recebendo dados ativamente ou enviando pings.
Esse comportamento é esperado e não indica um erro ou problema de rede.
Para manter uma experiência contínua, você precisa reconectar após cada janela de 2 horas.

Nós cuidamos disso

Tanto nossa biblioteca cliente de Python quanto a de TypeScript lidam com isso de forma transparente:

Quando o servidor encerra a conexão após 2 horas, o cliente detecta a desconexão.
Em seguida, ele tenta reconectar automaticamente, preservando seu fluxo com interrupção mínima.
Isso garante um fluxo de dados contínuo sem intervenção manual.

Se você está construindo seu próprio cliente sem usar nossas bibliotecas, certifique-se de implementar a lógica de reconexão do seu lado para lidar com o limite de 2 horas de forma elegante.

Ao entender esses conceitos básicos — conectar-se com segurança, autenticar suas requisições e manter a conexão com um batimento ping/pong — você está no caminho certo para integrar com eficiência a API WebSocket do finlight.me na sua aplicação. A partir daqui, você pode explorar as mensagens de assinatura, filtros como source ou language, e tratar os artigos recebidos para criar experiências ricas de notícias financeiras em tempo real.