feat(event-handler): add resolution logic to base router (#4349)

Co-authored-by: Andrea Amorosi <dreamorosi@gmail.com>

Author: svozza

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

@@ -3,7 +3,7 @@ import {
   getStringFromEnv,
   isDevMode,
 } from '@aws-lambda-powertools/commons/utils/env';
-import type { Context } from 'aws-lambda';
+import type { APIGatewayProxyResult, Context } from 'aws-lambda';
 import type { ResolveOptions } from '../types/index.js';
 import type {
   ErrorConstructor,
@@ -15,15 +15,22 @@ import type {
   RouteOptions,
   RouterOptions,
 } from '../types/rest.js';
-import { HttpVerbs } from './constants.js';
+import { HttpErrorCodes, HttpVerbs } from './constants.js';
+import {
+  handlerResultToProxyResult,
+  proxyEventToWebRequest,
+  responseToProxyResult,
+} from './converters.js';
 import { ErrorHandlerRegistry } from './ErrorHandlerRegistry.js';
 import {
+  InternalServerError,
   MethodNotAllowedError,
   NotFoundError,
   ServiceError,
 } from './errors.js';
 import { Route } from './Route.js';
 import { RouteHandlerRegistry } from './RouteHandlerRegistry.js';
+import { isAPIGatewayProxyEvent, isHttpMethod } from './utils.js';
 
 abstract class BaseRouter {
   protected context: Record<string, unknown>;
@@ -133,11 +140,72 @@ abstract class BaseRouter {
     };
   }
 
-  public abstract resolve(
+  /**
+   * Resolves an API Gateway event by routing it to the appropriate handler
+   * and converting the result to an API Gateway proxy result. Handles errors
+   * using registered error handlers or falls back to default error handling
+   * (500 Internal Server Error).
+   *
+   * @param event - The Lambda event to resolve
+   * @param context - The Lambda context
+   * @param options - Optional resolve options for scope binding
+   * @returns An API Gateway proxy result or undefined for incompatible events
+   */
+  public async resolve(
     event: unknown,
     context: Context,
     options?: ResolveOptions
-  ): Promise<unknown>;
+  ): Promise<APIGatewayProxyResult | undefined> {
+    if (!isAPIGatewayProxyEvent(event)) {
+      this.logger.error(
+        'Received an event that is not compatible with this resolver'
+      );
+      throw new InternalServerError();
+    }
+
+    const method = event.requestContext.httpMethod.toUpperCase();
+    if (!isHttpMethod(method)) {
+      this.logger.error(`HTTP method ${method} is not supported.`);
+      // We can't throw a MethodNotAllowedError outside the try block as it
+      // will be converted to an internal server error by the API Gateway runtime
+      return {
+        statusCode: HttpErrorCodes.METHOD_NOT_ALLOWED,
+        body: '',
+      };
+    }
+
+    const request = proxyEventToWebRequest(event);
+
+    try {
+      const path = new URL(request.url).pathname as Path;
+
+      const route = this.routeRegistry.resolve(method, path);
+
+      if (route === null) {
+        throw new NotFoundError(`Route ${path} for method ${method} not found`);
+      }
+
+      const result = await route.handler.apply(options?.scope ?? this, [
+        route.params,
+        {
+          event,
+          context,
+          request,
+        },
+      ]);
+
+      return await handlerResultToProxyResult(result);
+    } catch (error) {
+      this.logger.debug(`There was an error processing the request: ${error}`);
+      const result = await this.handleError(error as Error, {
+        request,
+        event,
+        context,
+        scope: options?.scope,
+      });
+      return await responseToProxyResult(result);
+    }
+  }
 
   public route(handler: RouteHandler, options: RouteOptions): void {
     const { method, path } = options;

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

@@ -1,5 +1,14 @@
-import type { APIGatewayProxyEvent } from 'aws-lambda';
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+import type { HandlerResponse } from '../types/rest.js';
+import { isAPIGatewayProxyResult } from './utils.js';
 
+/**
+ * Creates a request body from API Gateway event body, handling base64 decoding if needed.
+ *
+ * @param body - The raw body from the API Gateway event
+ * @param isBase64Encoded - Whether the body is base64 encoded
+ * @returns The decoded body string or null
+ */
 const createBody = (body: string | null, isBase64Encoded: boolean) => {
   if (body === null) return null;
 
@@ -9,21 +18,33 @@ const createBody = (body: string | null, isBase64Encoded: boolean) => {
   return Buffer.from(body, 'base64').toString('utf8');
 };
 
-export const proxyEventToWebRequest = (event: APIGatewayProxyEvent) => {
-  const { httpMethod, path, domainName } = event.requestContext;
+/**
+ * Converts an API Gateway proxy event to a Web API Request object.
+ *
+ * @param event - The API Gateway proxy event
+ * @returns A Web API Request object
+ */
+export const proxyEventToWebRequest = (
+  event: APIGatewayProxyEvent
+): Request => {
+  const { httpMethod, path } = event;
+  const { domainName } = event.requestContext;
 
   const headers = new Headers();
   for (const [name, value] of Object.entries(event.headers ?? {})) {
-    if (value != null) headers.append(name, value);
+    if (value != null) headers.set(name, value);
   }
 
   for (const [name, values] of Object.entries(event.multiValueHeaders ?? {})) {
     for (const value of values ?? []) {
-      headers.append(name, value);
+      const headerValue = headers.get(name);
+      if (!headerValue?.includes(value)) {
+        headers.append(name, value);
+      }
     }
   }
   const hostname = headers.get('Host') ?? domainName;
-  const protocol = headers.get('X-Forwarded-Proto') ?? 'http';
+  const protocol = headers.get('X-Forwarded-Proto') ?? 'https';
 
   const url = new URL(path, `${protocol}://${hostname}/`);
 
@@ -45,4 +66,58 @@ export const proxyEventToWebRequest = (event: APIGatewayProxyEvent) => {
     headers,
     body: createBody(event.body, event.isBase64Encoded),
   });
-}
+};
+
+/**
+ * Converts a Web API Response object to an API Gateway proxy result.
+ *
+ * @param response - The Web API Response object
+ * @returns An API Gateway proxy result
+ */
+export const responseToProxyResult = async (
+  response: Response
+): Promise<APIGatewayProxyResult> => {
+  const headers: Record<string, string> = {};
+  const multiValueHeaders: Record<string, Array<string>> = {};
+
+  for (const [key, value] of response.headers.entries()) {
+    const values = value.split(',').map((v) => v.trimStart());
+    if (values.length > 1) {
+      multiValueHeaders[key] = values;
+    } else {
+      headers[key] = value;
+    }
+  }
+
+  return {
+    statusCode: response.status,
+    headers,
+    multiValueHeaders,
+    body: await response.text(),
+    isBase64Encoded: false,
+  };
+};
+
+/**
+ * Converts a handler response to an API Gateway proxy result.
+ * Handles APIGatewayProxyResult, Response objects, and plain objects.
+ *
+ * @param response - The handler response (APIGatewayProxyResult, Response, or plain object)
+ * @returns An API Gateway proxy result
+ */
+export const handlerResultToProxyResult = async (
+  response: HandlerResponse
+): Promise<APIGatewayProxyResult> => {
+  if (isAPIGatewayProxyResult(response)) {
+    return response;
+  }
+  if (response instanceof Response) {
+    return await responseToProxyResult(response);
+  }
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response),
+    headers: { 'Content-Type': 'application/json' },
+    isBase64Encoded: false,
+  };
+};

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

@@ -1,7 +1,17 @@
 import { isRecord, isString } from '@aws-lambda-powertools/commons/typeutils';
-import type { APIGatewayProxyEvent } from 'aws-lambda';
-import type { CompiledRoute, Path, ValidationResult } from '../types/rest.js';
-import { PARAM_PATTERN, SAFE_CHARS, UNSAFE_CHARS } from './constants.js';
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+import type {
+  CompiledRoute,
+  HttpMethod,
+  Path,
+  ValidationResult,
+} from '../types/rest.js';
+import {
+  HttpVerbs,
+  PARAM_PATTERN,
+  SAFE_CHARS,
+  UNSAFE_CHARS,
+} from './constants.js';
 
 export function compilePath(path: Path): CompiledRoute {
   const paramNames: string[] = [];
@@ -68,3 +78,30 @@ export const isAPIGatewayProxyEvent = (
     (event.body === null || isString(event.body))
   );
 };
+
+export const isHttpMethod = (method: string): method is HttpMethod => {
+  return Object.keys(HttpVerbs).includes(method);
+};
+
+/**
+ * Type guard to check if the provided result is an API Gateway Proxy result.
+ *
+ * We use this function to ensure that the result is an object and has the
+ * required properties without adding a dependency.
+ *
+ * @param result - The result to check
+ */
+export const isAPIGatewayProxyResult = (
+  result: unknown
+): result is APIGatewayProxyResult => {
+  if (!isRecord(result)) return false;
+  return (
+    typeof result.statusCode === 'number' &&
+    isString(result.body) &&
+    (result.headers === undefined || isRecord(result.headers)) &&
+    (result.multiValueHeaders === undefined ||
+      isRecord(result.multiValueHeaders)) &&
+    (result.isBase64Encoded === undefined ||
+      typeof result.isBase64Encoded === 'boolean')
+  );
+};

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

@@ -24,7 +24,7 @@ type ErrorResolveOptions = RequestOptions & ResolveOptions;
 
 type ErrorHandler<T extends Error = Error> = (
   error: T,
-  options?: RequestOptions
+  options: RequestOptions
 ) => Promise<ErrorResponse>;
 
 interface ErrorConstructor<T extends Error = Error> {
@@ -53,10 +53,12 @@ interface CompiledRoute {
 
 type DynamicRoute = Route & CompiledRoute;
 
+type HandlerResponse = Response | JSONObject;
+
 type RouteHandler<
   TParams = Record<string, unknown>,
-  TReturn = Response | JSONObject,
-> = (args: TParams, options?: RequestOptions) => Promise<TReturn>;
+  TReturn = HandlerResponse,
+> = (args: TParams, options: RequestOptions) => Promise<TReturn>;
 
 type HttpMethod = keyof typeof HttpVerbs;
 
@@ -106,6 +108,7 @@ export type {
   ErrorHandlerRegistryOptions,
   ErrorHandler,
   ErrorResolveOptions,
+  HandlerResponse,
   HttpStatusCode,
   HttpMethod,
   Path,