feat(parser): support for CloudFormation Custom Resources

aws_lambda_powertools/utilities/parser/models/__init__.py

@@ -14,6 +14,12 @@
     RequestContextV2AuthorizerJwt,
     RequestContextV2Http,
 )
+from .cloudformation_custom_resource import (
+    CloudFormationCustomResourceBaseModel,
+    CloudFormationCustomResourceCreateModel,
+    CloudFormationCustomResourceDeleteModel,
+    CloudFormationCustomResourceUpdateModel,
+)
 from .cloudwatch import (
     CloudWatchLogsData,
     CloudWatchLogsDecode,
@@ -147,4 +153,8 @@
     "KafkaBaseEventModel",
     "KinesisFirehoseSqsModel",
     "KinesisFirehoseSqsRecord",
+    "CloudFormationCustomResourceUpdateModel",
+    "CloudFormationCustomResourceDeleteModel",
+    "CloudFormationCustomResourceCreateModel",
+    "CloudFormationCustomResourceBaseModel",
 ]

aws_lambda_powertools/utilities/parser/models/cloudformation_custom_resource.py

@@ -0,0 +1,29 @@
+from typing import Any, Dict, Type, Union
+
+from pydantic import BaseModel, Field, HttpUrl
+
+from aws_lambda_powertools.utilities.parser.types import Literal
+
+
+class CloudFormationCustomResourceBaseModel(BaseModel):
+    request_type: str = Field(..., alias="RequestType")
+    service_token: str = Field(..., alias="ServiceToken")
+    response_url: HttpUrl = Field(..., alias="ResponseURL")
+    stack_id: str = Field(..., alias="StackId")
+    request_id: str = Field(..., alias="RequestId")
+    logical_resource_id: str = Field(..., alias="LogicalResourceId")
+    resource_type: str = Field(..., alias="ResourceType")
+    resource_properties: Union[Dict[str, Any], Type[BaseModel]] = Field(..., alias="ResourceProperties")
+
+
+class CloudFormationCustomResourceCreateModel(CloudFormationCustomResourceBaseModel):
+    request_type: Literal["Create"] = Field(..., alias="RequestType")
+
+
+class CloudFormationCustomResourceDeleteModel(CloudFormationCustomResourceBaseModel):
+    request_type: Literal["Delete"] = Field(..., alias="RequestType")
+
+
+class CloudFormationCustomResourceUpdateModel(CloudFormationCustomResourceBaseModel):
+    request_type: Literal["Update"] = Field(..., alias="RequestType")
+    old_resource_properties: Union[Dict[str, Any], Type[BaseModel]] = Field(..., alias="OldResourceProperties")

docs/utilities/parser.md

@@ -156,27 +156,30 @@ def my_function():
 
 Parser comes with the following built-in models:
 
