Feature request: Add support for middlewares in event handler

[BVMiko]

Is your feature request related to a problem? Please describe.
Event handlers (specifically ApiGatewayResolver) are incompatible with middleware decorators. The lambda_handler_decorator is almost exactly what would be needed, except for the function signature.

Describe the solution you'd like
I'd like to be able to add middleware when using a router, and for the middleware to have access to the processed event:

@router_decorator
def db_middleware(handler, router, **kwargs):
    db = router.current_event.get_query_string_value(name="dbname", default_value='default_value')
    return handler(db=db, **kwargs)
    
@router.get("/users")
@db_middleware(router=router)
def get_users(db, foo) -> Dict:
    pagination_limit = router.current_event.get_query_string_value(name="limit", default_value=10)
    return {"pagination_limit": pagination_limit, "db": db}

Describe alternatives you've considered
Using a regular lambda_handler_decorator outside of the router.get is executed even when the router isn't called. The decorator wrapper could be stored in individual project code, but since it's so similar to the existing one and would be useful for any router usage, it makes sense to consider it for the aws-lambda-powertools library.

Additional context

[heitorlessa]

Hey @BVMiko - thanks for opening this feature request.

Perhaps a generic middleware factory decorator for any Python function with an arbitrary number of args, kwargs?

That would help make it more explicit so we have one for Lambda and for any function - it also makes it easier to preserve types and function signature (ParamSpec is only supported in later Python versions)

It's something I wanted to do for a long time but couldn't prioritise earlier

Thanks a lot btw!

[karanhere3962]

@heitorlessa Here is what would make sense for middleware :
Defining middleware :

        def auth_middleware(app, handler):

        ### auth logic here ###

        setattr(app.current_event, "user", user_obj) # or app.current_event.extras["user"] = user_obj - a well defined place through which extra information can be passed on to routes.

        return handler()  # I haven't seen the code base so I don't know how difficult/easy it would be to implement this`

Registering middleware :

app.register_middleware(auth_middleware)

[heitorlessa]

Thanks a lot @karanhere3962 -- that's similar to FastAPI.

As this would run for every request, what's the UX you have in mind for a middleware that only runs on a given path?

Example:

