feat: add decorator factory to create your own middleware

[heitorlessa]

Issue #, if available: #20

Description of changes:

This is required for Serverless Airline project to move from the modified version of powertools, and create own middlewares to improve reusability as much as possible.

Instead of creating reusable methods, we're at the stage that makes more sense to give flexibility to create own middlewares as #9, so customers can create one middleware with many custom processing before, after and exception handling instead.

This gives flexibility to control before, after, and exception handling logic in the way you'd like. It also lay the foundations to allow us to create a base Trace provider so you can use any Tracer that follow our protocol.

• Create decorator factory
• Tests
• Use existing Tracer class instance to trace custom middlewares
• Update existing middlewares
• Update docs
• Utility to optionally trace middleware
• Optional: Automate API docs

One step closer from GA 🎉 - We'll tackle log level next!

User Experience

Create a middleware no params

from aws_lambda_powertools.middleware_factory import lambda_handler_decorator

@lambda_handler_decorator
def log_response(handler, event, context):
    any_code_to_execute_before_lambda_handler()                
    response = handler(event, context)
    any_code_to_execute_after_lambda_handler()
    print(f"Lambda handler response: {response}")
    return response

@log_response
def lambda_handler(event, context):
    return True

Create a middleware with params

from aws_lambda_powertools.middleware_factory import lambda_handler_decorator

@lambda_handler_decorator
def obfuscate_sensitive_data(handler, event, context, fields=None):
    # Obfuscate email before calling Lambda handler
    if fields:
        for field in fields:
            field = event.get(field, "")
            event[field] = obfuscate_pii(field)

    return handler(event, context)
    

@obfuscate_sensitive_data(fields=["email"])
def lambda_handler(event, context):
    return True

Trace execution of custom middleware - Creates sub-segments in X-Ray

```python
from aws_lambda_powertools.utils import lambda_handler_decorator

@lambda_handler_decorator(trace_execution=True)
def my_custom_middleware(handler, event, context):
    ...

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[heitorlessa]

Local perf tests to rule out major performance impact on multiple callables - Decorator only prints before handler and after.

While Lambda will have less CPU it'll continue to be less than a microsecond, so it worth using this factory to refactor codebase to make it more contributor friendly (dev time is more expensive)

No decorator

50000000 loops, best of 5: 6.88 nsec per loop

Simpler decorator

50000000 loops, best of 5: 7.18 nsec per loop

Decorator factory

50000000 loops, best of 5: 7.25 nsec per loop

Simpler Stacked decorator

50000000 loops, best of 5: 7.05 nsec per loop

Factory Stacked decorator

50000000 loops, best of 5: 7.05 nsec per loop

---

python -m timeit -s 'import handler; handler.lambda_handler({}, {})'

def call_handler_simpler(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("SIMPLER - BEGIN")
        response = func(*args, **kwargs)
        print("SIMPLER - END")
        return response
    return wrapper

@lambda_handler_decorator
def call_handler_factory(handler, event, context):
    print("[CALL HANDLER] BEGIN")
    response = handler(event, context)
    print("[CALL HANDLER] END")
    return response

def lambda_handler(event, context):
    a = {
        "statusCode": 200,
        "body": "Hello world"
    }
    print("-------------LAMBDA FN CALLED!-------------")
    return a