-| Model name                              | Description                                                                           |
-| --------------------------------------- | ------------------------------------------------------------------------------------- |
-| **AlbModel**                            | Lambda Event Source payload for Amazon Application Load Balancer                      |
-| **APIGatewayProxyEventModel**           | Lambda Event Source payload for Amazon API Gateway                                    |
-| **APIGatewayProxyEventV2Model**         | Lambda Event Source payload for Amazon API Gateway v2 payload                         |
-| **CloudwatchLogsModel**                 | Lambda Event Source payload for Amazon CloudWatch Logs                                |
-| **DynamoDBStreamModel**                 | Lambda Event Source payload for Amazon DynamoDB Streams                               |
-| **EventBridgeModel**                    | Lambda Event Source payload for Amazon EventBridge                                    |
-| **KafkaMskEventModel**                  | Lambda Event Source payload for AWS MSK payload                                       |
-| **KafkaSelfManagedEventModel**          | Lambda Event Source payload for self managed Kafka payload                            |
-| **KinesisDataStreamModel**              | Lambda Event Source payload for Amazon Kinesis Data Streams                           |
-| **KinesisFirehoseModel**                | Lambda Event Source payload for Amazon Kinesis Firehose                               |
-| **KinesisFirehoseSqsModel**             | Lambda Event Source payload for SQS messages wrapped in Kinesis Firehose records      |
-| **LambdaFunctionUrlModel**              | Lambda Event Source payload for Lambda Function URL payload                           |
-| **S3EventNotificationEventBridgeModel** | Lambda Event Source payload for Amazon S3 Event Notification to EventBridge.          |
-| **S3Model**                             | Lambda Event Source payload for Amazon S3                                             |
-| **S3ObjectLambdaEvent**                 | Lambda Event Source payload for Amazon S3 Object Lambda                               |
-| **S3SqsEventNotificationModel**         | Lambda Event Source payload for S3 event notifications wrapped in SQS event (S3->SQS) |
-| **SesModel**                            | Lambda Event Source payload for Amazon Simple Email Service                           |
-| **SnsModel**                            | Lambda Event Source payload for Amazon Simple Notification Service                    |
-| **SqsModel**                            | Lambda Event Source payload for Amazon SQS                                            |
+| Model name                                  | Description                                                                           |
+| ------------------------------------------- | ------------------------------------------------------------------------------------- |
+| **AlbModel**                                | Lambda Event Source payload for Amazon Application Load Balancer                      |
+| **APIGatewayProxyEventModel**               | Lambda Event Source payload for Amazon API Gateway                                    |
+| **APIGatewayProxyEventV2Model**             | Lambda Event Source payload for Amazon API Gateway v2 payload                         |
+| **CloudwatchLogsModel**                     | Lambda Event Source payload for Amazon CloudWatch Logs                                |
+| **DynamoDBStreamModel**                     | Lambda Event Source payload for Amazon DynamoDB Streams                               |
+| **EventBridgeModel**                        | Lambda Event Source payload for Amazon EventBridge                                    |
+| **KafkaMskEventModel**                      | Lambda Event Source payload for AWS MSK payload                                       |
+| **KafkaSelfManagedEventModel**              | Lambda Event Source payload for self managed Kafka payload                            |
+| **KinesisDataStreamModel**                  | Lambda Event Source payload for Amazon Kinesis Data Streams                           |
+| **KinesisFirehoseModel**                    | Lambda Event Source payload for Amazon Kinesis Firehose                               |
+| **KinesisFirehoseSqsModel**                 | Lambda Event Source payload for SQS messages wrapped in Kinesis Firehose records      |
+| **LambdaFunctionUrlModel**                  | Lambda Event Source payload for Lambda Function URL payload                           |
+| **S3EventNotificationEventBridgeModel**     | Lambda Event Source payload for Amazon S3 Event Notification to EventBridge.          |
+| **S3Model**                                 | Lambda Event Source payload for Amazon S3                                             |
+| **S3ObjectLambdaEvent**                     | Lambda Event Source payload for Amazon S3 Object Lambda                               |
+| **S3SqsEventNotificationModel**             | Lambda Event Source payload for S3 event notifications wrapped in SQS event (S3->SQS) |
+| **SesModel**                                | Lambda Event Source payload for Amazon Simple Email Service                           |
+| **SnsModel**                                | Lambda Event Source payload for Amazon Simple Notification Service                    |
+| **SqsModel**                                | Lambda Event Source payload for Amazon SQS                                            |
+| **CloudFormationCustomResourceCreateModel** | Lambda Event Source payload for AWS CloudFormation 'create' custom resource           |
+| **CloudFormationCustomResourceUpdateModel** | Lambda Event Source payload for AWS CloudFormation 'update' custom resource           |
+| **CloudFormationCustomResourceDeleteModel** | Lambda Event Source payload for AWS CloudFormation 'delete' custom resource           |
 
 #### Extending built-in models
 

tests/events/customResourceCreate.json

@@ -0,0 +1,13 @@
+{
+  "RequestType": "Create",
+  "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
+  "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
+  "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
+  "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
+  "LogicalResourceId": "xxxxxxxxx",
+  "ResourceType": "Custom::MyType",
+  "ResourceProperties": {
+    "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+    "MyProps": "ss"
+  }
+}

tests/events/customResourceDelete.json

@@ -0,0 +1,13 @@
+{
+  "RequestType": "Delete",
+  "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
+  "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
+  "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
+  "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
+  "LogicalResourceId": "xxxxxxxxx",
+  "ResourceType": "Custom::MyType",
+  "ResourceProperties": {
+    "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+    "MyProps": "ss"
+  }
+}

tests/events/customResourceUpdate.json

@@ -0,0 +1,17 @@
+{
+  "RequestType": "Update",
+  "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
+  "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
+  "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
+  "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
+  "LogicalResourceId": "xxxxxxxxx",
+  "ResourceType": "Custom::MyType",
+  "ResourceProperties": {
+    "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+    "MyProps": "new"
+  },
+  "OldResourceProperties": {
+    "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx-xxxx-xxx",
+    "MyProps": "old"
+  }
+}

tests/functional/parser/test_custom_resource.py

