feat(event_handlers): Add support for Lambda Function URLs (#1408)

Author: rubenfonseca

aws_lambda_powertools/event_handler/__init__.py

@@ -11,6 +11,7 @@
     Response,
 )
 from .appsync import AppSyncResolver
+from .lambda_function_url import LambdaFunctionUrlResolver
 
 __all__ = [
     "AppSyncResolver",
@@ -19,5 +20,6 @@
     "ALBResolver",
     "ApiGatewayResolver",
     "CORSConfig",
+    "LambdaFunctionUrlResolver",
     "Response",
 ]

aws_lambda_powertools/event_handler/api_gateway.py

@@ -17,7 +17,12 @@
 from aws_lambda_powertools.shared import constants
 from aws_lambda_powertools.shared.functions import resolve_truthy_env_var_choice
 from aws_lambda_powertools.shared.json_encoder import Encoder
-from aws_lambda_powertools.utilities.data_classes import ALBEvent, APIGatewayProxyEvent, APIGatewayProxyEventV2
+from aws_lambda_powertools.utilities.data_classes import (
+    ALBEvent,
+    APIGatewayProxyEvent,
+    APIGatewayProxyEventV2,
+    LambdaFunctionUrlEvent,
+)
 from aws_lambda_powertools.utilities.data_classes.common import BaseProxyEvent
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
@@ -36,6 +41,7 @@ class ProxyEventType(Enum):
     APIGatewayProxyEvent = "APIGatewayProxyEvent"
     APIGatewayProxyEventV2 = "APIGatewayProxyEventV2"
     ALBEvent = "ALBEvent"
+    LambdaFunctionUrlEvent = "LambdaFunctionUrlEvent"
 
 
 class CORSConfig:
@@ -546,6 +552,9 @@ def _to_proxy_event(self, event: Dict) -> BaseProxyEvent:
         if self._proxy_type == ProxyEventType.APIGatewayProxyEventV2:
             logger.debug("Converting event to API Gateway HTTP API contract")
             return APIGatewayProxyEventV2(event)
+        if self._proxy_type == ProxyEventType.LambdaFunctionUrlEvent:
+            logger.debug("Converting event to Lambda Function URL contract")
+            return LambdaFunctionUrlEvent(event)
         logger.debug("Converting event to ALB contract")
         return ALBEvent(event)
 

aws_lambda_powertools/event_handler/lambda_function_url.py

@@ -0,0 +1,53 @@
+from typing import Callable, Dict, List, Optional
+
+from aws_lambda_powertools.event_handler import CORSConfig
+from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, ProxyEventType
+from aws_lambda_powertools.utilities.data_classes import LambdaFunctionUrlEvent
+
+
+class LambdaFunctionUrlResolver(ApiGatewayResolver):
+    """AWS Lambda Function URL resolver
+
+    Notes:
+    -----
+    Lambda Function URL follows the API Gateway HTTP APIs Payload Format Version 2.0.
+
+    Documentation:
+    - https://docs.aws.amazon.com/lambda/latest/dg/urls-configuration.html
+    - https://docs.aws.amazon.com/lambda/latest/dg/urls-invocation.html#urls-payloads
+
+    Examples
+    --------
+    Simple example integrating with Tracer
+
+    ```python
+    from aws_lambda_powertools import Tracer
+    from aws_lambda_powertools.event_handler import LambdaFunctionUrlResolver
+
+    tracer = Tracer()
+    app = LambdaFunctionUrlResolver()
+
+    @app.get("/get-call")
+    def simple_get():
+        return {"message": "Foo"}
+
+    @app.post("/post-call")
+    def simple_post():
+        post_data: dict = app.current_event.json_body
+        return {"message": post_data}
+
+    @tracer.capture_lambda_handler
+    def lambda_handler(event, context):
+        return app.resolve(event, context)
+    """
+
+    current_event: LambdaFunctionUrlEvent
+
+    def __init__(
+        self,
+        cors: Optional[CORSConfig] = None,
+        debug: Optional[bool] = None,
+        serializer: Optional[Callable[[Dict], str]] = None,
+        strip_prefixes: Optional[List[str]] = None,
+    ):
+        super().__init__(ProxyEventType.LambdaFunctionUrlEvent, cors, debug, serializer, strip_prefixes)

aws_lambda_powertools/logging/correlation_paths.py

@@ -6,4 +6,5 @@
 APPSYNC_RESOLVER = 'request.headers."x-amzn-trace-id"'
 APPLICATION_LOAD_BALANCER = 'headers."x-amzn-trace-id"'
 EVENT_BRIDGE = "id"
+LAMBDA_FUNCTION_URL = API_GATEWAY_REST
 S3_OBJECT_LAMBDA = "xAmzRequestId"

aws_lambda_powertools/utilities/data_classes/__init__.py

@@ -12,6 +12,7 @@
 from .event_bridge_event import EventBridgeEvent
 from .event_source import event_source
 from .kinesis_stream_event import KinesisStreamEvent
+from .lambda_function_url_event import LambdaFunctionUrlEvent
 from .s3_event import S3Event
 from .ses_event import SESEvent
 from .sns_event import SNSEvent
