refactor(event-handler): use null for unmatched route instead of raw path

Author: svozza

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

@@ -259,7 +259,7 @@ class Router<TEnv extends Env = Env> {
       context,
       req: options.req,
       res: options.res,
-      route: '',
+      route: null as string | null,
       params: {} as Record<string, string>,
       isHttpStreaming: options.isHttpStreaming,
       set: options.set,
@@ -346,7 +346,9 @@ class Router<TEnv extends Env = Env> {
 
       const route = this.routeRegistry.resolve(method, path);
 
-      requestContext.route = route?.route ?? `${method} ${path}`;
+      if (route !== null) {
+        requestContext.route = route.route;
+      }
 
       const handlerMiddleware: Middleware = async ({ reqCtx, next }) => {
         let handlerRes: HandlerResponse;

packages/event-handler/src/http/middleware/metrics.ts

@@ -54,7 +54,7 @@ const getEventMetadata = (reqCtx: RequestContext): Record<string, string> => {
  * A middleware for emitting per-request metrics using Powertools Metrics.
  *
  * This middleware automatically:
- * - Adds the matched route as a metric dimension (uses `NOT_FOUND` for 404 responses to prevent dimension explosion)
+ * - Adds the matched route as a metric dimension (uses `NOT_FOUND` when no route matches to prevent dimension explosion)
  * - Emits `latency` (Milliseconds), `fault` (Count), and `error` (Count) metrics
  * - Adds `httpMethod` and `path` metadata for all requests
  * - Adds `ipAddress` and `userAgent` metadata from request headers when available
@@ -89,7 +89,6 @@ const metrics = (metrics: Metrics): Middleware => {
       throw error;
     } finally {
       const url = new URL(reqCtx.req.url);
-      const is404 = status === 404;
       const metadata = {
         httpMethod: reqCtx.req.method,
         path: url.pathname,
@@ -101,7 +100,7 @@ const metrics = (metrics: Metrics): Middleware => {
         metrics.addMetadata(key, value);
       }
       metrics
-        .addDimension('route', is404 ? 'NOT_FOUND' : reqCtx.route)
+        .addDimension('route', reqCtx.route ?? 'NOT_FOUND')
         .addMetric(
           'latency',
           MetricUnit.Milliseconds,

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

@@ -170,7 +170,7 @@ type RequestContext<TEnv extends Env = Env> = {
     event: EventTypeMap[T];
     context: Context;
     res: Response;
-    route: string;
+    route: string | null;
     params: Record<string, string>;
     responseType: T;
     isBase64Encoded?: boolean;

packages/event-handler/tests/unit/http/Router/basic-routing.test.ts

@@ -567,7 +567,7 @@ describe.each([
   it('sets reqCtx.route to METHOD and path for static routes', async () => {
     // Prepare
     const app = new Router();
-    let capturedRoute = '';
+    let capturedRoute: string | null = null;
     app.use(async ({ reqCtx, next }) => {
       await next();
       capturedRoute = reqCtx.route;
@@ -584,7 +584,7 @@ describe.each([
   it('sets reqCtx.route to METHOD and pattern for dynamic routes', async () => {
     // Prepare
     const app = new Router();
-    let capturedRoute = '';
+    let capturedRoute: string | null = null;
     app.use(async ({ reqCtx, next }) => {
       await next();
       capturedRoute = reqCtx.route;
@@ -598,10 +598,10 @@ describe.each([
     expect(capturedRoute).toBe('GET /users/:id');
   });
 
-  it('sets reqCtx.route to METHOD and requested path for unmatched routes', async () => {
+  it('sets reqCtx.route to null for unmatched routes', async () => {
     // Prepare
     const app = new Router();
-    let capturedRoute = '';
+    let capturedRoute: string | null = '';
     app.use(async ({ reqCtx, next }) => {
       await next();
       capturedRoute = reqCtx.route;
@@ -612,6 +612,6 @@ describe.each([
     await app.resolve(createEvent('/nonexistent', 'GET'), context);
 
     // Assess
-    expect(capturedRoute).toBe('GET /nonexistent');
+    expect(capturedRoute).toBeNull();
   });
 });

packages/event-handler/tests/unit/http/middleware/metrics.test.ts

@@ -1,7 +1,7 @@
 import { Metrics } from '@aws-lambda-powertools/metrics';
 import context from '@aws-lambda-powertools/testing-utils/context';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { BadRequestError } from '../../../../src/http/errors.js';
+import { BadRequestError, NotFoundError } from '../../../../src/http/errors.js';
 import { metrics as metricsMiddleware } from '../../../../src/http/middleware/metrics.js';
 import { Router } from '../../../../src/http/Router.js';
 import {
@@ -159,7 +159,7 @@ describe('Metrics Middleware', () => {
     );
   });
 
-  it('uses NOT_FOUND as route dimension for 404 responses', async () => {
+  it('uses NOT_FOUND as route dimension when no route matches', async () => {
     // Prepare
     const metrics = new Metrics({ namespace: 'test' });
     app.use(metricsMiddleware(metrics));
@@ -179,6 +179,27 @@ describe('Metrics Middleware', () => {
     );
   });
 
+  it('uses the matched route pattern when a handler returns 404', async () => {
+    // Prepare
+    const metrics = new Metrics({ namespace: 'test' });
+    app.use(metricsMiddleware(metrics));
+    app.get('/users/:id', () => {
+      throw new NotFoundError('User not found');
+    });
+
+    // Act
+    await app.resolve(createTestEvent('/users/123', 'GET'), context);
+
+    // Assess
+    expect(console.log).toHaveEmittedEMFWith(
+      expect.objectContaining({
+        route: 'GET /users/:id',
+        statusCode: '404',
+        error: 1,
+      })
+    );
+  });
+
   it('adds ipAddress from identity.sourceIp for API Gateway V1 events', async () => {
     // Prepare
     const metrics = new Metrics({ namespace: 'test' });