Feature request: Add a flag to ALBResolver to URL-decode query parameters

[chriselion]

Use case

(follow up from Discord thread: https://discord.com/channels/1006478942305263677/1432874977454985288)

Background: According to https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html, for ALB requests

If the query parameters are URL-encoded, the load balancer does not decode them. You must decode them in your Lambda function

This decoding should happen before input validation; I think datetime types are especially problematic for this if you're trying to pass them as ISO-format strings. For example: .../?start=2025-12-20T16%3A56%3A02.032000%2000%3A00&end=2025-12-30T16%3A56%3A02.032000%2000%3A00

Solution/User Experience

It would be nice for ALBResolver to optionally do this decoding for you (I understand it could be a behavior change, so you probably wouldn't want it to be enabled by default).

An example of this behavior in some other frameworks that process ALB events: https://github.com/brefphp/bref/issues/456 https://github.com/fastify/aws-lambda-fastify/pull/91

Alternative solutions

I was able to work around this by adding a middleware for my ALB handler:


from aws_lambda_powertools.middleware_factory import lambda_handler_decorator

@lambda_handler_decorator
def alb_query_parameter_decoder(
    handler: Callable[[dict, LambdaContext], dict],
    event: dict,
    context: LambdaContext,
) -> dict:
    query_params = event.get("queryStringParameters")
    if query_params:
        for k, v in query_params.items():
            try:
                query_params[k] = unquote(v)
            except Exception:
                pass

    return handler(event, context)

Acknowledgment

• [x] This feature request meets Powertools for AWS Lambda (Python) Tenets
• [x] Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET

[boring-cyborg[bot]]

Thanks for opening your first issue here! We'll come back to you as soon as we can. In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[phipag]

Thanks for opening this feature request @chriselion. One of our Python maintainers will come back to you so we can decide how to move forward on also how much effort this will be.

Some thoughts from my end: Maybe we can offer such functionality as a global middleware packaged within the library? Or as a top-level option on the ALBResolver?

I will mark this issue an Idea for now.

[chriselion]

Yeah, I imagined it as a top-level option for ALBResolver, although I'm not sure how easy it would be to implement.

[phipag]

Would you be interested in working on such an option @chriselion and contribute this to the code base?

[chriselion]

Sure, as long as you think it's worthwhile, I can try adding it.

[phipag]

@leandrodamascena What do you think? Is this a feature we would like add to the ALBResolver?