diff --git a/docs/features/event-handler/rest.md b/docs/features/event-handler/rest.md index 7f53c1fe2c..48bc7e239e 100644 --- a/docs/features/event-handler/rest.md +++ b/docs/features/event-handler/rest.md @@ -595,11 +595,31 @@ For complete control you can return an `APIGatewayProxyEvent` (`v1` or `v2`) and ### Response streaming -!!! note "Coming soon" +!!! note "Compatibility" + Response streaming is only available for [API Gateway REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/response-transfer-mode.html){target="_blank"} + and [Lambda function URLs](https://docs.aws.amazon.com/lambda/latest/dg/configuration-response-streaming.html){target="_blank"}. + +You can send responses to the client using HTTP streaming by wrapping your router with the `streamify` function to turn all the associated route handlers into stream compatible handlers. This is useful when you need to send large payloads or want to start sending data before the entire response is ready. + +In order to gain the most benefit, you should return either a readable [Nodejs stream](https://nodejs.org/api/stream.html#readable-streams){target="_blank"}, +a duplex [Nodejs stream](https://nodejs.org/api/stream.html#class-streamduplex){target="_blank"}, or +a [Web stream](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API){target="_blank"} from your handlers. However, you can also return +other types and these will also be delivered via HTTP streaming. + +=== "index.ts" + + ```ts hl_lines="3 17" + --8<-- "examples/snippets/event-handler/rest/advanced_response_streaming.ts:4" + ``` + +!!! tip "When to use streaming" + Consider response streaming when: -At the moment, Event Handler does not support streaming responses. This means that the entire response must be generated and returned by the route handler before it can be sent to the client. + - Returning large payloads (> 6MB) + - Processing data that can be sent incrementally + - Reducing time-to-first-byte for long-running operations is a requirement -Please [check this issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/4476) for more details and add 👍 if you would like us to prioritize it. + For most use cases, the standard `resolve` method is sufficient. ### Debug mode diff --git a/examples/snippets/event-handler/rest/advanced_response_streaming.ts b/examples/snippets/event-handler/rest/advanced_response_streaming.ts new file mode 100644 index 0000000000..51c1741e89 --- /dev/null +++ b/examples/snippets/event-handler/rest/advanced_response_streaming.ts @@ -0,0 +1,20 @@ +declare function createVideoStream(): Readable; + +import type { Readable } from 'node:stream'; +import { + Router, + streamify, +} from '@aws-lambda-powertools/event-handler/experimental-rest'; + +const app = new Router(); + +app.get('/video-stream', async (reqCtx) => { + reqCtx.res.headers.set('content-type', 'video/mp4'); + return createVideoStream(); +}); + +app.get('/hello', () => { + return { message: 'Hello World' }; +}); + +export const handler = streamify(app);