메인 콘텐츠로 건너뛰기

​
연결 해제란 무엇인가요?

스트리밍 API에 연결한다는 것은 매우 장시간 유지되는 HTTPS 요청을 보내고 응답을 순차적으로 파싱하는 것을 의미합니다. filtered stream 엔드포인트에 연결할 때는 HTTPS 요청을 만든 뒤, 가능한 한 오래 그 결과 스트림을 읽어들이고 처리해야 합니다. 서버 측 오류, 과도한 클라이언트 측 지연, 네트워크 문제, 정기적인 서버 유지 보수, 중복 로그인 등의 경우를 제외하면, 당사 서버는 연결을 무기한 유지합니다. 스트리밍 엔드포인트에 대한 연결에서는 연결 해제가 자주 발생할 수 있으며, 이러한 상황을 예상하고 재연결 로직을 구현해야 합니다.  

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

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

​
일반적인 연결 끊김 errors는 다음과 같습니다:

	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "이 스트림은 운영상의 이유로 업스트림에서 연결이 끊어졌습니다.",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}

{
	"title": "ConnectionException",
	"detail": "This stream is currently at the maximum allowed connection limit.",
	"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 응답을 받을 때마다, 해당 계정에 대한 rate limit이 더 이상 적용되지 않을 때까지 대기해야 하는 시간이 증가한다는 점에 유의하십시오.  

​
손실된 데이터 복구

연결이 끊겼다면, 놓쳤을 수 있는 모든 데이터를 다시 수신할 수 있도록 활용할 수 있는 여러 가지 전략이 있습니다. 누락된 데이터를 복구하기 위해 취할 수 있는 핵심 단계들을 데이터 복구 통합 가이드에 정리해 두었습니다.   

​
요청 한도 및 사용량

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

​
재연결 모범 사례

백오프(backoff) 전략을 테스트하세요 백오프 구현을 테스트하는 좋은 방법은 잘못된 인증 자격 증명을 사용하고 재연결 시도를 관찰해 보는 것입니다. 올바른 구현이라면 429 응답을 전혀 받지 않아야 합니다. 여러 번 재연결될 때 알림을 보내세요 클라이언트가 재연결 간격에 대해 설정한 상한선에 도달하면, 연결에 영향을 주는 문제를 신속히 파악하고 조치할 수 있도록 운영자에게 알림을 보내야 합니다. DNS 변경을 처리하세요 클라이언트 프로세스가 DNS Time To Live(TTL)를 준수하는지 테스트하세요. 일부 스택은 프로세스가 실행되는 동안 조회된 주소를 캐싱하고, 지정된 TTL 내에서 발생하는 DNS 변경 사항을 반영하지 않습니다. 이러한 과도한 캐싱은 X가 IP 주소 간에 부하를 이동할 때 클라이언트에서 서비스 중단을 유발할 수 있습니다. User Agent user-agent HTTP 헤더에 클라이언트의 버전 정보가 포함되어 있는지 확인하세요. 이는 X 측에서 문제를 진단하는 데 매우 중요합니다. 환경상 user-agent 필드를 설정할 수 없다면 x-user-agent 헤더를 설정하세요.