feat(event_handler): add Router support to API Gateway WebSocket resolver

include_router merges a Router's routes, global middlewares,
exception handlers, and context into the resolver, so route keys can
be split across files. Router handlers access the request through the
router instance (router.current_event), mirroring the AppSync Events
and REST resolver conventions. On route key collisions the
router-registered handler wins, matching AppSync Events.

Includes tests for dispatch, context pointer sharing, middleware and
exception-handler merging and ordering, route-key precedence, plus
docs with a two-file example.

Author: Iamrodos

aws_lambda_powertools/event_handler/api_gateway_websocket/websocket.py

@@ -166,6 +166,43 @@ def exception_handler(self, exc_class: type[Exception] | list[type[Exception]])
         """
         return self.exception_handler_manager.exception_handler(exc_class=exc_class)
 
+    def include_router(self, router: Router) -> None:
+        """
+        Add all routes, middlewares, exception handlers, and context defined in a router.
+
+        Parameters
+        ----------
+        router : Router
+            A router containing routes to include, typically defined in a separate module
+
+        Examples
+        --------
+        >>> # orders.py
+        >>> from aws_lambda_powertools.event_handler.api_gateway_websocket import Router
+        >>>
+        >>> router = Router()
+        >>>
+        >>> @router.route("orderUpdate")
+        >>> def order_update():
+        >>>     return {"orderId": router.current_event.json_body["orderId"]}
+        >>>
+        >>> # app.py
+        >>> import orders
+        >>> from aws_lambda_powertools.event_handler import APIGatewayWebSocketResolver
+        >>>
+        >>> app = APIGatewayWebSocketResolver()
+        >>> app.include_router(orders.router)
+        """
+        logger.debug("Merging router and app context")
+        self.context.update(**router.context)
+        # use pointer to allow context clearance after event is processed e.g., resolve(evt, ctx)
+        router.context = self.context
+
+        logger.debug("Merging router routes, middlewares, and exception handlers")
+        self._router_middlewares.extend(router._router_middlewares)
+        self._route_registry.merge(router._route_registry)
+        self.exception_handler_manager.update_exception_handlers(router._exception_handlers)
+
     def _resolve_route(self) -> dict[str, Any]:
         """Dispatch the current event through the middleware chain to its route handler and normalize the response."""
         route_key = self.current_event.request_context.route_key

docs/core/event_handler/api_gateway_websocket.md

@@ -149,6 +149,26 @@ Without a Lambda authorizer, authenticate on `$connect` with a middleware and pe
     3. Returning without calling `next_middleware` short-circuits the chain — the handler never runs and the connection is rejected.
     4. Handlers and later middlewares read it from `app.context`.
 
+### Split routes with Router
+
+As your API grows, group related route keys in separate files with `Router`, then include them in the resolver. `include_router` merges the router's routes, global middlewares (`use`), exception handlers, and context into the app. Inside a router file, access the request through the router instance — `router.current_event`, `router.lambda_context`, and `router.context`.
+
+=== "working_with_router_orders.py"
+
+    ```python hl_lines="3 8"
+    --8<-- "examples/event_handler_api_gateway_websocket/src/working_with_router_orders.py"
+    ```
+
+    1. Use the router instance to access the current event inside router files.
+
+=== "working_with_router.py"
+
+    ```python hl_lines="1 7"
+    --8<-- "examples/event_handler_api_gateway_websocket/src/working_with_router.py"
+    ```
+
+    1. Registers every route, middleware, and exception handler defined on the router.
+
 ### Exception handling
 
 Register handlers for specific exception types with `@app.exception_handler`; it also accepts a list of types, and lookup respects inheritance. The handler receives the exception, and its return value goes through the same [response normalization](#response-format).

examples/event_handler_api_gateway_websocket/src/working_with_router.py

@@ -0,0 +1,16 @@
+import working_with_router_orders
+
+from aws_lambda_powertools.event_handler import APIGatewayWebSocketResolver
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+app = APIGatewayWebSocketResolver()
+app.include_router(working_with_router_orders.router)  # (1)!
+
+
+@app.on_connect()
+def connect():
+    return None
+
+
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    return app.resolve(event, context)

examples/event_handler_api_gateway_websocket/src/working_with_router_orders.py

@@ -0,0 +1,15 @@
+from aws_lambda_powertools.event_handler.api_gateway_websocket import Router
+
+router = Router()
+
+
+@router.route("orderUpdate")
+def order_update():
+    order = router.current_event.json_body  # (1)!
+    return {"orderId": order["orderId"], "status": "received"}
+
+
+@router.route("orderCancel")
+def order_cancel():
+    order = router.current_event.json_body
+    return {"orderId": order["orderId"], "status": "cancelled"}

tests/functional/event_handler/required_dependencies/api_gateway_websocket/test_api_gateway_websocket_resolver.py

@@ -676,3 +676,152 @@ def route_b():
 
     # THEN the global middleware runs on both routes; the route-level middleware runs only on route A
     assert order == ["global:routeA", "route_a_mw:routeA", "handler_a", "global:routeB", "handler_b"]
+
+
+def test_included_router_routes_are_dispatched(message_event, lambda_context):
+    # GIVEN routes registered on a standalone Router
+    event = deepcopy(message_event)
+    event["requestContext"]["routeKey"] = "orderUpdate"
+
+    router = Router()
+
+    @router.route("orderUpdate")
+    def order_update():
+        return "router handled it"
+
+    # WHEN the router is included and the event resolved
+    app = APIGatewayWebSocketResolver()
+    app.include_router(router)
+    result = app.resolve(event, lambda_context)
+
+    # THEN the router-registered handler is dispatched
+    assert result == {"statusCode": 200, "body": "router handled it"}
+
+
+def test_router_current_event_and_lambda_context_in_handler(message_event, lambda_context):
+    # GIVEN a router handler accessing the event and context through the router instance
+    event = deepcopy(message_event)
+    event["requestContext"]["routeKey"] = "orderUpdate"
+
+    router = Router()
+    captured = {}
+
+    @router.route("orderUpdate")
+    def order_update():
+        captured["event"] = router.current_event
+        captured["context"] = router.lambda_context
+
+    app = APIGatewayWebSocketResolver()
+    app.include_router(router)
+
+    # WHEN the event is resolved through the app
+    app.resolve(event, lambda_context)
+
+    # THEN the router sees the same event and context as the app (class-attribute mechanism)
+    assert isinstance(captured["event"], APIGatewayWebSocketEvent)
+    assert captured["event"].request_context.route_key == "orderUpdate"
+    assert captured["context"] is lambda_context
+
+
+def test_include_router_merges_and_shares_context(connect_event, lambda_context):
+    # GIVEN context appended to a router before inclusion
+    router = Router()
+    router.append_context(source="router")
+    captured = {}
+
+    @router.route("$connect")
+    def connect():
+        captured["source"] = router.context.get("source")
+        captured["app_added"] = router.context.get("app_added")
+
+    app = APIGatewayWebSocketResolver()
+    app.include_router(router)
+
+    # THEN the router context is merged into the app and the pointer is shared
+    assert app.context["source"] == "router"
+    assert router.context is app.context
+
+    # WHEN the app appends more context and the event is resolved
+    app.append_context(app_added=True)
+    app.resolve(connect_event, lambda_context)
+
+    # THEN the handler saw both values and clear_context cleared the shared dict
+    assert captured == {"source": "router", "app_added": True}
+    assert app.context == {}
+    assert router.context == {}
+
+
+def test_router_level_use_middlewares_are_merged(connect_event, lambda_context):
+    # GIVEN global middlewares on both the app and a router, and a route-level middleware on the router route
+    app = APIGatewayWebSocketResolver()
+    router = Router()
+    order = []
+
+    def app_middleware(app_, next_middleware):
+        order.append("app")
+        return next_middleware(app_)
+
+    def router_middleware(app_, next_middleware):
+        order.append("router")
+        return next_middleware(app_)
+
+    def route_middleware(app_, next_middleware):
+        order.append("route_mw")
+        return next_middleware(app_)
+
+    app.use(middlewares=[app_middleware])
+    router.use(middlewares=[router_middleware])
+
+    @router.route("$connect", middlewares=[route_middleware])
+    def connect():
+        order.append("handler")
+
+    # WHEN the router is included and the event resolved
+    app.include_router(router)
+    result = app.resolve(connect_event, lambda_context)
+
+    # THEN globals run in merge order (app then router), then the route-level middleware, then the handler
+    assert result == {"statusCode": 200}
+    assert order == ["app", "router", "route_mw", "handler"]
+
+
+def test_router_exception_handlers_are_merged(connect_event, lambda_context):
+    # GIVEN an exception handler registered on a router
+    router = Router()
+
+    @router.exception_handler(ValueError)
+    def handle_value_error(exc: ValueError):
+        return {"error": str(exc)}, 400
+
+    @router.route("$connect")
+    def connect():
+        raise ValueError("router boom")
+
+    # WHEN the router is included and the event resolved
+    app = APIGatewayWebSocketResolver()
+    app.include_router(router)
+    result = app.resolve(connect_event, lambda_context)
+
+    # THEN the router-registered exception handler is used
+    assert result == {"statusCode": 400, "body": '{"error":"router boom"}'}
+
+
+def test_included_router_route_wins_over_app_route(connect_event, lambda_context):
+    # GIVEN the app and a router both registering the same route key
+    app = APIGatewayWebSocketResolver()
+    router = Router()
+
+    @app.on_connect()
+    def app_connect():
+        return "from app"
+
+    @router.route("$connect")
+    def router_connect():
+        return "from router"
+
+    # WHEN the router is included and the event resolved
+    app.include_router(router)
+    result = app.resolve(connect_event, lambda_context)
+
+    # THEN the router-registered handler takes precedence (last-wins merge semantics)
+    assert result == {"statusCode": 200, "body": "from router"}