Skip to content

fix(parser): add a schema for each API Gateway WebSocket event - #6002

Open
Manishram-ai wants to merge 2 commits into
aws-powertools:mainfrom
Manishram-ai:fix/parser-websocket-event-schemas
Open

Manishram-ai wants to merge 2 commits into
aws-powertools:mainfrom
Manishram-ai:fix/parser-websocket-event-schemas

Conversation

@Manishram-ai

@Manishram-ai Manishram-ai commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

APIGatewayProxyWebsocketEventSchema required the REQUEST authorizer fields and the route fields together, so no event API Gateway sends to a WebSocket route matched it. As discussed in #6000, this adds one schema per event, like the Python models, and keeps the old schema as it is, marked as deprecated.

Changes

  • New APIGatewayWebSocketConnectEventSchema, APIGatewayWebSocketMessageEventSchema and APIGatewayWebSocketDisconnectEventSchema, each with a literal eventType and, for $connect and $disconnect, a literal routeKey. Message events now have messageId, disconnect events have disconnectStatusCode and disconnectReason, and connect events keep the optional query string fields.
  • The new schemas are exported with their APIGatewayWebSocketConnectEvent, APIGatewayWebSocketMessageEvent and APIGatewayWebSocketDisconnectEvent types.
  • APIGatewayProxyWebsocketEventSchema and its APIGatewayProxyWebsocketEvent type are unchanged from main and marked @deprecated, pointing to the three new schemas and saying they will be removed in the next major version.
  • New connect.json, message.json and disconnect.json test events, based on the WebSocket test events in Powertools for AWS Lambda (Python). The deprecated schema rejects all three.
  • The unit tests parse each event with its own schema and check that a message event without messageId and a disconnect event without disconnectStatusCode are rejected. One test still parses connectEvent.json with the deprecated schema.
  • The schema table in docs/features/parser.md lists the new schemas and marks APIGatewayProxyWebsocketEventSchema as deprecated.
  • The $connect authorizer event is left out, as you suggested.
  • npm run test:unit:coverage (coverage stays at 100%), npm run lint, npm run build:tests and npm run test:unit:types pass in packages/parser, and markdownlint passes on the docs page.

Issue number: closes #6000


By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

The WebSocket schema required the REQUEST authorizer fields and the route
fields together, so no event API Gateway sends matched it. Add one schema
per event, for $connect, messages and $disconnect, and rebuild
APIGatewayProxyWebsocketEventSchema as a union of the three.
@powertools-for-aws-oss-automation powertools-for-aws-oss-automation Bot added the size/XL PRs between 500-999 LOC, often PRs that grown with feedback label Nov 17, 2026

@dreamorosi dreamorosi left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this @Manishram-ai, and sorry for changing direction after you've done the work.

Reviewing the union showed us that it doesn't keep existing code working the way we hoped. Code that calls .extend(), .omit() or .pick() on APIGatewayProxyWebsocketEventSchema stops compiling, because those methods don't exist on a union. The inferred type also changes, and TypeScript can't narrow the union from the nested requestContext.eventType. Python doesn't have a catch-all model either.

So let's keep the three new schemas and drop the union:

  • Restore APIGatewayProxyWebsocketEventSchema and its APIGatewayProxyWebsocketEvent type exactly as they are on main, and mark both @deprecated. Point to the three new schemas and say it will be removed in the next major version. BatchProcessorSync has the wording we use.
  • Remove the union tests. Keep one test that parses connectEvent.json with the deprecated schema, so it stays covered until we remove it.
  • In docs/features/parser.md, mark the APIGatewayProxyWebsocketEventSchema row as deprecated instead of describing it as covering every WebSocket event.
  • Update the PR description to match.

The rest looks good. The per-event schemas, the test events and the tests are what we asked for.

@powertools-for-aws-oss-automation powertools-for-aws-oss-automation Bot removed the size/XL PRs between 500-999 LOC, often PRs that grown with feedback label Nov 18, 2026
@Manishram-ai

Copy link
Copy Markdown
Contributor Author

No problem, that makes sense. The union is gone in e37727d. APIGatewayProxyWebsocketEventSchema and its type are back as they are on main and marked deprecated, with one test still parsing connectEvent.json, and the docs row says it's deprecated. I updated the description too.

@powertools-for-aws-oss-automation powertools-for-aws-oss-automation Bot added the size/L PRs between 100-499 LOC label Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/L PRs between 100-499 LOC

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bug: APIGatewayProxyWebsocketEventSchema rejects the events API Gateway sends for WebSocket APIs

2 participants