Avnishamzn/Saptob feature ddbstream lambda sfn cdk ts

ddbstream-lambda-sfn-cdk-ts/README.md

@@ -0,0 +1,152 @@
+
+# Amazon DynamoDB Stream to AWS Step Functions Trigger
+
+This Pattern demonstrates how to automatically trigger AWS Step Functions workflows in response to changes in DynamoDB tables. The CDK construct `DynamoWorkflowTrigger` lets you connect DynamoDB and Step Functions by allowing you to define event handlers that monitor specific changes in your DynamoDB tables and trigger workflows in response. It leverages Lambda functions to evaluate conditions and start Step Functions state machines with inputs derived from the DynamoDB events.
+
+Learn more about this pattern at Serverless Land Patterns: [https://serverlessland.com/patterns/ddbstream-lambda-sfn-cdk-ts](https://serverlessland.com/patterns/ddbstream-lambda-sfn-cdk-ts)
+
+Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
+
+## Requirements
+
+* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
+* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
+* [Node and NPM](https://nodejs.org/en/download/) installed
+* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+* [AWS Cloud Development Kit](https://docs.aws.amazon.com/cdk/latest/guide/cli.html) (AWS CDK) installed
+
+## Deployment Instructions
+
+1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
+    ```
+    git clone https://github.com/aws-samples/serverless-patterns
+    ```
+2. Change directory to the pattern directory:
+    ```
+    cd ddbstream-lambda-sfn-cdk-ts
+    ```
+3. To deploy from the command line use the following:
+    ```bash
+      npm install
+      npm run lambda
+      cdk deploy
+    ```
+    **The deployment will take a couple of minutes**
+
+4. Note the outputs from the CDK deployment process. These contain the `<table_name>`, `<state-machine-arn>` and `<lambda-function-name>` which are used for testing.
+
+
+
+## How It Works
+
+![Architecture Diagram](ddbstream-lambda-sfn-cdk-ts.png)
+
+The `DdbstreamLambdaSfnExampleStack` demonstrates how to use the the pattern:
+
+1. It creates a DynamoDB table (`TestTable`) with streaming enabled
+2. It creates a simple Step Functions state machine (`TestStateMachine`)
+3. It sets up a trigger with the following behavior:
+   - It applies a filter to ignore events where a `SkipMe` attribute exists in the new image
+   - It only processes `MODIFY` events (updates to existing items)
+   - It checks two conditions:
+     - The new value of `testKey` must be "test8"
+     - The old value of `testKey` must have been "test9"
+   - When all conditions are met, it triggers the state machine with input parameters extracted from the DynamoDB event:
+     - `Index` taken from the item's partition key
+     - `MapAttribute` taken from the first element in a list attribute
+
+This workflow allows you to respond to specific data changes in DynamoDB by executing custom workflows with Step Functions.
+
+
+#### Features
+
+- Dead letter queue for failed invocations
+- VPC support
+- Custom security groups
+- Fine-grained event filtering
+- Multiple event handlers per construct
+- JSONPath-based condition evaluation
+- Input mapping for state machines
+
+#### Limitations
+
+- Tables must have streams enabled with `NEW_AND_OLD_IMAGES`
+- Conditions currently only support exact matches via the `value` property
+- For complex filtering, use Lambda event source filters
+
+## Testing
+
+You can test the workflow using the AWS CLI to create and modify items in the DynamoDB table. Here are some example commands to test different scenarios:
+
+1. First, create an item that shouldn't trigger the workflow (initial state):
+```bash
+aws dynamodb put-item \
+    --table-name <table_name> \
+    --item '{ 
+        "Index": {"S": "test-item-1"},
+        "testKey": {"S": "test9"},
+        "ListAttribute": {"L": [{"S": "first-element"}]}
+    }'
+```
+
+2. Update the item to trigger the workflow (meets all conditions):
+```bash
+aws dynamodb update-item \
+    --table-name <table_name> \
+    --key '{"Index": {"S": "test-item-1"}}' \
+    --update-expression "SET testKey = :newval" \
+    --expression-attribute-values '{":newval": {"S": "test8"}}'
+```
+
+3. Test the SkipMe filter by creating an item that should be ignored:
+```bash
+aws dynamodb put-item \
+    --table-name <table_name> \
+    --item '{ 
+        "Index": {"S": "test-item-2"},
+        "testKey": {"S": "test9"},
+        "SkipMe": {"S": "true"}
+    }'
+```
+This should not trigger DDBEventTrigger lambda at all.  
+
+To verify the results:
+
+1. Check if the Step Function was triggered:
+```bash
+aws stepfunctions list-executions \
+    --state-machine-arn <state-machine-arn>
+```
+
+2. View the execution details:
+```bash
+aws stepfunctions get-execution-history \
+    --execution-arn <execution-arn-from-previous-command>
+```
+
+3. Monitor Lambda function logs:
+```bash
+aws logs tail /aws/lambda/<lambda-function-name> --follow
+```
+
+
+#### Troubleshooting
+
+- Check Amazon CloudWatch Logs for the Lambda function
+- Monitor the dead letter queue for failed events
+- Ensure Amazon IAM permissions are correct for DynamoDB stream access and Step Functions execution
+
+## Cleanup
+
+1. From the command line, use the following in the source folder
+    ```bash
+    cdk destroy
+    ```
+2. Confirm the removal and wait for the resource deletion to complete.
+----
+
+
+
+Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: MIT-0

ddbstream-lambda-sfn-cdk-ts/app.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import { DdbstreamLambdaSfnExampleStack } from './src/lib/ddbstream-lambda-sfn-example-stack';
+
+const app = new cdk.App();
+new DdbstreamLambdaSfnExampleStack(app, 'DDBEventTrigger', {
+  /* If you don't specify 'env', this stack will be environment-agnostic.
+   * Account/Region-dependent features and context lookups will not work,
+   * but a single synthesized template can be deployed anywhere. */
+
+  /* Uncomment the next line to specialize this stack for the AWS Account
+   * and Region that are implied by the current CLI configuration. */
+  // env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
+
+  /* Uncomment the next line if you know exactly what Account and Region you
+   * want to deploy the stack to. */
+  //env: { account: 'AWS_ACCOUNT', region: 'REGION' },
+
+  /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
+});

ddbstream-lambda-sfn-cdk-ts/cdk.json

@@ -0,0 +1,50 @@
+{
+    "app": "npx ts-node --prefer-ts-exts app.ts",
+    "watch": {
+      "include": [
+        "**"
+      ],
+      "exclude": [
+        "README.md",
+        "cdk*.json",
+        "**/*.d.ts",
+        "**/*.js",
+        "tsconfig.json",
+        "package*.json",
+        "yarn.lock",
+        "node_modules",
+        "test"
+      ]
+    },
+    "context": {
+      "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
+      "@aws-cdk/core:checkSecretUsage": true,
+      "@aws-cdk/core:target-partitions": [
+        "aws",
+        "aws-cn"
+      ],
+      "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
+      "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
+      "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
+      "@aws-cdk/aws-iam:minimizePolicies": true,
+      "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
+      "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
+      "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
+      "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
+      "@aws-cdk/aws-apigateway:disableCloudWatchRole": true,
+      "@aws-cdk/core:enablePartitionLiterals": true,
+      "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
+      "@aws-cdk/aws-iam:standardizedServicePrincipals": true,
+      "@aws-cdk/aws-ecs:disableExplicitDeploymentControllerForCircuitBreaker": true,
+      "@aws-cdk/aws-iam:importedRoleStackSafeDefaultPolicyName": true,
+      "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true,
+      "@aws-cdk/aws-route53-patters:useCertificate": true,
+      "@aws-cdk/customresources:installLatestAwsSdkDefault": false,
+      "@aws-cdk/aws-rds:databaseProxyUniqueResourceName": true,
+      "@aws-cdk/aws-codedeploy:removeAlarmsFromDeploymentGroup": true,
+      "@aws-cdk/aws-apigateway:authorizerChangeDeploymentLogicalId": true,
+      "@aws-cdk/aws-ec2:launchTemplateDefaultUserData": true,
+      "@aws-cdk/aws-secretsmanager:useAttachedSecretResourcePolicyForSecretTargetAttachments": true,
+      "@aws-cdk/aws-redshift:columnId": true
+    }
+  }

ddbstream-lambda-sfn-cdk-ts/example-pattern.json

@@ -0,0 +1,72 @@
+{
+  "title": "Amazon DynamoDB Stream to AWS Step Functions Trigger",
+  "description": "Automatically trigger AWS Step Functions workflows in response to changes in DynamoDB tables using a CDK construct that connects DynamoDB and Step Functions.",
+  "language": "TypeScript",
+  "level": "300",
+  "framework": "AWS CDK",
+  "introBox": {
+    "headline": "How it works",
+    "text": [
+      "This pattern demonstrates how to automatically trigger AWS Step Functions workflows in response to changes in DynamoDB tables.",
+      "The CDK construct 'DynamoWorkflowTrigger' connects DynamoDB and Step Functions by allowing you to define event handlers that monitor specific changes in your DynamoDB tables.",
+      "It leverages Lambda functions to evaluate conditions and start Step Functions state machines with inputs derived from the DynamoDB events.",
+      "The pattern includes features like dead letter queues, VPC support, custom security groups, and fine-grained event filtering."
+    ]
+  },
+  "gitHub": {
+    "template": {
+      "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/ddbstream-lambda-sfn-cdk-ts",
+      "templateURL": "serverless-patterns/ddbstream-lambda-sfn-cdk-ts",
+      "projectFolder": "ddbstream-lambda-sfn-cdk-ts",
+      "templateFile": "lib/ddbstream-lambda-sfn-example-stack.ts"
+    }
+  },
+  "resources": {
+    "bullets": [
+      {
+        "text": "AWS DynamoDB Streams Documentation",
+        "link": "https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html"
+      },
+      {
+        "text": "AWS Step Functions Documentation",
+        "link": "https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html"
+      },
+      {
+        "text": "AWS CDK Documentation",
+        "link": "https://docs.aws.amazon.com/cdk/latest/guide/home.html"
+      }
+    ]
+  },
+  "deploy": {
+    "text": [
+      "Clone the repository: <code>git clone https://github.com/aws-samples/serverless-patterns</code>",
+      "Change directory: <code>cd ddbstream-lambda-sfn-cdk-ts</code>",
+      "Install dependencies: <code>npm install && npm run lambda</code>",
+      "Deploy the CDK stack: <code>cdk deploy</code>"
+    ]
+  },
+  "testing": {
+    "text": [
+      "1. Create an initial item in DynamoDB: <code>aws dynamodb put-item --table-name <table_name> --item '{ \"Index\": {\"S\": \"test-item-1\"}, \"testKey\": {\"S\": \"test9\"}, \"ListAttribute\": {\"L\": [{\"S\": \"first-element\"}]} }'</code>",
+      "2. Update the item to trigger workflow: <code>aws dynamodb update-item --table-name <table_name> --key '{\"Index\": {\"S\": \"test-item-1\"}}' --update-expression \"SET testKey = :newval\" --expression-attribute-values '{\":newval\": {\"S\": \"test8\"}}'</code>",
+      "3. Check Step Functions execution: <code>aws stepfunctions list-executions --state-machine-arn <state-machine-arn></code>",
+      "4. Monitor Lambda logs: <code>aws logs tail /aws/lambda/<lambda-function-name> --follow</code>"
+    ]
+  },
+  "cleanup": {
+    "text": ["Delete the stack: <code>cdk destroy</code>"]
+  },
+  "authors": [
+    {
+      "name": "Avnish Kumar",
+      "image": "https://i.postimg.cc/W1SVxLxR/avnish-profile.jpg",
+      "bio": "Senior Software Engineer, Amazon Web Services",
+      "linkedin": "avnish-kumar-40a54328"
+    },
+    {
+      "name": "Saptarshi Banerjee",
+      "bio": "Senior Solutions Architect, Amazon Web Services",
+      "linkedin": "saptarshi-banerjee-83472679"
+    }
+  ]
+}

ddbstream-lambda-sfn-cdk-ts/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "ddbstream-lambda-sfn-cdk-ts",
+  "version": "0.1.0",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "jest",
+    "lambda": "cd ./src/lambda && npm i"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "22.7.9",
+    "aws-cdk-lib": "2.195.0",
+    "@types/aws-lambda": "^8.10.102",
+    "constructs": "^10.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "~5.6.3"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "2.195.0",
+    "constructs": "^10.0.0"
+  }
+}