feat(event_handler): add Request object for middleware access to resolved route and args

[oyiz-michael]

Issue number: closes #7992, closes #4609

Summary

Changes

• Added a new Request class (aws_lambda_powertools/event_handler/request.py) that provides structured access to the resolved route pattern, path parameters, HTTP method, headers, query parameters, and body
• Added app.request property on BaseRouter — available inside middleware after route resolution
• Added automatic Request injection into route handlers via type annotation (declare a parameter typed as Request and it gets injected automatically)
• Updated _registered_api_adapter to detect Request-annotated handler parameters and inject the object (with per-route caching to avoid repeated signature inspection)
• Updated OpenAPI get_dependant() to skip Request-typed parameters so they don't appear in generated schemas
• Exported Request from aws_lambda_powertools.event_handler

User experience

Before: Middleware had no access to the resolved route pattern or extracted path parameters. app.current_event.path_parameters only contained the raw API Gateway parameters (e.g. {"proxy": "..."} for {proxy+} routes), not the Powertools-resolved values.

After: Middleware and route handlers can access a Request object with the resolved route and parameters:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Request, Response

app = APIGatewayRestResolver()

# Middleware usage
def auth_middleware(app: APIGatewayRestResolver, next_middleware):
    req = app.request
    print(req.route)            # "/applications/{application_id}"
    print(req.path_parameters)  # {"application_id": "4da715ee-..."}
    print(req.method)           # "PUT"
    return next_middleware(app)

app.use(middlewares=[auth_middleware])

# Handler injection via type annotation
@app.get("/applications/<application_id>")
def get_application(application_id: str, request: Request):
    user_agent = request.headers.get("user-agent")
    return {"id": application_id, "user_agent": user_agent}

---

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.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[leandrodamascena]

Hey @oyiz-michael, thanks for this PR! This is a great addition. The Request object is much cleaner than having middleware dig into app.context or deal with API Gateway's raw {proxy+} path parameters. Really nice work on the tests too, you covered a lot of ground.

I went through the code and made a few improvements on top of your work.

I'll open a follow-up issue for documentation updates after we merge this. The middleware docs should show app.request as the recommended way to access resolved route info.

Thanks again for the contribution!

APPROVED!

[codecov]

Codecov Report

❌ Patch coverage is 92.18750% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.63%. Comparing base (dafed6a) to head (1730848).
⚠️ Report is 2 commits behind head on develop.

Files with missing lines	Patch %	Lines
aws_lambda_powertools/event_handler/api_gateway.py	90.32%	2 Missing and 1 partial ⚠️
...mbda_powertools/event_handler/openapi/dependant.py	33.33%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #8036      +/-   ##
===========================================
- Coverage    96.65%   96.63%   -0.03%     
===========================================
  Files          282      283       +1     
  Lines        13798    13862      +64     
  Branches      1103     1111       +8     
===========================================
+ Hits         13336    13395      +59     
- Misses         339      342       +3     
- Partials       123      125       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.