Основы

WebSocket API finlight.me предоставляет непрерывный поток финансовых новостных статей в реальном времени, доставляемых в момент их появления. В отличие от традиционных REST-эндпоинтов, требующих периодического опроса, подход WebSocket позволяет поддерживать постоянное подключение и получать обновления без повторных запросов. Это обеспечивает более быструю доставку данных, эффективное использование ресурсов и улучшенный пользовательский опыт.

В этом руководстве вы изучите основные шаги по подключению, аутентификации и поддержанию соединения с WebSocket API finlight.me.

Примечание: Для использования функций WebSocket требуется платная подписка. Бесплатный тариф не включает функцию WebSocket. Вам нужна как минимум подписка с функциями WebSocket.

Подключение к WebSocket

Чтобы начать получать обновления финансовых новостей в реальном времени, необходимо установить WebSocket-подключение к серверу finlight.me. Это подключение остаётся открытым, пока вы или сервер его не закроете. Как только подключение установлено, вы можете подписываться на потоки статей и получать сообщения по мере публикации новых статей.

ПРИМЕЧАНИЕ: WebSocket API технически отключается через 2 часа. Однако наша клиентская библиотека на TypeScript или Python обрабатывает это автоматически, переподключаясь за вас. При необходимости вы также можете переподключиться вручную.

Эндпоинт WebSocket:
wss://wss.finlight.me

Ключевые моменты:

Данные в реальном времени: Протокол WebSocket обеспечивает полнодуплексное соединение, то есть данные могут передаваться к серверу и от него в реальном времени.
Модель публикация/подписка: После подключения вы можете указать запрос (например, query: "nvidia"), и сервер сразу отправит самую свежую подходящую статью, а затем — новые статьи по мере их появления.
Без повторного опроса: Вместо непрерывного опроса сервера на предмет новых данных сервер сам отправляет вам новые статьи, снижая накладные расходы и задержку.

Управление лимитами подключений с помощью Takeover

Каждый уровень подписки включает фиксированное число параллельных WebSocket-подключений. Если вы попытаетесь открыть больше подключений, чем разрешает ваш уровень, у вас есть два варианта:

Поведение по умолчанию (takeover: false): Новая попытка подключения будет отклонена, и вы получите ошибку о достижении лимита подключений.
Режим takeover (takeover: true): Самое старое существующее подключение будет автоматически закрыто, а новое займёт его место.

Пример с включённым Takeover:

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

Когда использовать Takeover:

Разработка/Тестирование: Полезно, когда вы часто перезапускаете приложение и не хотите вручную закрывать существующие подключения.
Один активный экземпляр: Когда нужно гарантировать, что активен только самый свежий экземпляр подключения.
Автоматическая миграция: При миграции между серверами или повторном развёртывании приложения.

Когда избегать Takeover:

Производственные среды: Где нужен явный контроль над управлением подключениями.
Несколько легитимных подключений: Когда вы намеренно запускаете несколько экземпляров подключения для разных целей.
Отладка: Когда нужно понять, почему достигаются лимиты подключений.

Аутентификация

Для обеспечения безопасного и авторизованного доступа все WebSocket-подключения к finlight.me должны аутентифицироваться вашим ключом API. Этот ключ подтверждает, что у вас есть необходимые разрешения и права доступа для получения контента в реальном времени.

Включите свой ключ API в заголовки первоначального запроса WebSocket-рукопожатия. Большинство клиентских библиотек WebSocket позволяют указывать дополнительные заголовки при создании подключения.

Заголовок:
x-api-key: YOUR_API_KEY

Как получить ключ API:

Зарегистрируйтесь в панели finlight.
Перейдите в раздел API Keys, чтобы создавать ключи и управлять ими.

Фрагмент кода (пример на 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)
})

Поддержание соединения (механизм Ping/Pong)

WebSocket-подключения могут оставаться открытыми длительное время, но сетевые условия, прокси и брандмауэры могут разрывать неактивные подключения. Чтобы смягчить это, finlight.me поддерживает механизм поддержания соединения ping/pong.

Как это работает:

Клиент отправляет ping: Через регулярные интервалы (например, каждые 8 минут) клиент отправляет серверу сообщение ping.
Сервер отвечает pong: Сервер отвечает сообщением pong, указывая, что соединение всё ещё активно.
Обработка отсутствия ответа: Если клиент не получает pong в течение определённого времени, он может предположить, что соединение потеряно, и попытаться переподключиться.

Этот простой «сердечный ритм» гарантирует, что и клиент, и сервер знают, что соединение всё ещё активно, и могут обмениваться данными без перебоев.

Пример (Node.js с 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.')
  })
})

Почему Ping/Pong важен?

Долгоживущие подключения: Многие приложения полагаются на непрерывно работающие WebSocket-подключения. Без механизма поддержания соединения эти подключения могут незаметно выходить из строя.
Надёжность сети: Проверки ping/pong гарантируют, что временные сетевые проблемы не оставят клиента в неведении о разорванном соединении.
Эффективность ресурсов: Быстрое обнаружение потерянного соединения помогает клиенту экономить ресурсы, не ожидая бесконечно новых данных, которые так и не поступят.

Лимиты длительности подключения

Инфраструктура WebSocket finlight.me работает на AWS API Gateway, который накладывает жёсткий максимум длительности подключения в 2 часа на каждую WebSocket-сессию. Это ограничение на уровне платформы — независимо от активности, все подключения закрываются AWS через 2 часа.

Что это значит для вас

Ваше подключение будет автоматически закрыто через 2 часа, даже если оно активно получает данные или отправляет ping.
Это ожидаемое поведение и не указывает на ошибку или проблему с сетью.
Чтобы сохранить бесперебойную работу, необходимо переподключаться после каждого 2-часового окна.

Мы обо всём позаботились

Обе наши клиентские библиотеки — Python и TypeScript — обрабатывают это прозрачно:

Когда сервер закрывает подключение через 2 часа, клиент обнаруживает разрыв.
Затем он автоматически пытается переподключиться, сохраняя ваш поток с минимальным перерывом.
Это обеспечивает непрерывный поток данных без ручного вмешательства.

Если вы создаёте собственный клиент без использования наших библиотек, обязательно реализуйте логику переподключения на своей стороне, чтобы корректно обрабатывать 2-часовой лимит.

Понимая эти основы — безопасное подключение, аутентификацию запросов и поддержание соединения «сердечным ритмом» ping/pong — вы уверенно движетесь к эффективной интеграции WebSocket API finlight.me в своё приложение. Отсюда вы можете изучить сообщения подписки, фильтры вроде source или language и обработку входящих статей, чтобы создавать насыщенные финансовые новостные сервисы в реальном времени.