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