AWS powertools documentation change
Summary
Added comprehensive documentation for request/response validation using Standard Schema, store API (request/shared/typed stores), split routers, and updated middleware capabilities. Removed 'coming soon' sections and replaced with implemented features.
Security assessment
The changes are feature enhancements and documentation updates for validation, data stores, and router capabilities. While validation can improve input sanitization and data integrity, there's no evidence of addressing a specific security vulnerability or weakness. The changes are routine documentation updates for new features.
Diff
diff --git a/powertools/typescript/latest/features/event-handler/http.md b/powertools/typescript/latest/features/event-handler/http.md index dcd74b3b3..6dce829cb 100644 --- a//powertools/typescript/latest/features/event-handler/http.md +++ b//powertools/typescript/latest/features/event-handler/http.md @@ -57,0 +58,2 @@ Event Handler + * Validating requests + * Validating responses @@ -92,0 +95,5 @@ Event Handler + * Store + * Request store + * Shared store + * Typed stores + * Typed stores with split routers @@ -106,0 +114 @@ Event Handler + * [ Metadata ](../../metadata/) @@ -140,0 +149,2 @@ Table of contents + * Validating requests + * Validating responses @@ -175,0 +186,5 @@ Table of contents + * Store + * Request store + * Shared store + * Typed stores + * Typed stores with split routers @@ -190 +205 @@ Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Bala - * Built-in middleware engine for request/response transformation (validation coming soon). + * Built-in middleware engine for request/response transformation and validation. @@ -605,0 +621,98 @@ The event handler automatically ensures the correct response format is returned +If you need to control the status code or headers alongside auto-serialization, return an object with `statusCode` and `headers` fields. The `body` field accepts any JSON-serializable value — object or array — and is automatically serialized. Omitting `body` produces an empty response body, which is useful for responses like `204 No Content`. + +index.tsResponse + + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + 22 + 23 + 24 + 25 + +| + + + import { Router } from '@aws-lambda-powertools/event-handler/http'; + import type { Context } from 'aws-lambda'; + + const app = new Router(); + + app.post('/todos', () => ({ + statusCode: 201, // (1)! + headers: { 'x-todo-id': '123' }, // (2)! + body: { id: '123', title: 'Buy milk' }, // (3)! + })); + + app.get('/todos', () => ({ + statusCode: 200, + body: [ + { id: '1', title: 'Buy milk' }, + { id: '2', title: 'Take out trash' }, + ], // (4)! + })); + + app.delete('/todos/:id', () => ({ + statusCode: 204, // (5)! + })); + + export const handler = async (event: unknown, context: Context) => + app.resolve(event, context); + + +---|--- + + 1. Set a custom status code alongside JSON auto-serialization + 2. Set custom response headers + 3. Object body is automatically serialized to JSON + 4. Array body is automatically serialized to JSON + 5. Omitting `body` produces an empty response body + + + + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + +| + + + { + "statusCode": 201, + "headers": { + "Content-Type": "application/json", + "x-todo-id": "123" + }, + "body": "{\"id\":\"123\",\"title\":\"Buy milk\"}", + "isBase64Encoded": false + } + + +---|--- + @@ -1058,9 +1171 @@ We recommend passing a reference to `this` to ensure the correct class scope is -Coming soon - -We plan to add built-in support for request and response validation using [Standard Schema](https://standardschema.dev) in a future release. For the time being, you can use any validation library of your choice in your route handlers or middleware. - -Please [check this issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/4516) for more details and examples, and add 👍 if you would like us to prioritize it. - -### Accessing request details¶ - -You can access request details such as headers, query parameters, and body using the `Request` object provided to your route handlers and middleware functions via `reqCtx.req`. +Event Handler supports built-in request and response validation using [Standard Schema](https://standardschema.dev), a common specification supported by popular TypeScript validation libraries including [Zod](https://zod.dev), [Valibot](https://valibot.dev), and [ArkType](https://arktype.io). @@ -1068 +1173 @@ You can access request details such as headers, query parameters, and body using -### Error handling¶ +Body validation is limited to JSON-serializable values @@ -1070 +1175 @@ You can access request details such as headers, query parameters, and body using -You can use the `errorHandler()` method as a higher-order function or class method decorator to define a custom error handler for errors thrown in your route handlers or middleware. +Standard Schema validators operate on JavaScript values, not raw bytes. For body validation, Event Handler deserializes the body before passing it to your schema: `application/json` content is parsed as an object, all other content types are passed as a plain string. Binary data, streams, and other non-serializable response types cannot be validated. @@ -1072 +1177 @@ You can use the `errorHandler()` method as a higher-order function or class meth -This allows you to catch and return custom error responses, or perform any other error handling logic you need. +#### Validating requests¶ @@ -1074 +1179 @@ This allows you to catch and return custom error responses, or perform any other -Error handlers receive the error object and the request context as arguments, and can return a `Response` object or a JavaScript object that will be auto-serialized as per the response auto-serialization section. +Pass a `validation` option to your route handler with a `req` configuration to validate the incoming request. Validation runs before your handler, and if it fails, Event Handler automatically returns a **422 Unprocessable Entity** response with structured error details. @@ -1076 +1181 @@ Error handlers receive the error object and the request context as arguments, an -You can also pass a list of error classes to the `errorHandler()` method. +Validated data is available via `reqCtx.valid.req` and is fully typed based on your schema. Only the fields you provide schemas for are accessible: accessing an unvalidated field (e.g., `reqCtx.valid.req.headers` when no headers schema was configured) is a compile-time error. @@ -1078 +1183 @@ You can also pass a list of error classes to the `errorHandler()` method. -index.tsUsing decorators +index.tsRequestResponseValidation error (422) @@ -1105,2 +1209,0 @@ index.tsUsing decorators - 25 - 26 @@ -1111,9 +1214,3 @@ index.tsUsing decorators - import { - HttpStatusCodes, - Router, - } from '@aws-lambda-powertools/event-handler/http'; - import { Logger } from '@aws-lambda-powertools/logger'; - import type { Context } from 'aws-lambda/handler'; - - const logger = new Logger(); - const app = new Router({ logger }); + import { Router } from '@aws-lambda-powertools/event-handler/http'; + import type { Context } from 'aws-lambda'; + import { z } from 'zod'; @@ -1121,2 +1218 @@ index.tsUsing decorators - app.errorHandler(GetTodoError, async (error, reqCtx) => { - logger.error('Unable to get todo', { error }); + const app = new Router(); @@ -1124,4 +1220,3 @@ index.tsUsing decorators - return { - statusCode: HttpStatusCodes.BAD_REQUEST, - message: `Bad request: ${error.message} - ${reqCtx.req.headers.get('x-correlation-id')}`, - }; + const createTodoSchema = z.object({ + title: z.string(), + completed: z.boolean().optional().default(false), @@ -1130,4 +1225,10 @@ index.tsUsing decorators - app.get('/todos/:todoId', async ({ params: { todoId } }) => { - const todo = await getTodoById(todoId); // May throw GetTodoError - return { todo }; - }); + app.post( + '/todos', + (reqCtx) => { + const { title, completed } = reqCtx.valid.req.body; // (1)! + return { id: '123', title, completed }; + }, + { + validation: { req: { body: createTodoSchema } }, + } + ); @@ -1140,0 +1242,85 @@ index.tsUsing decorators + 1. Access the validated and typed request body via `reqCtx.valid.req.body`