Mastering End-to-End Streaming Through AWS API Gateway

API Gateway 스트리밍 실제 검증

엔드투엔드(백엔드→게이트웨이→CDN→브라우저) 스트리밍이 “진짜” 되는지 확인하려면, 아래 방식으로 바로 점검하면 된다.

1) 최소 테스트 구성

• 백엔드 테스트 엔드포인트: 200ms~500ms 간격으로 “작은 청크”를 write/flush 하며 총 5~10회 출력.

• API Gateway(REST): 통합의 Response transfer mode를 STREAM 으로 설정. 기본값은 BUFFERED라 반드시 바꿔야 한다. 스트리밍 모드에선 계산이 끝나기 전에 바이트를 바로 흘려보낸다. (AWS Documentation)

• 클라이언트: fetch/ReadableStream으로 수신 즉시 콘솔 로그. 첫 바이트 도착(TTFB)이 청크마다 이어져 찍히면 성공. (API Gateway의 REST 스트리밍은 2025‑11‑19 공식 지원 공지 참고) (Amazon Web Services, Inc.)

2) 기대 동작(패스 기준)

• 브라우저 네트워크 탭에서 응답이 “길게 열린 상태”로 보이고, 콘솔에는 청크별 타임스탬프가 순차 출력되어야 한다. (게이트웨이가 전체 버퍼링 없이 전송) (AWS Documentation)

3) 자주 막히는 지점(중간 계층)

• CloudFront: 오리진이 Transfer‑Encoding: chunked로 응답 중일 때, 뷰어가 Range 요청을 보내면 CloudFront가 부분이 아닌 전체 객체를 반환하는 동작이 있어, 부분 전송·점진 표시 기대가 깨질 수 있다. (버퍼링/비스트리밍처럼 보임) (AWS Documentation)

• 타 프록시/프레임워크: 일부는 기본 버퍼링으로 스트리밍을 지연시킨다(예: NextJS/일부 CDN 기본 동작). 반드시 프록시 레벨에서 버퍼링 비활성화/플러시 허용을 확인. (Repost)

4) 빠른 체크리스트

• API Gateway REST 통합 모드 STREAM 확인(HTTP_PROXY/Lambda Proxy에서만 가능). (AWS Documentation)

• 스테이지 액세스 로그에 $context.integration.responseTransferMode 가 STREAMED 로 찍히는지 확인. (AWS Documentation)

• CloudFront 사용 시 Range 상호작용과 오리진의 chunked 조합을 피하거나, 경로 분리로 스트리밍 엔드포인트는 CF를 우회/별도 배포. (AWS Documentation)

• Lambda를 직접 쓰는 경우 InvokeWithResponseStream/Function URL 스트리밍 모드도 선택지. (VPC·타임아웃 제약 확인) (AWS Documentation)

5) 샘플 스니펫(클라이언트)