feat(event-handler): add first-class support for binary responses

Author: svozza

packages/event-handler/src/rest/Router.ts

@@ -48,9 +48,12 @@ import { Route } from './Route.js';
 import { RouteHandlerRegistry } from './RouteHandlerRegistry.js';
 import {
   composeMiddleware,
+  getBase64EncodingFromHeaders,
+  getBase64EncodingFromResult,
   HttpResponseStream,
   isAPIGatewayProxyEventV1,
   isAPIGatewayProxyEventV2,
+  isBinaryResult,
   isExtendedAPIGatewayProxyResult,
   resolvePrefixedPath,
 } from './utils.js';
@@ -260,29 +263,27 @@ class Router {
       const route = this.routeRegistry.resolve(method, path);
 
       const handlerMiddleware: Middleware = async ({ reqCtx, next }) => {
+        let handlerRes: HandlerResponse;
         if (route === null) {
-          const notFoundRes = await this.handleError(
+          handlerRes = await this.handleError(
             new NotFoundError(`Route ${path} for method ${method} not found`),
             { ...reqCtx, scope: options?.scope }
           );
-          reqCtx.res = handlerResultToWebResponse(
-            notFoundRes,
-            reqCtx.res.headers
-          );
         } else {
           const handler =
             options?.scope == null
               ? route.handler
               : route.handler.bind(options.scope);
 
-          const handlerResult = await handler(reqCtx);
+          handlerRes = await handler(reqCtx);
+        }
 
-          reqCtx.res = handlerResultToWebResponse(
-            handlerResult,
-            reqCtx.res.headers
-          );
+        if (getBase64EncodingFromResult(handlerRes)) {
+          reqCtx.isBase64Encoded = true;
         }
 
+        reqCtx.res = handlerResultToWebResponse(handlerRes, reqCtx.res.headers);
+
         await next();
       };
 
@@ -313,10 +314,16 @@ class Router {
         ...requestContext,
         scope: options?.scope,
       });
+
+      if (getBase64EncodingFromResult(res)) {
+        requestContext.isBase64Encoded = true;
+      }
+
       requestContext.res = handlerResultToWebResponse(
         res,
         requestContext.res.headers
       );
+
       return requestContext;
     }
   }
