docs(event-handler): update binary response docs (aws-powertools#4783)

Co-authored-by: Swopnil Dangol <[email protected]>

Author: svozza

docs/features/event-handler/rest.md

@@ -514,33 +514,84 @@ You can enable response compression by using the `compress` middleware. This wil
 
 ### Binary responses
 
-!!! note "Coming soon"
+If you need to return binary data, there are several ways you can do so based on how much control you require.
+
+#### Auto serialization
 
 As described in the [response auto serialization](#response-auto-serialization) section, when you return a JavaScript object from your route handler, we automatically serialize it to JSON and set the `Content-Type` header to `application/json`.
 
-If you need to return binary data (e.g. images, PDFs, etc), you will need to return an API Gateway Proxy result directly, setting the `isBase64Encoded` flag to `true` and base64 encoding the binary data, as well as setting the appropriate `Content-Type` header.
+A similar pattern applies to binary data where you can return an `ArrayBuffer`,
+a [Nodejs stream](https://nodejs.org/api/stream.html){target="_blank"}, or
+a [Web stream](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API#browser_compatibility){target="_blank"}
+directly from your handler. We will automatically serialize the response by setting the `isBase64Encoded` flag to `true` and `base64` encoding the binary data.
+
+!!! note "Content types"
+    The default header will be set to `application/json`. If you wish to change this,
+    e.g., in the case of images, PDFs, videos, etc, then you should use the `reqCtx.res.headers` object to set the appropriate header.
 
 === "index.ts"
 
-    ```ts hl_lines="10-17"
-    --8<-- "examples/snippets/event-handler/rest/advanced_binary_responses.ts"
+    ```ts hl_lines="8-9"
+    --8<-- "examples/snippets/event-handler/rest/advanced_binary_response_auto.ts"
     ```
 
 === "Request"
 
     ```json
-    --8<-- "examples/snippets/event-handler/rest/samples/advanced_binary_req.json"
+    --8<-- "examples/snippets/event-handler/rest/samples/advanced_binary_req_logo_image.json"
     ```
 
 === "Response"
 
     ```json
-    --8<-- "examples/snippets/event-handler/rest/samples/advanced_binary_res.json"
+    --8<-- "examples/snippets/event-handler/rest/samples/advanced_binary_res_logo_image.json"
     ```
 
-You can use binary responses together with the [`compress`](#compress) feature, and the client must send the `Accept` header with the correct media type.
+#### Set `isBase64Encoded` parameter
 
-We plan to add first-class support for binary responses in a future release. Please [check this issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/4514) for more details and examples, and add 👍 if you would like us to prioritize it.
+You can indicate that you wish to `base64` encode any response, regardless of type, by setting the `isBase64Encoded` field in `reqCtx` to `true`.
+
+=== "index.ts"
+
+    ```ts hl_lines="7"
+    --8<-- "examples/snippets/event-handler/rest/advanced_binary_response_reqCtx.ts"
+    ```
+
+=== "Request"
+
+    ```json
+    --8<-- "examples/snippets/event-handler/rest/samples/advanced_binary_req_json64.json"
+    ```
+
+=== "Response"
+
+    ```json
+    --8<-- "examples/snippets/event-handler/rest/samples/advanced_binary_res_json64.json"
+    ```
+
+#### Manual serialization
+
+For complete control you can return an `APIGatewayProxyEvent` (`v1` or `v2`) and this will be handled transparently by the resolver.
+
+=== "index.ts"
+
+    ```ts hl_lines="8-16"
+    --8<-- "examples/snippets/event-handler/rest/advanced_binary_response_manual.ts"
+    ```
+
+=== "Request"
+
+    ```json
+    --8<-- "examples/snippets/event-handler/rest/samples/advanced_binary_req_logo_image.json"
+    ```
+
+=== "Response"
+
+    ```json
+    --8<-- "examples/snippets/event-handler/rest/samples/advanced_binary_res_logo_image.json"
+    ```
+!!! note "Compression"
+    If you wish to use binary responses together with the [`compress`](#compress) feature, the client must send the `Accept` header with the correct media type.
 
 ### Response streaming
 

examples/snippets/event-handler/rest/advanced_binary_response_auto.ts

@@ -0,0 +1,13 @@
+import { createReadStream } from 'node:fs';
+import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
+import type { Context } from 'aws-lambda';
+
+const app = new Router();
+
+app.get('/logo', async (reqCtx) => {
+  reqCtx.res.headers.set('Content-Type', 'image/png');
+  return createReadStream(`${process.env.LAMBDA_TASK_ROOT}/logo.png`);
+});
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

examples/snippets/event-handler/rest/advanced_binary_responses.ts renamed to examples/snippets/event-handler/rest/advanced_binary_response_manual.ts

@@ -1,11 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
-import { compress } from '@aws-lambda-powertools/event-handler/experimental-rest/middleware';
 import type { Context } from 'aws-lambda';
 
 const app = new Router();
 
-app.get('/logo', [compress()], async () => {
+app.get('/logo', async () => {
   const logoFile = await readFile(`${process.env.LAMBDA_TASK_ROOT}/logo.png`);
   return {
     body: logoFile.toString('base64'),

examples/snippets/event-handler/rest/advanced_binary_response_reqCtx.ts

@@ -0,0 +1,12 @@
+import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
+import type { Context } from 'aws-lambda';
+
+const app = new Router();
+
+app.get('/json64', async (reqCtx) => {
+  reqCtx.isBase64Encoded = true;
+  return { message: 'Hello World!' };
+});
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

examples/snippets/event-handler/rest/samples/advanced_binary_req.json

@@ -0,0 +1,5 @@
+{
+  "resource": "/json64",
+  "path": "/json64",
+  "httpMethod": "GET"
+}

examples/snippets/event-handler/rest/samples/advanced_binary_req_json64.json

@@ -0,0 +1,5 @@
+{
+  "resource": "/logo",
+  "path": "/logo",
+  "httpMethod": "GET"
+}

examples/snippets/event-handler/rest/samples/advanced_binary_req_logo_image.json

@@ -0,0 +1,8 @@
+{
+  "body": "eyJtZXNzYWdlIjoiSGVsbG8gV29ybGQifQ==",
+  "headers": {
+    "Content-Type": "application/json"
+  },
+  "isBase64Encoded": true,
+  "statusCode": 200
+}

examples/snippets/event-handler/rest/samples/advanced_binary_res_json64.json

@@ -1,8 +1,7 @@
 {
   "body": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iMjU2cHgiIGhlaWdodD0iMjU2cHgiIHZpZXdCb3g9IjAgMCAyNTYgMjU2IiB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHByZXNlcnZlQXNwZWN0UmF0aW89InhNaWRZTWlkIj4KICAgIDx0aXRsZT5BV1MgTGFtYmRhPC90aXRsZT4KICAgIDxkZWZzPgogICAgICAgIDxsaW5lYXJHcmFkaWVudCB4MT0iMCUiIHkxPSIxMDAlIiB4Mj0iMTAwJSIgeTI9IjAlIiBpZD0ibGluZWFyR3JhZGllbnQtMSI+CiAgICAgICAgICAgIDxzdG9wIHN0b3AtY29sb3I9IiNDODUxMUIiIG9mZnNldD0iMCUiPjwvc3RvcD4KICAgICAgICAgICAgPHN0b3Agc3RvcC1jb2xvcj0iI0ZGOTkwMCIgb2Zmc2V0PSIxMDAlIj48L3N0b3A+CiAgICAgICAgPC9saW5lYXJHcmFkaWVudD4KICAgIDwvZGVmcz4KICAgIDxnPgogICAgICAgIDxyZWN0IGZpbGw9InVybCgjbGluZWFyR3JhZGllbnQtMSkiIHg9IjAiIHk9IjAiIHdpZHRoPSIyNTYiIGhlaWdodD0iMjU2Ij48L3JlY3Q+CiAgICAgICAgPHBhdGggZD0iTTg5LjYyNDExMjYsMjExLjIgTDQ5Ljg5MDMyNzcsMjExLjIgTDkzLjgzNTQ4MzIsMTE5LjM0NzIgTDExMy43NDcyOCwxNjAuMzM5MiBMODkuNjI0MTEyNiwyMTEuMiBaIE05Ni43MDI5MzU3LDExMC41Njk2IEM5Ni4xNjQwODU4LDEwOS40NjU2IDk1LjA0MTQ4MTMsMTA4Ljc2NDggOTMuODE2MjM4NCwxMDguNzY0OCBMOTMuODA2NjE2MywxMDguNzY0OCBDOTIuNTcxNzUxNCwxMDguNzY4IDkxLjQ0OTE0NjYsMTA5LjQ3NTIgOTAuOTE5OTE4NywxMTAuNTg1NiBMNDEuOTEzNDIwOCwyMTMuMDIwOCBDNDEuNDM4NzE5NywyMTQuMDEyOCA0MS41MDYwNzU4LDIxNS4xNzc2IDQyLjA5NjI0NTEsMjE2LjEwODggQzQyLjY3OTk5OTQsMjE3LjAzNjggNDMuNzA2MzgwNSwyMTcuNiA0NC44MDY1MzMxLDIxNy42IEw5MS42NTQ0MjMsMjE3LjYgQzkyLjg5NTcwMjcsMjE3LjYgOTQuMDIxNTE0OSwyMTYuODg2NCA5NC41NTM5NTAxLDIxNS43Njk2IEwxMjAuMjAzODU5LDE2MS42ODk2IEMxMjAuNjE3NjE5LDE2MC44MTI4IDEyMC42MTQ0MTIsMTU5Ljc5ODQgMTIwLjE4NzgyMiwxNTguOTI4IEw5Ni43MDI5MzU3LDExMC41Njk2IFogTTIwNy45ODUxMTcsMjExLjIgTDE2OC41MDc5MjgsMjExLjIgTDEwNS4xNzM3ODksNzguNjI0IEMxMDQuNjQ0NTYxLDc3LjUxMDQgMTAzLjUxNTU0MSw3Ni44IDEwMi4yNzc0NjksNzYuOCBMNzYuNDQ3OTQzLDc2LjggTDc2LjQ3NjgwOTksNDQuOCBMMTI3LjEwMzA2Niw0NC44IEwxOTAuMTQ1MzI4LDE3Ny4zNzI4IEMxOTAuNjc0NTU2LDE3OC40ODY0IDE5MS44MDM1NzUsMTc5LjIgMTkzLjA0MTY0NywxNzkuMiBMMjA3Ljk4NTExNywxNzkuMiBMMjA3Ljk4NTExNywyMTEuMiBaIE0yMTEuMTkyNTU4LDE3Mi44IEwxOTUuMDcxOTU4LDE3Mi44IEwxMzIuMDI5Njk2LDQwLjIyNzIgQzEzMS41MDA0NjgsMzkuMTEzNiAxMzAuMzcxNDQ5LDM4LjQgMTI5LjEzMDE2OSwzOC40IEw3My4yNzI1NzYsMzguNCBDNzEuNTA1Mjc1OCwzOC40IDcwLjA2ODM0MjEsMzkuODMwNCA3MC4wNjUxMzQ0LDQxLjU5NjggTDcwLjAyOTg1MjgsNzkuOTk2OCBDNzAuMDI5ODUyOCw4MC44NDggNzAuMzYzNDI2Niw4MS42NjA4IDcwLjk2OTYzMyw4Mi4yNjI0IEM3MS41Njk0MjQ2LDgyLjg2NCA3Mi4zODQxMTQ2LDgzLjIgNzMuMjM3Mjk0MSw4My4yIEwxMDAuMjUzNTczLDgzLjIgTDE2My41OTA5MiwyMTUuNzc2IEMxNjQuMTIzMzU1LDIxNi44ODk2IDE2NS4yNDU5NiwyMTcuNiAxNjYuNDg0MDMyLDIxNy42IEwyMTEuMTkyNTU4LDIxNy42IEMyMTIuOTY2Mjc0LDIxNy42IDIxNC40LDIxNi4xNjY0IDIxNC40LDIxNC40IEwyMTQuNCwxNzYgQzIxNC40LDE3NC4yMzM2IDIxMi45NjYyNzQsMTcyLjggMjExLjE5MjU1OCwxNzIuOCBMMjExLjE5MjU1OCwxNzIuOCBaIiBmaWxsPSIjRkZGRkZGIj48L3BhdGg+CiAgICA8L2c+Cjwvc3ZnPg==",
-  "multiValueHeaders": {
-    "Content-Type": ["image/png"],
-    "Content-Encoding": ["gzip"]
+  "headers": {
+    "Content-Type": "image/png"
   },
   "isBase64Encoded": true,
   "statusCode": 200