Feature request: Implement Middleware for REST Event Handler

[svozza]

Use case

The REST API event handler should provide a way to apply middleware to requests both globally and at route level. The order in which middleware are passed to the event handler are the order in which they will be applied. Users will also be able to return early from from middleware and any errors thrown will be caught and handled in the same manner as errors from handlers.

Solution/User Experience

Global middleware

Middleware that should apply to all routes would be register as so:

app.use(async ({req, res, context, event}}, next) => {
  // this will run before the handler executes
  console.log(`Http method is: ${req.method}`);
  // this will ensure the next middleware in the chain is executed
  await next();
  // this will execute after the handler executes
  res.headers.set('X-post-req-header', 'some-value')
});

Route specific middleware

Route specific middleware can be specified when registering a router:

const middleware1(async ({req, res, context, event}}, next) => {
  // ....
});

const middleware2(async ({req, res, context, event}}, next) => {
  // ....
});

app.get('/standard', [middleware1, middleware2], () => {
  return new Response(JSON.stringify({message: 'OK'}), {
    status: 200,
    headers: {'Content-Type': 'application/json'}
  });
});

Early returns

Users can also return early from middleware. This will prevent the execution of any other middleware further down the chain:

app.use(async ({req, res, context, event}}, next) => {
  if(someCondition) {
    res.header.set('X-return-early', 'some-value');
    return res; // you may also return a JSON object or an APIGatewayProxyResult
  }
  // this will ensure the next middleware in the chain is executed
  await next();
});

Errors

Errors thrown in middleware will stop processing and result in the thrown error being handled in the same manner as errors from handlers.

app.use(async ({req, res, context, event}}, next) => {
  if(someCondition) {
    throw new BadRequestError();
  }
  await next();
});

Alternative solutions

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[dcabib]

Nice feature request! The middleware API you've designed looks really thoughtful - I love how it balances familiar patterns with Lambda-specific needs. The examples you provided make the use cases crystal clear.

Building on Your Design

The API signatures you've outlined work really well. A few thoughts on the specific patterns you mentioned:

Global Middleware Flow

Your global middleware example with the pre/post execution pattern is perfect:

app.use(async ({req, res, context, event}, next) => {
  // Before handler - your logging example
  console.log(`Http method is: ${req.method}`);
  await next();
  // After handler - your header setting example  
  res.headers.set('X-post-req-header', 'some-value');
});

This pre/post pattern will be incredibly useful for things like request timing, correlation IDs, and response transformations.

Route-Specific Array Syntax

The array syntax you showed for route-specific middleware is intuitive:

app.get('/standard', [middleware1, middleware2], handler);

This makes the middleware execution order explicit and reads naturally. I'm wondering about the internal execution - will this create a single merged chain where global middleware runs first, then route-specific middleware in array order?

Early Returns & Response Types

Your early return flexibility is really smart - supporting res, JSON objects, or APIGatewayProxyResult covers all the common use cases:

// Your example with different return types
if(someCondition) {
  res.header.set('X-return-early', 'some-value');
  return res; // or JSON object or APIGatewayProxyResult
}

This flexibility will make migration from existing patterns much easier.

Error Handling Strategy

Your error handling approach makes sense - treating middleware errors the same as handler errors:

// Your BadRequestError example
app.use(async ({req, res, context, event}, next) => {
  if(someCondition) {
    throw new BadRequestError();
  }
  await next();
});

This consistency will make debugging much more predictable. Will the error handling support async errors that might occur after await next() returns?

Implementation Considerations

Looking at your examples, I'm thinking about:

Execution Chain: Since you mentioned order matters, the internal chain would need to merge global + route-specific middleware while preserving the ordering you specified.

Context Object: The {req, res, context, event} destructuring pattern you showed is really clean - it makes all the Lambda context available without complex nesting.

Return Type Flexibility: Supporting multiple return types (res/JSON/APIGatewayProxyResult) as you outlined will require some smart type inference to keep it type-safe.

Testing Strategy Ideas

Middleware can get complex quickly, especially with early returns and error scenarios. Some testing patterns that might be valuable:

1. Middleware isolation tests: Each middleware in isolation
2. Chain execution tests: Full middleware pipeline execution
3. Error propagation tests: Ensuring errors bubble up correctly
4. Performance benchmarks: Overhead vs. native handler execution

Powerful Use Cases This Enables

Your middleware design opens up some really compelling patterns:

Authentication/Authorization:

// Following your early return pattern
app.use(async ({req, res}, next) => {
  if (!req.headers.authorization) {
    return { statusCode: 401, body: 'Unauthorized' }; // Your JSON return option
  }
  await next();
});

Request/Response Transformation:

// Using your pre/post execution model
app.use(async ({req, res}, next) => {
  req.startTime = Date.now(); // Before
  await next();
  res.headers.set('X-Duration', `${Date.now() - req.startTime}ms`); // After
});

Route-Specific Validation:

// Your array syntax with validation
app.post('/users', [validateUserSchema, checkPermissions], createUser);

Questions on Your Design

1. Middleware Ordering: When combining global and route-specific middleware, will it be [...global, ...routeSpecific, handler]?

2. Context Mutation: Can middleware modify the {req, res, context, event} objects for downstream middleware?

3. Error Context: When middleware throws (like your BadRequestError example), will the error have context about which middleware failed?

4. Performance: Have you considered middleware compilation during cold starts to optimize the execution chain?

Cross-Language Learning Opportunity

Interesting note - I checked Python Powertools and they already have a robust middleware system! Their approach uses similar patterns with app.use() for global middleware and supports both function-based and class-based middleware. This could be a great opportunity for TypeScript to learn from their implementation and maybe even improve on it.

The Python version supports:

• Pre/post request processing (like your design)
• Early returns and exception handling
• Context sharing between middleware
• BaseMiddlewareHandler for complex middleware

This middleware feature could actually position TypeScript ahead of other Powertools languages in terms of developer experience, especially with the type safety advantages you're building in.

I'd Love to Help

The middleware patterns you've outlined will be game-changing for the Event Handler utility! Since you're leading this implementation, I'd be happy to contribute in any way that's helpful:

• Execution chain logic: Implementing the middleware ordering and next() function mechanics you described
• Type safety: Ensuring the {req, res, context, event} destructuring and return type flexibility work perfectly with TypeScript
• Built-in middleware: Common patterns that leverage your early return and error handling designs
• Testing scenarios: Covering all the execution paths (global, route-specific, early returns, errors)
• Performance validation: Making sure the middleware overhead is minimal in Lambda environments