응답 스트리밍 지원 Lambda 함수 작성

응답 스트리밍 함수의 핸들러 작성은 일반적인 핸들러 패턴과 다릅니다. 스트리밍 함수를 작성할 때는 다음을 반드시 수행하세요.

출처: AWS Lambda 개발자 안내서

본문

함수를 awslambda.streamifyResponse() 데코레이터로 감쌉니다. awslambda 전역 객체는 Lambda의 Node.js 런타임 환경이 제공합니다.
모든 데이터 처리가 완료되도록 스트림을 우아하게(end) 종료합니다.

스트림 응답 핸들러 함수 구성

런타임에 Lambda가 함수의 응답을 스트리밍해야 한다는 것을 알리려면 함수를 streamifyResponse() 데코레이터로 감싸야 합니다. 이는 런타임이 응답 스트리밍에 올바른 로직 경로를 사용하고 함수가 응답을 스트리밍할 수 있게 합니다.

streamifyResponse() 데코레이터는 다음 파라미터를 받는 함수를 받습니다.

event – 함수 URL 호출 이벤트에 대한 정보(HTTP 메서드, 쿼리 파라미터, 요청 본문 등)를 제공합니다.
responseStream – 쓰기 가능한 스트림(writable stream)을 제공합니다.
context – 호출, 함수, 실행 환경에 대한 정보를 담은 메서드·속성을 제공합니다.

responseStream 객체는 Node.js의 writableStream입니다. 다른 스트림과 마찬가지로 pipeline() 메서드를 사용해야 합니다.

awslambda 전역 객체는 Lambda의 Node.js 런타임이 자동으로 제공하며 import 가 필요하지 않습니다.

import { pipeline } from 'node:stream/promises';
import { Readable } from 'node:stream';

export const echo = awslambda.streamifyResponse(async (event, responseStream, _context) => {
  // As an example, convert event to a readable stream.
  const requestStream = Readable.from(Buffer.from(JSON.stringify(event)));

  await pipeline(requestStream, responseStream);
});

responseStream은 스트림에 쓰는 write() 메서드를 제공하지만 가능하면 pipeline()을 사용할 것을 권장합니다. pipeline()을 사용하면 더 빠른 읽기 스트림에 쓰기 가능한 스트림이 압도당하지 않도록 보장합니다.

스트림 종료(Ending the stream)

핸들러가 반환되기 전에 스트림을 올바르게 종료해야 합니다. pipeline() 메서드는 이를 자동으로 처리합니다.

다른 사용 사례에는 responseStream.end() 메서드를 호출해 스트림을 올바르게 종료합니다. 이 메서드는 더 이상 스트림에 데이터를 쓰지 않아야 한다는 신호를 보냅니다. pipeline()이나 pipe()로 스트림에 쓴다면 이 메서드는 필요하지 않습니다.

Node.js 24부터 Lambda는 핸들러가 반환되거나 응답 스트림이 끝난 뒤 미해결 프로미스(unresolved promises)가 완료되기를 더 이상 기다리지 않습니다. 함수가 타이머나 fetch 같은 추가 비동기 작업에 의존한다면 핸들러에서 이를 await 해야 합니다.

import { pipeline } from 'node:stream/promises';

export const handler = awslambda.streamifyResponse(async (event, responseStream, _context) => {
  await pipeline(requestStream, responseStream);
});

export const handler = awslambda.streamifyResponse(async (event, responseStream, _context) => {
  responseStream.write("Hello ");
  responseStream.write("world ");
  responseStream.write("from ");
  responseStream.write("Lambda!");
  responseStream.end();
});

응답 스트리밍 지원 Lambda 함수 작성