feat: add HttpResolverAlpha resolver

[leandrodamascena]

Issue number: closes #7912

Summary

Adds HttpResolverAlpha - a new resolver that implements ASGI for running Event Handler APIs locally with uvicorn or any ASGI server.

Changes

• New HttpResolverAlpha class in aws_lambda_powertools/event_handler/http_resolver.py
• Implements ASGI spec, no external dependencies
• All existing features work: routing, middleware, validation, OpenAPI, CORS, exception handling
• Marked as Alpha with runtime warning

User experience

from aws_lambda_powertools.event_handler import HttpResolverAlpha

app = HttpResolverAlpha(enable_validation=True)

@app.get("/hello/<name>")
def hello(name: str):
    return {"message": f"Hello, {name}!"}

# Run locally: uvicorn app:app --reload
# Deploy to Lambda: handler = app

---

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.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[codecov]

Codecov Report

❌ Patch coverage is 96.25668% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.71%. Comparing base (a3255e9) to head (73f3ca1).

Files with missing lines	Patch %	Lines
...s_lambda_powertools/event_handler/http_resolver.py	96.23%	2 Missing and 5 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7913      +/-   ##
===========================================
- Coverage    96.72%   96.71%   -0.01%     
===========================================
  Files          275      276       +1     
  Lines        13214    13401     +187     
  Branches      1006     1030      +24     
===========================================
+ Hits         12781    12961     +180     
- Misses         325      327       +2     
- Partials       108      113       +5     

☔ 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.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[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

[dreamorosi]

I have some questions/concerns around whether this fits in the library.

Our first tenet says we focus on AWS Lambda runtime while this goes quite outside of that. I can see some value in having a regular resolver running locally for local development, but in the current shape the new resolver requires a code change which is creates a precedent in us adding a significant runtime implementation for a non-Lambda environment.

I am not opposing this feature, but I wonder if we can frame it differently or make it work differently.

As a quick win, I'd feel more comfortable if this was 1/ listed under the testing section of the docs, and 2/ named in a way that clearly conveys it's meant to be used for local testing only. In both cases my concern is that this gives the false impression that we want to support non-Lambda environments - which is not the case I hope.

Along the same lines, is there any way at all to get an existing resolver to work with the ASGI protocol when an env variable is set? I don't know the specifics but what I have in mind is basically customers using one of the already existing resolvers, and then when they set an env variable like POWERTOOLS_EVENT_HANDLER_ASGI the resolver works locally with this protocol.

Again, my goal here is mainly to make sure this is positioned in the correct way. Happy to discuss.

[leandrodamascena]

Those are fair points. Thanks for raising them.

I have some questions/concerns around whether this fits in the library.

Our first tenet says we focus on AWS Lambda runtime while this goes quite outside of that. I can see some value in having a regular resolver running locally for local development, but in the current shape the new resolver requires a code change which is creates a precedent in us adding a significant runtime implementation for a non-Lambda environment.

Actually there is a minimal code change between local and Lambda

1/ Change the resolver
2/ Uncomment the Lambda Handler.

As a quick win, I'd feel more comfortable if this was 1/ listed under the testing section of the docs, and 2/ named in a way that clearly conveys it's meant to be used for local testing only. In both cases my concern is that this gives the false impression that we want to support non-Lambda environments - which is not the case I hope.

I am good to name this HttpResolverLocal and list it in the testing documentation, making it clear to use for test. This is a quick solution for clients who want to run it locally and create prototypes, especially those who are not onboarded in Lambda and are getting used to the Lambda programming model.

Tests, local run, CI and more.

Along the same lines, is there any way at all to get an existing resolver to work with the ASGI protocol when an env variable is set? I don't know the specifics but what I have in mind is basically customers using one of the already existing resolvers, and then when they set an env variable like POWERTOOLS_EVENT_HANDLER_ASGI the resolver works locally with this protocol.

Hmm no, there isn't because I'll change the code behavior and it's not ideal.

Again, my goal here is mainly to make sure this is positioned in the correct way. Happy to discuss.

Sure thing, I think your point about tests and naming make it clear.

WDYT?

[dreamorosi]

Sounds good, thanks for explaining.

I am ok with moving the section in the docs under testing plus renaming.

I'd suggest HttpResolverLocalDev to make it extra clear, but if it's too long HttpResolverLocal that you suggested + a call out in the docstring of the class is enough.

For future reference/readers, in similar cases where the boundary of what we build is not clear, we'll still want to evaluate whether something fits or not - so our tenet still stands.