feat(event_handler): inject resolver into Depends() instead of Request for middleware parity

[Iamrodos]

Summary

Depends() (#8128) currently injects Request into dependency functions — a thin 7-property wrapper that loses most of what Powertools provides. Before this ships in a release, I would like to propose the injection target should be the resolver (app) instead. This gives dependency functions the same data access that middleware has, and enables incremental migration of the data-sharing role that append_context/app.context currently fills.

I have a PR ready to accompany this issue.

Context

This comes from real-world evaluation of adopting Depends() in an existing codebase that uses middleware and app.context extensively (~550 references). See discussion #4551 (my detailed feedback comment) and the original feature request #8099.

Note: Depends() is not a replacement for middleware — middleware handles request interception (short-circuiting with 401s, modifying responses) which Depends() cannot do. However, Depends() does replace the data-sharing role that middleware performs via append_context/app.context. For that role, dependency functions need the same data access that middleware has.

Why Request is a problematic injection target

1. The abstraction is incomplete. The example in #8099 itself wrote request.current_event — which doesn't exist on Request. Request only exposes 7 properties: route, path_parameters, method, headers, query_parameters, body, json_body. Missing: cookies, actual request path, event helpers (get_query_string_value, get_header_value), request_context, and the full Lambda event.

2. The docs already work around the gap. In examples/event_handler_rest/src/dependency_injection.py line 26, the handler uses app.current_event.json_body via a module global because there's no way to access it through Depends().

3. Module globals don't work across router modules. When routes are split into separate files using Router(), the module-level app is a Router instance, not the resolver — it doesn't have current_event. This is the exact problem that started discussion #4551 and led to the middleware wrapper pattern. Using app instead of Request unlocks much more sophisticated split routing scenarios without workarounds.

4. Module globals break dependency_overrides. If dependency functions read from globals instead of receiving the resolver as a parameter, you can't swap them in tests. This undermines the core testability value of Depends().

5. Request injection proves globals aren't the answer. If module globals were sufficient, there'd be no need for Request injection at all. The intention of Request indicates that dependency functions should receive what they need as parameters. My suggestion is that the injected object just needs to be more capable.

6. Data access parity with middleware. Middleware receives the full resolver with current_event, context, and lambda_context. Since Depends() replaces the data-sharing role of middleware, dependency functions need the same level of data access. Without it, teams can't incrementally migrate their app.context usage to Depends().

Proposed change

Replace Request injection with resolver injection in solve_dependencies():

• Dependency functions that type-hint a parameter as BaseRouter (or any resolver subclass) automatically receive the resolver
• Remove the special-case Request injection — users who want Request can use app.request
• Request class stays as-is, just no longer auto-injected
• Export BaseRouter from aws_lambda_powertools.event_handler

Before (current):

def get_authenticated_user(request: Request) -> str:
    user_id = request.headers.get("x-user-id")  # limited to 7 properties
    # Can't access: cookies, path, app.context, current_event helpers
    return user_id

After (proposed):

from aws_lambda_powertools.event_handler import BaseRouter

def get_authenticated_user(app: BaseRouter) -> str:
    user_id = app.current_event.headers.get("x-user-id")
    # Full access: cookies, path, context, event helpers, lambda_context
    return user_id

This is a minimal change — 3 files modified in the core, plus test and doc updates. I have created a PR for review and look forward to a discussion to bring the best we can to Powertools users.

[leandrodamascena]

Hey @Iamrodos! Thanks for taking the time to evaluate Depends() against your real-world codebase - that kind of feedback is incredibly valuable.

You raise good points about Request being too thin for advanced use cases. However, I don't think injecting the full resolver (BaseRouter) is the right path. Let me breakdown:

Why not inject the resolver

Depends() was intentionally designed to work with typed, scoped data - not the full resolver. This was how I designed this because:

1. I don't think Depends() is a middleware replacement. It's a complementary pattern for dependency injection. Middleware still exists and is the right tool when you need the full resolver lifecycle (pre/post processing, short-circuiting, etc.)

2. Injecting BaseRouter exposes too much stuff. BaseRouter is the class that manages route registration, middleware chains, CORS, exception handlers, and shared mutable state (app.context). A dependency function that receives it can register new routes, modify middleware, clear context mid-request, or call resolve() again. That's not a theoretical risk - it makes dependencies unpredictable and nearly impossible to unit test without spinning up the entire resolver.

3. When it comes to test, having Request you can construct a test Request object with exactly the data you need. With the resolver, you'd need to mock or instantiate the entire resolver with its state, middleware chain, etc.

What I'm going to do instead

I agree Request needs to be more capable and I missed some points. The Request object already holds the full current_event internally (self._current_event) and it just doesn't expose it. I'm planning to add:

# Expose the full Powertools event (cookies, helpers, request_context, etc.)
request.resolved_event  # → BaseProxyEvent (current_event)

# Expose the resolver context for incremental migration from middleware
request.context  # → dict (app.context)

This gives you everything you're asking for without injecting the resolver. Here's how your auth → request parsing → permission chain would look:

This example was created using AI, pls review any gap here.

from typing import Annotated
from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Router, Request, Depends

# admin_router.py — no module globals, no circular imports
admin_router = Router()

def require_auth(request: Request) -> AuthUser:
    """Validates the token and returns the authenticated user."""
    token = request.resolved_event.get_header_value("authorization")
    if not token:
        raise UnauthorizedError("Missing authorization header")

    user = validate_token(token)

    # Bridge: existing handlers reading app.context["user"] keep working
    request.context["user"] = user

    return user

def setup_request(request: Request, user: Annotated[AuthUser, Depends(require_auth)]) -> RequestContext:
    """Parses form data, extracts handler metadata from the matched route."""
    form_data = parse_form_data(request.resolved_event.body)
    path = request.resolved_event.path  # actual path, not route pattern
    cookies = request.resolved_event.cookies

    ctx = RequestContext(user=user, form_data=form_data, path=path, cookies=cookies)

    # Bridge for incremental migration
    request.context["form_data"] = form_data

    return ctx

def check_permission(
    user: Annotated[AuthUser, Depends(require_auth)],
    ctx: Annotated[RequestContext, Depends(setup_request)],
) -> PermissionResult:
    """Checks if the user has permission for this route + action."""
    return authorize(user=user, path=ctx.path, action=ctx.form_data.get("action"))

@admin_router.route("/admin", method=["GET", "POST"])
def admin(
    user: Annotated[AuthUser, Depends(require_auth)],
    ctx: Annotated[RequestContext, Depends(setup_request)],
    perms: Annotated[PermissionResult, Depends(check_permission)],
):
    # All dependencies resolved, typed, and available
    # Existing app.context["user"] / app.context["form_data"] also work
    # for the 550 lines of code you haven't migrated yet
    ...

Testing is straightforward - no resolver mocking needed:

from aws_lambda_powertools.event_handler import Request
from my_app.deps import require_auth

def test_require_auth():
    request = Request(
        route_path="/admin",
        path_parameters={},
        current_event=mock_event_with_valid_token,
    )
    user = require_auth(request)
    assert user.role == "admin"

This addresses your concerns:

• Incomplete abstraction → resolved_event exposes the full Powertools event with all helpers
• Router modules → Request is injected per-invocation, no module globals needed
• Migration from app.context → request.context provides read/write access for incremental migration
• Middleware parity → same data access, different (and cleaner) interface

I appreciate the energy you're putting into this and pls let me know if that make sense for you.

[Iamrodos]

Thanks @leandrodamascena, your reasoning about not injecting the full resolver makes sense. BaseRouter exposes too much (route registration, middleware chains, etc.) and the richer Request is a cleaner design.

I'll admit I got a bit sidetracked evaluating Depends() as a middleware replacement. The discussion in #4551 suggested it as a solution to my per-router middleware problem, and I ran with that framing. Your response clarified that these are complementary patterns, which makes much more sense. Depends() can replace some middleware where the middleware is purely doing data-sharing (like my setup_request which just parses form data and injects values), but not all of it.

Two thoughts on your example:

Auth as Depends() doesn't work for some auth flows

Your require_auth example raises UnauthorizedError on failure. In practice, auth middleware often needs to return custom HTTP responses, not just exceptions. For example, an unauthenticated GET needs to redirect to Cognito login with a state param for deep linking back (302 /authenticated?state=/admin/users), while an unauthenticated POST or htmx request should get a plain 401. Permission denials need a redirect to /401, or an HX-Redirect header for htmx requests.

Depends() can't return HTTP responses, it can only return values or raise exceptions. So for some use cases auth and permission checking must remain as middleware. This means the enriched Request isn't just nice-to-have. request.context is essential as the bridge between middleware (which might handle auth and setup some data) and Depends() (which handles data-sharing). Middleware writes request.context["user"], dependencies read it.

Documentation should clarify the relationship

It would really help if the docs clearly explained that middleware and Depends() are complementary. Middleware for request interception (auth, permission gates, response modification), Depends() for typed data injection. A brief "when to use which" section and an example showing them working together via request.context would save others the same journey I went through.

Looking forward to the enriched Request and being able to update some of my routes to use Depends() for components where the capabilities of middleware are not required. Happy to help test, review, or contribute documentation.

[leandrodamascena]

Hey @Iamrodos, you spot on with both points.

I agree that uth flows that need HTTP response control (redirects, conditional 401s) must stay as middleware. Depends() returns typed values, it can't short-circuit with a custom response. That's by design: middleware for request interception, Depends() for typed data injection.

The bridge between them is request.context - middleware writes it, Depends() reads it:

# Auth stays as middleware - needs HTTP response control
@app.use_middleware
def auth_middleware(app, next_middleware):
    token = app.current_event.get_header_value("authorization")
    if not token:
        return Response(status_code=302, headers={"Location": "/login"})
    
    app.append_context(user=validate_token(token))
    return next_middleware(app)

# Depends() reads what middleware wrote — typed and testable
def get_current_user(request: Request) -> AuthUser:
    return request.context["user"]

@admin_router.route("/admin", method=["GET", "POST"])
def admin(user: Annotated[AuthUser, Depends(get_current_user)]):
    ...

I 100% agree about the, I'll add a "when to use which" section. Your example is exactly the kind of confusion good docs should prevent.

Thanks for helping shape this, happy to have you test this feature even before we launch this.