@@ -28,6 +29,7 @@
     "DynamoDBStreamEvent",
     "EventBridgeEvent",
     "KinesisStreamEvent",
+    "LambdaFunctionUrlEvent",
     "S3Event",
     "SESEvent",
     "SNSEvent",

aws_lambda_powertools/utilities/data_classes/api_gateway_proxy_event.py

@@ -127,19 +127,22 @@ def caller_id(self) -> Optional[str]:
     def cognito_amr(self) -> Optional[List[str]]:
         """This represents how the user was authenticated.
         AMR stands for  Authentication Methods References as per the openid spec"""
-        return self["cognitoIdentity"].get("amr")
+        cognito_identity = self["cognitoIdentity"] or {}  # not available in FunctionURL
+        return cognito_identity.get("amr")
 
     @property
     def cognito_identity_id(self) -> Optional[str]:
         """The Amazon Cognito identity ID of the caller making the request.
         Available only if the request was signed with Amazon Cognito credentials."""
-        return self["cognitoIdentity"].get("identityId")
+        cognito_identity = self.get("cognitoIdentity") or {}  # not available in FunctionURL
+        return cognito_identity.get("identityId")
 
     @property
     def cognito_identity_pool_id(self) -> Optional[str]:
         """The Amazon Cognito identity pool ID of the caller making the request.
         Available only if the request was signed with Amazon Cognito credentials."""
-        return self["cognitoIdentity"].get("identityPoolId")
+        cognito_identity = self.get("cognitoIdentity") or {}  # not available in FunctionURL
+        return cognito_identity.get("identityPoolId")
 
     @property
     def principal_org_id(self) -> Optional[str]:
@@ -159,12 +162,14 @@ def user_id(self) -> Optional[str]:
 
 class RequestContextV2Authorizer(DictWrapper):
     @property
-    def jwt_claim(self) -> Dict[str, Any]:
-        return self["jwt"]["claims"]
+    def jwt_claim(self) -> Optional[Dict[str, Any]]:
+        jwt = self.get("jwt") or {}  # not available in FunctionURL
+        return jwt.get("claims")
 
     @property
-    def jwt_scopes(self) -> List[str]:
-        return self["jwt"]["scopes"]
+    def jwt_scopes(self) -> Optional[List[str]]:
+        jwt = self.get("jwt") or {}  # not available in FunctionURL
+        return jwt.get("scopes")
 
     @property
     def get_lambda(self) -> Optional[Dict[str, Any]]:

aws_lambda_powertools/utilities/data_classes/common.py

@@ -395,5 +395,7 @@ def time_epoch(self) -> int:
     @property
     def authentication(self) -> Optional[RequestContextClientCert]:
         """Optional when using mutual TLS authentication"""
-        client_cert = self["requestContext"].get("authentication", {}).get("clientCert")
+        # FunctionURL might have NONE as AuthZ
+        authentication = self["requestContext"].get("authentication") or {}
+        client_cert = authentication.get("clientCert")
         return None if client_cert is None else RequestContextClientCert(client_cert)

aws_lambda_powertools/utilities/data_classes/lambda_function_url_event.py

@@ -0,0 +1,18 @@
+from aws_lambda_powertools.utilities.data_classes.api_gateway_proxy_event import APIGatewayProxyEventV2
+
+
+class LambdaFunctionUrlEvent(APIGatewayProxyEventV2):
+    """AWS Lambda Function URL event
+
+    Notes:
+    -----
+    Lambda Function URL follows the API Gateway HTTP APIs Payload Format Version 2.0.
+    
+    Keys related to API Gateway features not available in Function URL use a sentinel value (e.g.`routeKey`, `stage`).
+
+    Documentation:
+    - https://docs.aws.amazon.com/lambda/latest/dg/urls-configuration.html
+    - https://docs.aws.amazon.com/lambda/latest/dg/urls-invocation.html#urls-payloads
+    """
+
+    pass

docs/core/event_handler/api_gateway.md

@@ -3,11 +3,11 @@ title: REST API
 description: Core utility
 ---
 
-Event handler for Amazon API Gateway REST and HTTP APIs, and Application Loader Balancer (ALB).
+Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Balancer (ALB), and Lambda Function URLs.
 
 ## Key Features
 
-* Lightweight routing to reduce boilerplate for API Gateway REST/HTTP API and ALB
+* Lightweight routing to reduce boilerplate for API Gateway REST/HTTP API, ALB and Lambda Function URLs.
 * Support for CORS, binary and Gzip compression, Decimals JSON encoding and bring your own JSON serializer
 * Built-in integration with [Event Source Data Classes utilities](../../utilities/data_classes.md){target="_blank"} for self-documented event schema
 
@@ -18,23 +18,31 @@ Event handler for Amazon API Gateway REST and HTTP APIs, and Application Loader
 
 ### Required resources
 
-You must have an existing [API Gateway Proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html){target="_blank"} or [ALB](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html){target="_blank"} configured to invoke your Lambda function.
+If you're using any API Gateway integration, you must have an existing [API Gateway Proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html){target="_blank"} or [ALB](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html){target="_blank"} configured to invoke your Lambda function.
 
