메인 콘텐츠로 건너뛰기

​
연결 해제란 무엇인가?

스트리밍 API에 연결한다는 것은 매우 장시간 지속되는 HTTPS 요청을 보내고, 응답을 순차적으로 파싱하는 것을 의미합니다. 필터링된 스트림 엔드포인트에 연결할 때는 HTTPS 요청을 보내고, 가능한 한 오래 결과 스트림을 소비하는 것이 바람직합니다. 서버 측 오류, 과도한 클라이언트 측 지연, 네트워크 문제, 정기적인 서버 유지 보수, 중복 로그인 등의 상황이 아니라면, 당사 서버는 연결을 무기한 유지합니다. 스트리밍 엔드포인트 연결에서는 연결 해제가 발생할 가능성이 높으며, 이는 예상해야 하며 재연결 로직을 구현해 두어야 합니다.  

​
스트리밍 연결이 끊길 수 있는 이유

스트림은 여러 가지 이유로 연결이 끊길 수 있습니다. 실패 원인을 파악하려면 스트림에서 반환된 오류 메시지를 확인하세요. 연결 해제의 가능한 이유는 다음과 같습니다.
  • 인증 오류(예: 잘못된 토큰 사용 또는 부적절한 인증 방식 사용)
  • X 측 스트리밍 서버 재시작. 보통 코드 배포와 관련되며, 일반적으로 예상하고 이에 맞춰 설계해야 합니다.
  • 클라이언트가 스트림이 전달하는 게시물 수를 따라가지 못하거나 데이터를 너무 느리게 읽는 경우. 모든 스트리밍 연결은 클라이언트로 전송할 메시지 큐를 기반으로 합니다. 시간이 지나 큐가 과도하게 커지면 연결이 종료됩니다.
  • 계정이 게시물에 대한 일일/월간 쿼터를 초과함
  • 활성 중복 연결이 너무 많음
  • 클라이언트가 갑자기 데이터 읽기를 중단함. 스트림에서 읽는 게시물 처리 속도가 급격히 떨어지면 연결이 종료됩니다.
  • 서버와 클라이언트 간 네트워크 문제 가능성
  • 일시적인 서버 측 이슈, 예정된 점검 및 업데이트. (상태 페이지 확인: https://api.twitterstat.us/)  

​
일반적인 연결 해제 오류에는 다음이 포함됩니다:

	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "운영상의 이유로 이 스트림이 상위 측에서 연결 해제되었습니다.",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}

{
	"title": "ConnectionException",
	"detail": "해당 스트림이 현재 허용된 최대 연결 한도에 도달했습니다.",
	"connection_issue": "TooManyConnections",
	"type": "https://api.x.com/2/problems/streaming-connection"
}

​
연결 끊김을 예상하고 재연결하기

게시물을 스트리밍할 때는 끊김이 발생할 수 있음을 염두에 두고 가능한 한 오래 연결을 유지하는 것이 목표입니다. 이 엔드포인트는 20초 간격의 keep-alive 하트비트를 제공합니다(새 줄 문자로 표시됩니다). 이 신호를 사용해 연결이 끊겼는지 감지하세요.
  1. 코드가 신규 콘텐츠와 하트비트 수신이 모두 중단된 시점을 감지해야 합니다.
  2. 그런 경우 재연결 로직을 실행하도록 하세요. 일부 클라이언트와 언어는 읽기 타임아웃을 지정할 수 있으며, 이를 20초로 설정할 수 있습니다.
  3. 서비스는 이러한 끊김을 감지하면 가능한 한 빨리 재연결해야 합니다.
