기초

finlight.me WebSocket API는 금융 뉴스 기사가 사용 가능해지는 즉시 전달되는, 연속적인 실시간 스트림을 제공합니다. 주기적인 폴링이 필요한 전통적인 REST 엔드포인트와 달리, WebSocket 방식은 지속적인 연결을 유지하고 반복 요청 없이 업데이트를 받을 수 있게 합니다. 이는 더 빠른 데이터 전송, 효율적인 리소스 사용, 향상된 사용자 경험으로 이어집니다.

이 가이드에서는 finlight.me WebSocket API에 연결하고, 인증하고, 연결을 유지하는 기본 단계를 알아봅니다.

참고: WebSocket 기능을 사용하려면 유료 구독이 필요합니다. 무료 등급에는 WebSocket 기능이 포함되지 않습니다. 최소한 WebSocket 기능이 포함된 구독이 필요합니다.

WebSocket에 연결하기

실시간 금융 뉴스 업데이트 수신을 시작하려면 finlight.me 서버와 WebSocket 연결을 설정해야 합니다. 이 연결은 귀하 또는 서버가 닫을 때까지 열려 있습니다. 연결이 설정되는 즉시 기사 스트림 구독을 시작하고 새 기사가 게시될 때 메시지를 받을 수 있습니다.

참고: WebSocket API는 기술적으로 2시간 후에 연결이 끊어집니다. 그러나 당사의 TypeScript 또는 Python 클라이언트 라이브러리가 자동으로 재연결하여 이를 처리합니다. 필요하면 수동으로 재연결할 수도 있습니다.

WebSocket 엔드포인트:
wss://wss.finlight.me

핵심 사항:

실시간 데이터: WebSocket 프로토콜은 전이중(full-duplex) 연결을 가능하게 하여, 데이터가 서버와 실시간으로 양방향 흐를 수 있습니다.
발행/구독 모델: 연결되면 쿼리(예: 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를 피해야 할 때:

프로덕션 환경: 연결 관리를 명시적으로 제어하고자 할 때.
여러 개의 정당한 연결: 서로 다른 목적으로 여러 연결 인스턴스를 의도적으로 실행할 때.
디버깅: 연결 한도에 도달하는 이유를 파악해야 할 때.

인증

안전하고 승인된 접근을 보장하기 위해, finlight.me로의 모든 WebSocket 연결은 API 키로 인증해야 합니다. 이 키는 실시간 콘텐츠를 받는 데 필요한 권한과 접근 권리가 있음을 확인합니다.

초기 WebSocket 핸드셰이크 요청 헤더에 API 키를 포함하세요. 대부분의 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을 받지 못하면 연결이 끊겼다고 가정하고 재연결을 시도할 수 있습니다.

이 간단한 하트비트는 클라이언트와 서버 모두 연결이 여전히 활성 상태임을 알고 중단 없이 데이터를 교환할 수 있도록 보장합니다.

예시(setInterval을 사용한 Node.js):

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 점검은 일시적인 네트워크 문제로 인해 클라이언트가 연결이 끊긴 것을 인지하지 못한 채 남아 있지 않도록 보장합니다.
리소스 효율성: 끊긴 연결을 빠르게 감지하면 결코 도착하지 않을 새 데이터를 무한정 기다리지 않아 클라이언트가 리소스를 절약할 수 있습니다.

연결 지속 시간 한도

finlight.me의 WebSocket 인프라는 AWS API Gateway로 구동되며, WebSocket 세션당 2시간이라는 엄격한 최대 연결 지속 시간을 적용합니다. 이는 플랫폼 수준의 제한으로, 활동 여부와 관계없이 모든 연결은 2시간 후 AWS에 의해 닫힙니다.

이것이 의미하는 바

연결은 데이터를 활발히 수신 중이거나 ping을 보내는 중이라도 2시간 후 자동으로 닫힙니다.
이 동작은 예상된 것이며 오류나 네트워크 문제를 나타내지 않습니다.
매끄러운 경험을 유지하려면 각 2시간 창마다 재연결해야 합니다.

저희가 처리해 드립니다

당사의 Python과 TypeScript 클라이언트 라이브러리 모두 이를 투명하게 처리합니다:

서버가 2시간 후 연결을 닫으면 클라이언트가 연결 끊김을 감지합니다.
그런 다음 자동으로 재연결을 시도하여 최소한의 중단으로 스트림을 유지합니다.
이는 수동 개입 없이 연속적인 데이터 흐름을 보장합니다.

당사 라이브러리를 사용하지 않고 자체 클라이언트를 구축하는 경우, 2시간 제한을 우아하게 처리하도록 귀하 측에서 재연결 로직을 구현해야 합니다.

이러한 기초 — 안전하게 연결하고, 요청을 인증하고, ping/pong 하트비트로 연결을 유지하는 것 — 를 이해하면 finlight.me의 WebSocket API를 애플리케이션에 효율적으로 통합하는 길에 잘 들어선 것입니다. 여기서부터 구독 메시지, source나 language 같은 필터, 들어오는 기사 처리를 살펴보며 풍부한 실시간 금융 뉴스 경험을 구축할 수 있습니다.