@@ -0,0 +1,130 @@
+import pytest
+from pydantic import BaseModel, Field
+
+from aws_lambda_powertools.utilities.parser import ValidationError, event_parser
+from aws_lambda_powertools.utilities.parser.models import (
+    CloudFormationCustomResourceCreateModel,
+    CloudFormationCustomResourceDeleteModel,
+    CloudFormationCustomResourceUpdateModel,
+)
+from aws_lambda_powertools.utilities.typing import LambdaContext
+from tests.functional.utils import load_event
+
+
+@event_parser(model=CloudFormationCustomResourceCreateModel)
+def handle_create_custom_resource(event: CloudFormationCustomResourceCreateModel, _: LambdaContext):
+    assert event.request_type == "Create"
+    assert event.request_id == "xxxxx-d2a0-4dfb-ab1f-xxxxxx"
+    assert event.service_token == "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe"
+    assert (
+        str(event.response_url)
+        == "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b"
+    )
+    assert event.stack_id == "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21"
+    assert event.logical_resource_id == "xxxxxxxxx"
+    assert event.resource_type == "Custom::MyType"
+    assert event.resource_properties == {
+        "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+        "MyProps": "ss",
+    }
+
+
+@event_parser(model=CloudFormationCustomResourceUpdateModel)
+def handle_update_custom_resource(event: CloudFormationCustomResourceUpdateModel, _: LambdaContext):
+    assert event.request_type == "Update"
+    assert event.request_id == "xxxxx-d2a0-4dfb-ab1f-xxxxxx"
+    assert event.service_token == "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe"
+    assert (
+        str(event.response_url)
+        == "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b"
+    )
+    assert event.stack_id == "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21"
+    assert event.logical_resource_id == "xxxxxxxxx"
+    assert event.resource_type == "Custom::MyType"
+    assert event.resource_properties == {
+        "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+        "MyProps": "new",
+    }
+    assert event.old_resource_properties == {
+        "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx-xxxx-xxx",
+        "MyProps": "old",
+    }
+
+
+@event_parser(model=CloudFormationCustomResourceDeleteModel)
+def handle_delete_custom_resource(event: CloudFormationCustomResourceDeleteModel, _: LambdaContext):
+    assert event.request_type == "Delete"
+    assert event.request_id == "xxxxx-d2a0-4dfb-ab1f-xxxxxx"
+    assert event.service_token == "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe"
+    assert (
+        str(event.response_url)
+        == "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b"
+    )
+    assert event.stack_id == "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21"
+    assert event.logical_resource_id == "xxxxxxxxx"
+    assert event.resource_type == "Custom::MyType"
+    assert event.resource_properties == {
+        "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+        "MyProps": "ss",
+    }
+
+
+def test_create_trigger_event():
+    event_dict = load_event("customResourceCreate.json")
+    handle_create_custom_resource(event_dict, LambdaContext())
+
+
+def test_update_trigger_event():
+    event_dict = load_event("customResourceUpdate.json")
+    handle_update_custom_resource(event_dict, LambdaContext())
+
+
+def test_delete_trigger_event():
+    event_dict = load_event("customResourceDelete.json")
+    handle_delete_custom_resource(event_dict, LambdaContext())
+
+
+def test_validate_create_event_does_not_conform_with_model():
+    event = {"invalid": "event"}
+    with pytest.raises(ValidationError):
+        handle_create_custom_resource(event, LambdaContext())
+
+
+def test_validate_update_event_does_not_conform_with_model():
+    event = {"invalid": "event"}
+    with pytest.raises(ValidationError):
+        handle_update_custom_resource(event, LambdaContext())
+
+
+def test_validate_delete_event_does_not_conform_with_model():
+    event = {"invalid": "event"}
+    with pytest.raises(ValidationError):
+        handle_delete_custom_resource(event, LambdaContext())
+
+
+class MyModel(BaseModel):
+    MyProps: str
+
+
+class MyCustomResource(CloudFormationCustomResourceCreateModel):
+    resource_properties: MyModel = Field(..., alias="ResourceProperties")
+
+
+@event_parser(model=MyCustomResource)
+def handle_create_custom_resource_extended_model(event: MyCustomResource, _: LambdaContext):
+    assert event.request_type == "Create"
+    assert event.request_id == "xxxxx-d2a0-4dfb-ab1f-xxxxxx"
+    assert event.service_token == "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe"
+    assert (
+        str(event.response_url)
+        == "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b"
+    )
+    assert event.stack_id == "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21"
+    assert event.logical_resource_id == "xxxxxxxxx"
+    assert event.resource_type == "Custom::MyType"
+    assert event.resource_properties.MyProps == "ss"
+
+
+def test_create_trigger_event_custom_model():
+    event_dict = load_event("customResourceCreate.json")
+    handle_create_custom_resource_extended_model(event_dict, LambdaContext())