이미 설정된 연결이 끊기면 즉시 재연결을 시도하세요. 재연결에 실패하면 발생한 오류 유형에 따라 재연결 시도를 점진적으로 늦추세요:
  • TCP/IP 수준 네트워크 오류에는 선형 백오프를 적용하세요. 이러한 문제는 대체로 일시적이며 빠르게 해소됩니다. 각 시도마다 재연결 지연 시간을 250ms씩 늘려 최대 16초까지 증가시키세요.
  • 재연결이 적절한 HTTP 오류에는 지수 백오프를 적용하세요. 5초 대기부터 시작해 시도할 때마다 두 배로 늘리고 최대 320초까지 증가시키세요.
  • HTTP 429 오류(요율 제한 초과)에는 지수 백오프를 적용하세요. 1분 대기부터 시작해 각 시도마다 두 배로 늘리세요. HTTP 429를 받을 때마다 계정의 요율 제한이 해제될 때까지 기다려야 하는 시간이 증가한다는 점에 유의하세요.  

​
손실된 데이터 복구

연결이 끊겼을 경우, 놓쳤을 수 있는 모든 데이터를 확보하기 위해 사용할 수 있는 다양한 전략이 있습니다. 통합 가이드의 데이터 복구 문서에 누락된 데이터를 복구하기 위해 수행할 수 있는 핵심 단계를 정리해 두었습니다.   

​
요청 한도 및 사용량

연결 한도를 확인하려면 응답에 세 가지 헤더가 포함되어 반환됩니다. 이는 규칙 엔드포인트를 얼마나 자주 사용할 수 있는지와 스트리밍 엔드포인트에서 허용되는 재연결 시도 횟수를 파악하는 데 유용합니다.
  • x-rate-limit-limit은 15분 윈도우 동안 클라이언트에 할당된 최대 요청 수를 나타냅니다.
  • x-rate-limit-remaining은 현재 15분 윈도우에서 지금까지 사용한 요청 수를 나타냅니다.
  • x-rate-limit-reset은 15분 윈도우가 언제 다시 시작되는지(그 시점에 x-rate-limit-remaining이 0으로 초기화됨)를 나타내는 UNIX 타임스탬프입니다.
filter stream 엔드포인트는 현재 사용량 데이터를 보고하지 않습니다. 전달된 게시물 개수를 확인하려면 코드에 계량 로직을 구현하여 소비량을 측정하고 필요 시 일시 중지할 수 있도록 하세요. 스트림 클라이언트 코드는 수신한 게시물을 선입선출(FIFO) 큐 또는 유사한 메모리 구조에 단순히 삽입하고, 별도의 프로세스/스레드가 해당 큐에서 게시물을 가져가 파싱 및 저장 준비를 수행하도록 하세요. 이러한 설계를 통해 유입되는 게시물량이 급격히 변해도 효율적으로 확장 가능한 서비스를 구현할 수 있습니다. 개념적으로는 HTTP로 무한히 긴 파일을 다운로드하는 것과 유사하게 생각할 수 있습니다.

​
재연결 모범 사례

백오프 전략 테스트 백오프 구현을 검증하는 좋은 방법은 잘못된 인증 자격 증명을 사용해 재연결 시도를 관찰하는 것입니다. 적절한 구현이라면 429 응답을 받지 않습니다. 다중 재연결에 대한 경보 발송 클라이언트의 재연결 간격이 상한 임계값에 도달하면, 연결에 영향을 주는 문제를 신속히 분류할 수 있도록 알림을 보내야 합니다. DNS 변경 처리 클라이언트 프로세스가 DNS TTL(Time To Live)을 준수하는지 테스트하십시오. 일부 스택은 프로세스 실행 동안 해석된 주소를 캐시하여, 지정된 TTL 내 발생한 DNS 변경을 반영하지 않습니다. 이러한 과도한 캐싱은 X가 IP 주소 간에 부하를 분산·조정하는 동안 클라이언트 서비스 장애로 이어질 수 있습니다. User Agent user-agent HTTP 헤더에 클라이언트 버전을 포함하십시오. 이는 X 측에서 문제를 진단하는 데 매우 중요합니다. 환경상 user-agent 필드를 설정할 수 없다면 x-user-agent 헤더를 설정하십시오.