add custom middleware section

Author: svozza

docs/features/event-handler/rest.md

@@ -397,6 +397,36 @@ middleware. Event handler provides many [built-in HTTP errors](#throwing-http-er
 you can use or you can throw a custom error of your own. As noted above, this means
 that no post-processing of your request will occur.
 
+#### Custom middleware
+
+A common pattern to create reusable middleware is to implement a factory functions that
+accepts configuration options and returns a middleware function.
+
+=== "index.ts"
+
+    ```ts hl_lines="8-30 35 38"
+    --8<-- "examples/snippets/event-handler/rest/advanced_mw_custom_middleware.ts:3"
+    ```
+
+In this example we have a middleware that acts only in the post-processing stage as all
+the logic occurs after the `next` function has been called. This is so as to ensure that
+the handler has run and we have access to request body.
+
+#### Avoiding destructuring pitfalls
+
+!!! warning "Critical: Never destructure the response object"
+    When writing middleware, always access the response through `reqCtx.res` rather than destructuring `{ res }` from the request context. Destructuring captures a reference to the original response object, which becomes stale when middleware replaces the response.
+
+=== "index.ts"
+
+    ```ts hl_lines="8 15"
+    --8<-- "examples/snippets/event-handler/rest/advanced_mw_destructuring_problem.ts:3"
+    ```
+
+During the middleware execution chain, the response object (`reqCtx.res`) can be replaced by
+other middleware or the route handler. When you destructure the request context, you capture
+a reference to the response object as it existed at that moment, not the current response.
+
 ### Fine grained responses
 
 You can use the Web API's `Response` object to have full control over the response. For

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

@@ -0,0 +1,48 @@
+declare const compresssBody: (body: string) => Promise<string>;
+
+import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
+import type { Middleware } from '@aws-lambda-powertools/event-handler/types';
+import type { Context } from 'aws-lambda';
+
+interface CompressOptions {
+  threshold?: number;
+  level?: number;
+}
+
+// Factory function that returns middleware
+const compress = (options: CompressOptions = {}): Middleware => {
+  return async (params, reqCtx, next) => {
+    await next();
+
+    // Check if response should be compressed
+    const body = await reqCtx.res.text();
+    const threshold = options.threshold || 1024;
+
+    if (body.length > threshold) {
+      const compressedBody = await compresssBody(body);
+      const compressedRes = new Response(compressedBody, reqCtx.res);
+      compressedRes.headers.set('Content-Encoding', 'gzip');
+      reqCtx.res = compressedRes;
+    }
+  };
+};
+
+const app = new Router();
+
+// Use custom middleware globally
+app.use(compress({ threshold: 500 }));
+
+app.get('/data', async () => {
+  return {
+    message: 'Large response data',
+    data: new Array(100).fill('content'),
+  };
+});
+
+app.get('/small', async () => {
+  return { message: 'Small response' };
+});
+
+export const handler = async (event: unknown, context: Context) => {
+  return await app.resolve(event, context);
+};

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

@@ -0,0 +1,31 @@
+import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
+import type { Middleware } from '@aws-lambda-powertools/event-handler/types';
+import type { Context } from 'aws-lambda';
+
+const app = new Router();
+
+// ❌ WRONG: Using destructuring captures a reference to the original response
+const badMiddleware: Middleware = async (params, { res }, next) => {
+  res.headers.set('X-Before', 'Before');
+  await next();
+  // This header will NOT be added because 'res' is a stale reference
+  res.headers.set('X-After', 'After');
+};
+
+// ✅ CORRECT: Always access response through reqCtx
+const goodMiddleware: Middleware = async (params, reqCtx, next) => {
+  reqCtx.res.headers.set('X-Before', 'Before');
+  await next();
+  // This header WILL be added because we get the current response
+  reqCtx.res.headers.set('X-After', 'After');
+};
+
+app.use(goodMiddleware);
+
+app.get('/test', async () => {
+  return { message: 'Hello World!' };
+});
+
+export const handler = async (event: unknown, context: Context) => {
+  return await app.resolve(event, context);
+};