-This is the sample infrastructure for API Gateway we are using for the examples in this documentation.
+This is the sample infrastructure for API Gateway and Lambda Function URLs we are using for the examples in this documentation.
 
 ???+ info "There is no additional permissions or dependencies required to use this utility."
 
-```yaml title="AWS Serverless Application Model (SAM) example"
---8<-- "examples/event_handler_rest/sam/template.yaml"
-```
+=== "API Gateway SAM Template"
+
+    ```yaml title="AWS Serverless Application Model (SAM) example"
+    --8<-- "examples/event_handler_rest/sam/template.yaml"
+    ```
+
+=== "Lambda Function URL SAM Template"
+
+    ```yaml title="AWS Serverless Application Model (SAM) example"
+    --8<-- "examples/event_handler_lambda_function_url/sam/template.yaml"
+    ```
 
 ### Event Resolvers
 
 Before you decorate your functions to handle a given path and HTTP method(s), you need to initialize a resolver.
 
 A resolver will handle request resolution, including [one or more routers](#split-routes-with-router), and give you access to the current event via typed properties.
 
-For resolvers, we provide: `APIGatewayRestResolver`, `APIGatewayHttpResolver`, and `ALBResolver`.
+For resolvers, we provide: `APIGatewayRestResolver`, `APIGatewayHttpResolver`, `ALBResolver`, and `LambdaFunctionUrlResolver` .
 
 ???+ info
     We will use `APIGatewayRestResolver` as the default across examples.
@@ -87,6 +95,22 @@ When using Amazon Application Load Balancer (ALB) to front your Lambda functions
 --8<-- "examples/event_handler_rest/src/getting_started_alb_api_resolver.py"
 ```
 
+#### Lambda Function URL
+
+When using [AWS Lambda Function URL](https://docs.aws.amazon.com/lambda/latest/dg/urls-configuration.html), you can use `LambdaFunctionUrlResolver`.
+
+=== "getting_started_lambda_function_url_resolver.py"
+
+    ```python hl_lines="5 11" title="Using Lambda Function URL resolver"
+    --8<-- "examples/event_handler_lambda_function_url/src/getting_started_lambda_function_url_resolver.py"
+    ```
+
+=== "getting_started_lambda_function_url_resolver.json"
+
+    ```json hl_lines="4-5" title="Example payload delivered to the handler"
+    --8<-- "examples/event_handler_lambda_function_url/src/getting_started_lambda_function_url_resolver.json"
+    ```
+
 ### Dynamic routes
 
 You can use `/todos/<todo_id>` to configure dynamic URL paths, where `<todo_id>` will be resolved at runtime.
@@ -270,7 +294,7 @@ This will ensure that CORS headers are always returned as part of the response w
 
 #### Pre-flight
 
-Pre-flight (OPTIONS) calls are typically handled at the API Gateway level as per [our sample infrastructure](#required-resources), no Lambda integration necessary. However, ALB expects you to handle pre-flight requests.
+Pre-flight (OPTIONS) calls are typically handled at the API Gateway or Lambda Function URL level as per [our sample infrastructure](#required-resources), no Lambda integration is necessary. However, ALB expects you to handle pre-flight requests.
 
 For convenience, we automatically handle that for you as long as you [setup CORS in the constructor level](#cors).
 
@@ -339,6 +363,8 @@ Like `compress` feature, the client must send the `Accept` header with the corre
 ???+ warning
     This feature requires API Gateway to configure binary media types, see [our sample infrastructure](#required-resources) for reference.
 
+???+ note
+    Lambda Function URLs handle binary media types automatically.
 === "binary_responses.py"
 
     ```python hl_lines="14 20"
@@ -380,7 +406,7 @@ This will enable full tracebacks errors in the response, print request and respo
 
 ### Custom serializer
 
-You can instruct API Gateway handler to use a custom serializer to best suit your needs, for example take into account Enums when serializing.
+You can instruct event handler to use a custom serializer to best suit your needs, for example take into account Enums when serializing.
 
 ```python hl_lines="35 40" title="Using a custom JSON serializer for responses"
 --8<-- "examples/event_handler_rest/src/custom_serializer.py"
@@ -501,7 +527,7 @@ A micro function means that your final code artifact will be different to each f
 
 **Downsides**
 
-* **Upfront investment**. You need custom build tooling to bundle assets, including [C bindings for runtime compatibility](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html){target="_blank"}. `Operations become more elaborate — you need to standardize tracing labels/annotations, structured logging, and metrics to pinpoint root causes.
+* **Upfront investment**. You need custom build tooling to bundle assets, including [C bindings for runtime compatibility](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html){target="_blank"}. Operations become more elaborate — you need to standardize tracing labels/annotations, structured logging, and metrics to pinpoint root causes.
     * Engineering discipline is necessary for both approaches. Micro-function approach however requires further attention in consistency as the number of functions grow, just like any distributed system.
 * **Harder to share code**. Shared code must be carefully evaluated to avoid unnecessary deployments when that changes. Equally, if shared code isn't a library,
 your development, building, deployment tooling need to accommodate the distinct layout.