Google API Gateway에서 SSE가 한꺼번에 도착한다면: 스트리밍 켜는 법

세 줄 요약

Google API Gateway의 스트리밍 공개 미리보기는 새 게이트웨이를 만들 때 켤 수 있다.
SSE의 기본 요청 제한 시간은 15초다. 스트리밍을 켜는 것만으로 한 시간이 확보되지는 않는다.
백엔드의 제한 시간과 클라이언트의 출력 버퍼링도 따로 확인해야 한다.

SSE를 받으려면 스트리밍을 켠 게이트웨이가 필요하다

Cloud Run을 직접 호출하면 답변이 조금씩 나오는데 게이트웨이를 거치면 마지막에 몰려오는 상황은 Google 개발자 포럼에도 올라온 질문이다. 당시의 미지원 설명을 지금 그대로 적용할 필요는 없다. 9월 29일 릴리스 노트에는 스트리밍 공개 미리보기가 등록됐고, Google은 10월 22일 개발자 블로그에서 활용 방법을 소개했다.

스트리밍 모드는 생성 후 바꿀 수 없다. 백엔드가 이미 SSE를 내보낸다면 다음처럼 새 게이트웨이를 만든다. 대문자 값에는 프로젝트에 있는 API·설정·리전과 새 게이트웨이 이름을 넣는다.

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID \
  --api-config=CONFIG_ID \
  --location=REGION \
  --enable-streaming

이는 공식 생성 명령의 스트리밍 옵션이다. API 명세에 별도의 스트리밍 전용 확장을 추가하지는 않는다. 다만 기존 설정의 요청 제한 시간이 짧다면 아래 값을 수정한 API 설정이 필요하다.

답변이 15초 뒤 끊기면 deadline을 확인한다

SSE와 청크 전송에서 deadline은 응답 전체에 허용된 시간이다. 데이터가 계속 흐르더라도 시간이 끝나면 연결이 끊긴다. gcloud 문서가 명시한 기본값은 15초, 스트리밍 게이트웨이의 상한은 3600초다.

다음은 공식 가이드에 따른 OpenAPI 2.0 백엔드 설정 예시다. 주소는 실제 백엔드로 바꾸며, 3600은 허용 가능한 최대값이다.

x-google-backend:
  address: https://YOUR_SERVICE.run.app
  protocol: h2
  deadline: 3600.0

백엔드도 같은 시간 동안 요청을 유지해야 한다. Cloud Run의 기본 제한 시간은 300초다. 게이트웨이에 한 시간을 주어도 Cloud Run이 5분에 응답을 닫으면 스트림은 그때 끝난다. 앱 프레임워크와 호출 클라이언트에 더 짧은 제한이 있는지도 함께 확인한다.

새 주소와 curl의 출력 방식을 함께 확인한다

생성된 게이트웨이를 조회해 effectiveStreamingMode가 EFFECTIVE_STREAMING_MODE_ENABLED인지 확인한다. 호출 주소는 같은 조회 결과의 defaultHostname을 사용한다.

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=REGION

응답 확인에는 curl -N이 유용하다. -N은 curl이 받은 데이터를 출력하면서 모아 두는 동작을 끈다. 기존 요청의 인증 헤더·본문은 유지하고 이 옵션을 더해, 백엔드 직접 호출과 게이트웨이 호출을 각각 비교할 수 있다. 서버가 응답을 모아 보내는 설정까지 이 옵션이 바꾸지는 않는다.

한편 32MB 응답 크기 제한은 스트리밍·청크 응답에 적용되지 않는다. 요청 본문에는 여전히 32MB 제한이 적용된다. 긴 답변을 받는 기능과 큰 파일을 올리는 기능의 한도를 혼동하면 안 된다.

커스텀 도메인을 쓰던 서비스는 이전 경로가 달라진다

현재 공개 미리보기에서 스트리밍 게이트웨이는 Serverless NEG와 외부 Application Load Balancer 뒤에 둘 수 없다. 이 경로에 의존하는 커스텀 도메인도 지원되지 않으며, Terraform으로 스트리밍을 켜는 기능도 아직 없다.

따라서 기존 주소를 통째로 교체하기 전에 새 게이트웨이 주소로 SSE 수신과 제한 시간을 확인하는 순서가 맞다. 연결이 끊겼을 때의 재접속도 앱이 처리해야 한다. Cloud Run에서는 재접속이 새 요청이므로, 이전 응답을 이어 받을지 새로 생성할지도 애플리케이션에서 정해야 한다.