From 96e9b3fcdac5d43791011e734aa164e3dee3b0b5 Mon Sep 17 00:00:00 2001 From: svozza Date: Fri, 21 Nov 2025 01:55:11 +0000 Subject: [PATCH 1/2] docs(event-handler): add response streaming docs --- docs/features/event-handler/rest.md | 26 ++++++++++++++++--- .../rest/advanced_response_streaming.ts | 20 ++++++++++++++ 2 files changed, 43 insertions(+), 3 deletions(-) create mode 100644 examples/snippets/event-handler/rest/advanced_response_streaming.ts diff --git a/docs/features/event-handler/rest.md b/docs/features/event-handler/rest.md index b2726f88cf..3e09447b5f 100644 --- a/docs/features/event-handler/rest.md +++ b/docs/features/event-handler/rest.md @@ -544,11 +544,31 @@ We plan to add first-class support for binary responses in a future release. Ple ### 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) + and [Lambda function URLs](https://docs.aws.amazon.com/lambda/latest/dg/configuration-response-streaming.html). + +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), +a duplex [Nodejs stream](https://nodejs.org/api/stream.html#class-streamduplex), or +a [Web stream](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API#browser_compatibility) from your handlers. However, you can also return +other types and these will also be delivered via HTTP streaming. + +=== "index.ts" + + ```ts hl_lines="7 11" + --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); From c5a06856b78b99b059246692f029bb0cca261c7c Mon Sep 17 00:00:00 2001 From: Swopnil Dangol Date: Fri, 21 Nov 2025 15:47:35 +0000 Subject: [PATCH 2/2] Apply suggestions from code review --- docs/features/event-handler/rest.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/features/event-handler/rest.md b/docs/features/event-handler/rest.md index 3e09447b5f..8c1bdcc3b1 100644 --- a/docs/features/event-handler/rest.md +++ b/docs/features/event-handler/rest.md @@ -545,19 +545,19 @@ We plan to add first-class support for binary responses in a future release. Ple ### Response streaming !!! note "Compatibility" - Response streaming is only available for [API Gateway REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/response-transfer-mode.html) - and [Lambda function URLs](https://docs.aws.amazon.com/lambda/latest/dg/configuration-response-streaming.html). + 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), -a duplex [Nodejs stream](https://nodejs.org/api/stream.html#class-streamduplex), or -a [Web stream](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API#browser_compatibility) from your handlers. However, you can also return +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="7 11" + ```ts hl_lines="3 17" --8<-- "examples/snippets/event-handler/rest/advanced_response_streaming.ts:4" ```