@@ -353,7 +360,12 @@ class Router {
     options?: ResolveOptions
   ): Promise<APIGatewayProxyResult | APIGatewayProxyStructuredResultV2> {
     const reqCtx = await this.#resolve(event, context, options);
-    return webResponseToProxyResult(reqCtx.res, reqCtx.responseType);
+    const isBase64Encoded =
+      reqCtx.isBase64Encoded ??
+      getBase64EncodingFromHeaders(reqCtx.res.headers);
+    return webResponseToProxyResult(reqCtx.res, reqCtx.responseType, {
+      isBase64Encoded,
+    });
   }
 
   /**
@@ -434,7 +446,11 @@ class Router {
       try {
         const { scope, ...reqCtx } = options;
         const body = await handler.apply(scope ?? this, [error, reqCtx]);
-        if (body instanceof Response || isExtendedAPIGatewayProxyResult(body)) {
+        if (
+          body instanceof Response ||
+          isExtendedAPIGatewayProxyResult(body) ||
+          isBinaryResult(body)
+        ) {
           return body;
         }
         if (!body.statusCode) {

packages/event-handler/src/rest/converters.ts

@@ -7,18 +7,18 @@ import type {
   APIGatewayProxyStructuredResultV2,
 } from 'aws-lambda';
 import type {
-  CompressionOptions,
   ExtendedAPIGatewayProxyResult,
   ExtendedAPIGatewayProxyResultBody,
   HandlerResponse,
   ResponseType,
   ResponseTypeMap,
   V1Headers,
+  WebResponseToProxyResultOptions,
 } from '../types/rest.js';
-import { COMPRESSION_ENCODING_TYPES } from './constants.js';
 import { InvalidHttpMethodError } from './errors.js';
 import {
   isAPIGatewayProxyEventV2,
+  isBinaryResult,
   isExtendedAPIGatewayProxyResult,
   isHttpMethod,
   isNodeReadableStream,
@@ -213,41 +213,29 @@ const webHeadersToApiGatewayHeaders = <T extends ResponseType>(
     : { headers: Record<string, string> };
 };
 
+const responseBodyToBase64 = async (response: Response) => {
+  const buffer = await response.arrayBuffer();
+  return Buffer.from(buffer).toString('base64');
+};
+
 /**
  * Converts a Web API Response object to an API Gateway V1 proxy result.
  *
  * @param response - The Web API Response object
+ * @param isBase64Encoded - Whether the response body should be base64 encoded (e.g., for binary or compressed content)
  * @returns An API Gateway V1 proxy result
  */
 const webResponseToProxyResultV1 = async (
-  response: Response
+  response: Response,
+  isBase64Encoded?: boolean
 ): Promise<APIGatewayProxyResult> => {
   const { headers, multiValueHeaders } = webHeadersToApiGatewayV1Headers(
     response.headers
   );
 
-  // Check if response contains compressed/binary content
-  const contentEncoding = response.headers.get(
-    'content-encoding'
-  ) as CompressionOptions['encoding'];
-  let body: string;
-  let isBase64Encoded = false;
-
-  if (
-    contentEncoding &&
-    [
-      COMPRESSION_ENCODING_TYPES.GZIP,
-      COMPRESSION_ENCODING_TYPES.DEFLATE,
-    ].includes(contentEncoding)
-  ) {
-    // For compressed content, get as buffer and encode to base64
-    const buffer = await response.arrayBuffer();
-    body = Buffer.from(buffer).toString('base64');
-    isBase64Encoded = true;
-  } else {
-    // For text content, use text()
-    body = await response.text();
-  }
+  const body = isBase64Encoded
+    ? await responseBodyToBase64(response)
+    : await response.text();
 
   const result: APIGatewayProxyResult = {
     statusCode: response.status,
@@ -267,10 +255,12 @@ const webResponseToProxyResultV1 = async (
  * Converts a Web API Response object to an API Gateway V2 proxy result.
  *
  * @param response - The Web API Response object
+ * @param isBase64Encoded - Whether the response body should be base64 encoded (e.g., for binary or compressed content)
  * @returns An API Gateway V2 proxy result
  */
 const webResponseToProxyResultV2 = async (
-  response: Response
+  response: Response,
+  isBase64Encoded?: boolean
 ): Promise<APIGatewayProxyStructuredResultV2> => {
   const headers: Record<string, string> = {};
   const cookies: string[] = [];
@@ -283,25 +273,9 @@ const webResponseToProxyResultV2 = async (
     }
   }
 
-  const contentEncoding = response.headers.get(
-    'content-encoding'
-  ) as CompressionOptions['encoding'];
-  let body: string;
-  let isBase64Encoded = false;
-
-  if (
-    contentEncoding &&
-    [
-      COMPRESSION_ENCODING_TYPES.GZIP,
-      COMPRESSION_ENCODING_TYPES.DEFLATE,
-    ].includes(contentEncoding)
-  ) {
-    const buffer = await response.arrayBuffer();
-    body = Buffer.from(buffer).toString('base64');
-    isBase64Encoded = true;
-  } else {
-    body = await response.text();
-  }
+  const body = isBase64Encoded
+    ? await responseBodyToBase64(response)
+    : await response.text();
 
   const result: APIGatewayProxyStructuredResultV2 = {
     statusCode: response.status,
@@ -319,12 +293,18 @@ const webResponseToProxyResultV2 = async (
 
 const webResponseToProxyResult = <T extends ResponseType>(
   response: Response,
-  responseType: T
+  responseType: T,
+  options?: WebResponseToProxyResultOptions
 ): Promise<ResponseTypeMap[T]> => {
+  const isBase64Encoded = options?.isBase64Encoded ?? false;
   if (responseType === 'ApiGatewayV1') {
-    return webResponseToProxyResultV1(response) as Promise<ResponseTypeMap[T]>;
+    return webResponseToProxyResultV1(response, isBase64Encoded) as Promise<
+      ResponseTypeMap[T]
+    >;
   }
-  return webResponseToProxyResultV2(response) as Promise<ResponseTypeMap[T]>;
+  return webResponseToProxyResultV2(response, isBase64Encoded) as Promise<
+    ResponseTypeMap[T]
+  >;
 };
 
 /**
@@ -385,6 +365,19 @@ const handlerResultToWebResponse = (
   }
 
   const headers = new Headers(resHeaders);
+
+  if (isBinaryResult(response)) {
+    const body =
+      response instanceof Readable
+        ? (Readable.toWeb(response) as ReadableStream)
+        : response;
+
+    return new Response(body, {
+      status: 200,
+      headers,
+    });
+  }
+
   headers.set('Content-Type', 'application/json');
 
   if (isExtendedAPIGatewayProxyResult(response)) {

packages/event-handler/src/rest/utils.ts

@@ -7,6 +7,7 @@ import {
 import type { APIGatewayProxyEvent, APIGatewayProxyEventV2 } from 'aws-lambda';
 import type {
   CompiledRoute,
+  CompressionOptions,
   ExtendedAPIGatewayProxyResult,
   HandlerResponse,
   HttpMethod,
@@ -16,6 +17,7 @@ import type {
   ValidationResult,
 } from '../types/rest.js';
 import {
+  COMPRESSION_ENCODING_TYPES,
   HttpVerbs,
   PARAM_PATTERN,
   SAFE_CHARS,
@@ -156,6 +158,16 @@ export const isWebReadableStream = (
   );
 };
 
+export const isBinaryResult = (
+  value: unknown
+): value is ArrayBuffer | Readable | ReadableStream => {
+  return (
+    value instanceof ArrayBuffer ||
+    isNodeReadableStream(value) ||
+    isWebReadableStream(value)
+  );
+};
+
 /**
  * Type guard to check if the provided result is an API Gateway Proxy result.
  *
@@ -318,3 +330,47 @@ export const HttpResponseStream =
       return underlyingStream;
     }
   };
+
+export const getBase64EncodingFromResult = (result: HandlerResponse) => {
+  if (isBinaryResult(result)) {
+    return true;
+  }
+  if (isExtendedAPIGatewayProxyResult(result)) {
+    return (
+      result.body instanceof ArrayBuffer ||
+      isNodeReadableStream(result.body) ||
+      isWebReadableStream(result.body)
+    );
+  }
+  return false;
+};
+
+export const getBase64EncodingFromHeaders = (headers: Headers): boolean => {
+  const contentEncoding = headers.get(
+    'content-encoding'
+  ) as CompressionOptions['encoding'];
+
+  if (
+    contentEncoding != null &&
+    [
+      COMPRESSION_ENCODING_TYPES.GZIP,
+      COMPRESSION_ENCODING_TYPES.DEFLATE,
+    ].includes(contentEncoding)
+  ) {
+    return true;
+  }
+
+  const contentType = headers.get('content-type');
+  if (contentType != null) {
+    const type = contentType.split(';')[0].trim();
+    if (
+      type.startsWith('image/') ||
+      type.startsWith('audio/') ||
+      type.startsWith('video/')
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+};

packages/event-handler/src/types/rest.ts

@@ -29,6 +29,7 @@ type RequestContext = {
   res: Response;
   params: Record<string, string>;
   responseType: ResponseType;
+  isBase64Encoded?: boolean;
 };
 
 type ErrorResolveOptions = RequestContext & ResolveOptions;
@@ -69,14 +70,20 @@ interface CompiledRoute {
 
 type DynamicRoute = Route & CompiledRoute;
 
-type ExtendedAPIGatewayProxyResultBody = string | Readable | ReadableStream;
+type BinaryResult = ArrayBuffer | Readable | ReadableStream;
+
+type ExtendedAPIGatewayProxyResultBody = BinaryResult | string;
 
 type ExtendedAPIGatewayProxyResult = Omit<APIGatewayProxyResult, 'body'> & {
   body: ExtendedAPIGatewayProxyResultBody;
   cookies?: string[];
 };
 
-type HandlerResponse = Response | JSONObject | ExtendedAPIGatewayProxyResult;
+type HandlerResponse =
+  | Response
+  | JSONObject
+  | ExtendedAPIGatewayProxyResult
+  | BinaryResult;
 
 type RouteHandler<TReturn = HandlerResponse> = (
   reqCtx: RequestContext
@@ -230,7 +237,12 @@ type CompressionOptions = {
   threshold?: number;
 };
 
+type WebResponseToProxyResultOptions = {
+  isBase64Encoded?: boolean;
+};
+
 export type {
+  BinaryResult,
   ExtendedAPIGatewayProxyResult,
   ExtendedAPIGatewayProxyResultBody,
   CompiledRoute,
@@ -259,4 +271,5 @@ export type {
   CompressionOptions,
   NextFunction,
   V1Headers,
+  WebResponseToProxyResultOptions,
 };