• Register as part of route definition: @app.get("/path", middlewares=[]
• Register anywhere else: app.include_middleware(middleware, route="/path")

The details are important so we keep maintenance and extensibility at heart to follow our tenets.

Any other ideas would be great.

Cc @marcioemiranda who proposed this in the early days

[karanhere3962]

Both the options that you have given seem great.

[heitorlessa]

Reviving this feature request now that we finished with all V2 post-release tasks.

These are questions I'd like us to answer and get a POC moving.

Writing a middleware

• What should the signature looks like? e.g., def my_middleware(app, get_response, **kwargs) -> Response
• What does short-circuiting should look like? e.g., if schema validation fail we should return early and not call any subsequent registered middleware
• Should we allow mutability on query strings/headers/body? e.g., app.current_event properties are immutable today for various reasons, but we can have setters if needed.
  • alternative: middleware could use append_context feature so the underlying event always stays true avoiding complications - cons: typing gymnastics depending on what a middleware wants to inject

Registering a middleware

• Per route: Should we add a single parameter, namely middlewares=[]?
• Per route: Should we add a before_request and after_request parameters? e.g., advantage being simpler to write/read middlewares
  • Or keep it simple with middlewares=[] only? in the future we could have a class-based resolver to not over-complicate things.
• Per request: Given per route and global middlewares were registered (App+Routers), which order do we resolve?

Built-in middlewares

• What are some of the must-have middlewares we should have available within Powertools? e.g., schema validation

Suggestion: I think we should revisit the UX for creating/registering middlewares and get inspired about some of these libraries[1] decisions, so that we keep our Tenets in mind and performance.

[1] Chalice middlewares, FastAPI Middleware, Django Middleware, Starlite

[heitorlessa]

Prioritizing it for our next iteration May 8th-May 19th

[heitorlessa]

reassigning as I'm starting a POC tomorrow, apologies for the delay everyone - security and operations took priority (as it should)

[heitorlessa]

UPDATE: we had to reprioritize it due to Pydantic v2 launch and the weight it brought in the ecosystem (breaking changes) - @leandrodamascena is on it, but I took on-call responsibilities until the end of next week.

Realistically speaking, only resuming a local POC I got by the end of the month. Meanwhile, @rubenfonseca continues to work on OpenAPI + SwaggerUI auto-generation RFC + POC.

Apologies for the delays here...

[walmsles]

Thoughts on Middleware (based on @heitorlessa's questions above):

Reviving this feature request now that we finished with all V2 post-release tasks.

These are questions I'd like us to answer and get a POC moving.

Writing a middleware

• What should the signature looks like? e.g., def my_middleware(app, get_response, **kwargs) -> Response

I like this signature - **kwargs enables possible dependency injection from middleware so resolves additional use-cases

• What does short-circuiting should look like? e.g., if schema validation fail we should return early and not call any subsequent registered middleware

• with middleware calling the next get_response(app, **kwargs) - any middleware can raise an exception to halt the continuation of request processing. Any prior middleware wanting to catch/handle exceptions may do so using try: ... except: so becomes a simple language every dev understands

• Should we allow mutability on query strings/headers/body? e.g., app.current_event properties are immutable today for various reasons, but we can have setters if needed.

• I feel the original event should remain immutable.

• alternative: middleware could use append_context feature so the underlying event always stays true avoiding complications - cons: typing gymnastics depending on what a middleware wants to inject

• I like this idea, con is a concern - might need more input here to understand better - although **kwargs above could do away with this need - given devs could inject whatever they wanted to the route handlers with this mechanism, and it is completely in their control

Registering a middleware

• Per route: Should we add a single parameter, namely middlewares=[]?

• Yes - this is nice and simple, devs also set the order in the array, and that's how they are executed

• Per route: Should we add a before_request and after_request parameters? e.g., advantage being simpler to write/read middlewares

• No, I dislike the use of before_request, after_request and error - properly constructed middleware stack naturally has this behaviour via: before/after - due to the placement of code around calling get_response(app, context) and errorviatry:...except:` language blocks

• Per request: Given per route and global middlewares were registered (App+Routers), which order do we resolve?

• Resolution order should be global followed by route - global would usually represent cross-cutting concerns that benefit from the earlier resolution

Built-in middlewares

• What are some of the must-have middlewares we should have available within Powertools? _e.g., schema validation

• schema validation
• ResponseCaching
• Idempotency (??)
• custom authorizers (with care)
• ResponseStreaming (????? 👀)
• refactor built_in features to core middleware (backward compatibility alert)
  - Cors
  - Compression
  - Cache-Control

[1] Chalice middlewares, FastAPI Middleware, Django Middleware, Starlite

Inspiration: Starlette

Fast API, Chalice & Starlette implementation is very similar - I like the approach (classic middleware implementation that is easy to reason about).

[walmsles]

Looking deeper: We need to consider how to bring middleware to appsync resolvers - I feel the same DX works. I feel I need to dig deeper into AppSync and Powertools, its very separate from other resolvers (and likely with good cause).

[heitorlessa]

Sounds great to me @walmsles! On AppSync, @leandrodamascena @mploski are working on a refactor to support Batch event and partial failure, so I'd ignore middleware support in AppSync Event Handler until this work is complete #1303. Let's get Event Handler working POC first then we see how much is transferable as-is so it doesn't become a blocker.

[walmsles]

Thanks @heitorlessa - agree -that was my thinking.

[heitorlessa]

Sharing progress for anyone following - we're currently writing docs, probably 8 more hours and then a final pass before we release it. We're looking to make it available by early September

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.

[github-actions]

This is now released under 2.24.0 version!