docs(event_handler): polish WebSocket resolver docs from final review

Author: Iamrodos

README.md

@@ -24,6 +24,7 @@ Core utilities such as Tracing, Logging, Metrics, and Event Handler are availabl
 * **[Event handler: AppSync](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/appsync/)** - AppSync event handler for Lambda Direct Resolver and Amplify GraphQL Transformer function
 * **[Event handler: AppSync Events](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/appsync_events/)** - AppSync Events handler for real-time WebSocket APIs with pub/sub pattern
 * **[Event handler: API Gateway, ALB, Lambda Function URL, VPC Lattice](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/)** - REST/HTTP API event handler for Lambda functions invoked via Amazon API Gateway, ALB, Lambda Function URL, and VPC Lattice
+* **[Event handler: API Gateway WebSocket](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway_websocket/)** - WebSocket API event handler for Lambda functions invoked via Amazon API Gateway WebSocket APIs
 * **[Event handler: Agents for Amazon Bedrock](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/bedrock_agents/)** - Create Agents for Amazon Bedrock, automatically generating OpenAPI schemas
 * **[Middleware factory](https://docs.powertools.aws.dev/lambda/python/latest/utilities/middleware_factory/)** - Decorator factory to create your own middleware to run logic before, and after each Lambda invocation
 * **[Parameters](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parameters/)** - Retrieve and cache parameter values from Parameter Store, Secrets Manager, AppConfig, or DynamoDB

aws_lambda_powertools/event_handler/api_gateway_websocket/router.py

@@ -24,7 +24,7 @@ class Router(BaseRouter):
     Registers route handlers for WebSocket route keys so they can be split across
     files and later included in an `APIGatewayWebSocketResolver` via `include_router`.
 
-    Parameters
+    Attributes
     ----------
     context : dict
         Dictionary to store context information accessible across route handlers

docs/core/event_handler/api_gateway_websocket.md

@@ -121,7 +121,9 @@ A returned dict is always body content — it is never inspected for a `statusCo
 The status code has different effects depending on the route:
 
 * **`$connect`**: the status code decides the connection — 2xx accepts the WebSocket upgrade, anything else rejects it.
-* **All other routes**: the body is delivered back to the client only when the route has a route response configured, and a non-2xx status code does **not** drop the connection.
+* **All other routes**: the body is delivered back to the client only on routes with a [route response](#terminology), and a non-2xx status code does **not** drop the connection.
+
+An event whose route key has no registered handler emits a `PowertoolsUserWarning` and returns `{"statusCode": 400}` — on `$connect`, that rejects the connection.
 
 ## Advanced
 
@@ -145,7 +147,7 @@ Execution order is: global middlewares (`app.use`), then route-level `middleware
 
 ### Authentication patterns
 
-`$connect` is the only route where credentials exist: headers and cookies are present on the WebSocket handshake only, and later messages carry nothing but the connection ID. There are two ways to bridge that gap.
+`$connect` is the only route where credentials exist: headers and cookies are present on the WebSocket handshake only, and later messages carry nothing from the client but the connection ID. There are two ways to bridge that gap.
 
 #### Lambda authorizer
 
@@ -229,7 +231,7 @@ Use `app.append_context` / `app.context` to share data between middlewares and h
 
 ### Sending messages to connected clients
 
-Returned bodies only reply to the **calling** client, on routes with a route response. To push a message to a client at any time — including after the invocation that received the request has long finished — call the API Gateway Management API's `PostToConnection` with the connection ID, against the endpoint the `callback_url` property gives you.
+Returned bodies only reply to the **calling** client. To push a message to a client at any time — including after the invocation that received the request has long finished — call the API Gateway Management API's `PostToConnection` with the connection ID, against the endpoint the `callback_url` property gives you.
 
 Capture `connection_id` and `callback_url` together at `$connect` and persist them: that record is everything **any** process needs to push to that client later.
 

docs/index.md

@@ -52,7 +52,7 @@ Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverles
 | [Tracer](./core/tracer.md) | Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions |
 | [Logger](./core/logger.md) | Structured logging made easier, and target to enrich structured logging with key Lambda context details |
 | [Metrics](./core/metrics.md) | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF) |
-| [Event Handler](./core/event_handler/api_gateway.md) | Event handler for API Gateway, ALB, Lambda Function URL, VPC Lattice, AppSync, and Bedrock Agents |
+| [Event Handler](./core/event_handler/api_gateway.md) | Event handler for API Gateway, ALB, Lambda Function URL, VPC Lattice, API Gateway WebSocket, AppSync, and Bedrock Agents |
 | [Parameters](./utilities/parameters.md) | Retrieve and cache parameter values from Parameter Store, Secrets Manager, AppConfig, or DynamoDB |
 | [Parser](./utilities/parser.md) | Data parsing and deep validation using Pydantic |
 | [Batch Processing](./utilities/batch.md) | Handle partial failures for SQS, Kinesis Data Streams, and DynamoDB Streams |

examples/event_handler_api_gateway_websocket/src/my_connection_store.py

@@ -1,6 +1,7 @@
 # Illustrative connection store. In production, back these functions with a durable store
 # such as a DynamoDB table: the WebSocket resolver and the functions that push results run
-# in different Lambda execution environments and cannot share process memory.
+# in different Lambda execution environments and cannot share process memory. Use a TTL —
+# $disconnect delivery is best-effort, so missed disconnects would leak entries forever.
 
 _connections: dict[str, str] = {}
 

mkdocs.yml

@@ -22,9 +22,9 @@ nav:
           - Event Handler:
               - core/event_handler/api_gateway.md
               - core/event_handler/openapi.md
+              - core/event_handler/api_gateway_websocket.md
               - core/event_handler/appsync.md
               - core/event_handler/appsync_events.md
-              - core/event_handler/api_gateway_websocket.md
               - core/event_handler/bedrock_agents.md
           - utilities/parameters.md
           - utilities/batch.md
@@ -244,9 +244,9 @@ plugins:
           - core/metrics.md
           - core/metrics/datadog.md
           - core/event_handler/api_gateway.md
+          - core/event_handler/api_gateway_websocket.md
           - core/event_handler/appsync.md
           - core/event_handler/appsync_events.md
-          - core/event_handler/api_gateway_websocket.md
           - core/event_handler/bedrock_agents.md
         Utilities:
           - utilities/parameters.md