22 Lambda Utils

README.md

@@ -158,10 +158,35 @@ The project supports multiple environments:
 
 Each environment has its own AWS account and configuration.
 
+## Lambda Utils Project
+
+The `@leanstacks/lambda-utils` package is a TypeScript utility library for AWS Lambda functions. It provides pre-configured logging, API response formatting, configuration validation, and AWS SDK clients—reducing boilerplate and promoting best practices within Node.js Lambda functions.
+
+Several of the Lambda Utils are used in the Lambda Starter application. You are encouraged to use the Lambda Utils library in your project or, if you want to maintain the source code yourself, you may fork the repo or copy only the code you need into your project.
+
+Learn more about the Lambda Utils with these resources...
+
+- **[@leanstacks/lambda-utils package on NPM](https://www.npmjs.com/package/@leanstacks/lambda-utils)**
+- **[lambda-utils repository on GitHub](https://github.com/leanstacks/lambda-utils)**
+
+## Serverless Microservice Patterns
+
+This project implements the **Simple Web Service** serverless microservice pattern. The [Serverless Microservice Patterns repository](https://github.com/leanstacks/serverless-microservice-patterns) provides a comprehensive collection of additional patterns and examples, including:
+
+- **Simple Web Service**: A basic serverless web service pattern using API Gateway, Lambda, and DynamoDB.
+- **Gatekeeper**: Adds an Auth microservice to authenticate and authorize API requests.
+- **Internal API**: Facilitates synchronous, internal microservice-to-microservice integration without API Gateway exposure.
+- **Internal Handoff**: Enables asynchronous microservice-to-microservice communication.
+- **Publish Subscribe**: Demonstrates event-driven architecture using SNS topics and SQS queues for loose coupling.
+- **Queue-Based Load Leveling**: Uses a message queue as a buffer to decouple producers from consumers and smooth demand spikes.
+
+Each pattern is implemented as a standalone project with practical examples and reference implementations for building scalable, event-driven microservices on AWS.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## Further Reading
 
-- [Project Documentation](./docs/README.md)
+- [**Lambda Utils Project**](https://github.com/leanstacks/lambda-utils)
+- [**Project Documentation**](./docs/README.md)

docs/ConfigurationGuide.md

@@ -10,14 +10,15 @@ The application configuration is managed through environment variables. These va
 
 The following environment variables are available for configuring the application:
 
-| Variable            | Type    | Description                                      | Default     | Required |
-| ------------------- | ------- | ------------------------------------------------ | ----------- | -------- |
-| `TASKS_TABLE`       | string  | The name of the DynamoDB table for storing tasks | -           | Yes      |
-| `AWS_REGION`        | string  | The AWS region where resources are deployed      | `us-east-1` | No       |
-| `LOGGING_ENABLED`   | boolean | Enable or disable application logging            | `true`      | No       |
-| `LOGGING_LEVEL`     | enum    | Logging level: `debug`, `info`, `warn`, `error`  | `debug`     | No       |
-| `LOGGING_FORMAT`    | enum    | Logging format: `text`, `json`                   | `json`      | No       |
-| `CORS_ALLOW_ORIGIN` | string  | CORS allow origin header value                   | `*`         | No       |
+| Variable               | Type    | Description                                      | Default     | Required |
+| ---------------------- | ------- | ------------------------------------------------ | ----------- | -------- |
+| `TASKS_TABLE`          | string  | The name of the DynamoDB table for storing tasks | -           | Yes      |
+| `TASK_EVENT_TOPIC_ARN` | string  | The ARN of the SNS topic for task events         | -           | Yes      |
+| `AWS_REGION`           | string  | The AWS region where resources are deployed      | `us-east-1` | No       |
+| `LOGGING_ENABLED`      | boolean | Enable or disable application logging            | `true`      | No       |
+| `LOGGING_LEVEL`        | enum    | Logging level: `debug`, `info`, `warn`, `error`  | `debug`     | No       |
+| `LOGGING_FORMAT`       | enum    | Logging format: `text`, `json`                   | `json`      | No       |
+| `CORS_ALLOW_ORIGIN`    | string  | CORS allow origin header value                   | `*`         | No       |
 
 ### Usage
 
@@ -27,6 +28,7 @@ Application configuration is accessed through the `config` object exported from
 import { config } from './utils/config';
 
 console.log(`Tasks table: ${config.TASKS_TABLE}`);
+console.log(`Task event topic ARN: ${config.TASK_EVENT_TOPIC_ARN}`);
 console.log(`Logging enabled: ${config.LOGGING_ENABLED}`);
 ```
 
@@ -155,6 +157,7 @@ Infrastructure configuration variables are passed to Lambda functions with modif
 | `CDK_APP_LOGGING_FORMAT`  | `LOGGING_FORMAT`            |
 | `CDK_CORS_ALLOW_ORIGIN`   | `CORS_ALLOW_ORIGIN`         |
 | (DynamoDB table name)     | `TASKS_TABLE`               |
+| (SNS topic ARN)           | `TASK_EVENT_TOPIC_ARN`      |
 | (AWS Region)              | `AWS_REGION`                |
 
 ---

docs/InfrastructureGuide.md

@@ -11,6 +11,7 @@ The infrastructure is organized into two main AWS CDK stacks:
 | Stack Name Pattern        | Purpose                                    |
 | ------------------------- | ------------------------------------------ |
 | `{app-name}-data-{env}`   | Manages DynamoDB tables and data resources |
+| `{app-name}-sns-{env}`    | Manages SNS topics for messaging           |
 | `{app-name}-lambda-{env}` | Manages Lambda functions and API Gateway   |
 
 ---
@@ -34,6 +35,24 @@ The infrastructure is organized into two main AWS CDK stacks:
 
 ---
 
+## SNS Stack
+
+**Purpose:** Manages SNS topics for messaging and event publishing.
+
+**Key Resources:**
+
+| Resource  | Name Pattern                  | Key Properties                                    |
+| --------- | ----------------------------- | ------------------------------------------------- |
+| SNS Topic | `{app-name}-task-event-{env}` | Standard (non-FIFO) topic, AWS-managed encryption |
+
+**Outputs:**
+
+| Output Name         | Export Name Pattern                     | Description                     |
+| ------------------- | --------------------------------------- | ------------------------------- |
+| `TaskEventTopicArn` | `{app-name}-task-event-topic-arn-{env}` | Task Event Topic ARN (exported) |
+
+---
+
 ## Lambda Stack
 
 **Purpose:** Manages Lambda functions, API Gateway, and application runtime resources.
@@ -49,6 +68,19 @@ The infrastructure is organized into two main AWS CDK stacks:
 | Lambda Function | `{app-name}-delete-task-{env}` | Delete a task (DynamoDB DeleteItem)  |
 | API Gateway     | `{app-name}-api-{env}`         | REST API for Lambda functions        |
 
+**Environment Variables Passed to Lambda Functions:**
+
+All Lambda functions receive the following environment variables from the CDK configuration:
+
+| Variable               | Source                    | Purpose                                  |
+| ---------------------- | ------------------------- | ---------------------------------------- |
+| `TASKS_TABLE`          | Data Stack output         | DynamoDB table name for tasks            |
+| `TASK_EVENT_TOPIC_ARN` | SNS Stack output          | SNS topic ARN for publishing task events |
+| `LOGGING_ENABLED`      | `CDK_APP_LOGGING_ENABLED` | Enable/disable application logging       |
+| `LOGGING_LEVEL`        | `CDK_APP_LOGGING_LEVEL`   | Application logging level                |
+| `LOGGING_FORMAT`       | `CDK_APP_LOGGING_FORMAT`  | Application logging format               |
+| `CORS_ALLOW_ORIGIN`    | `CDK_CORS_ALLOW_ORIGIN`   | CORS allow origin header value           |
+
 **Outputs:**
 
 | Output Name             | Export Name Pattern                | Description                     |

infrastructure/app.ts

@@ -4,6 +4,7 @@ import * as cdk from 'aws-cdk-lib';
 
 import { getConfig, getEnvironmentConfig, getTags } from './utils/config';
 import { DataStack } from './stacks/data-stack';
+import { SnsStack } from './stacks/sns-stack';
 import { LambdaStack } from './stacks/lambda-stack';
 
 // Load and validate configuration
@@ -27,13 +28,23 @@ const dataStack = new DataStack(app, `${config.CDK_APP_NAME}-data-stack-${config
   ...(environmentConfig && { env: environmentConfig }),
 });
 
+// Create SNS Stack
+const snsStack = new SnsStack(app, `${config.CDK_APP_NAME}-sns-stack-${config.CDK_ENV}`, {
+  appName: config.CDK_APP_NAME,
+  envName: config.CDK_ENV,
+  stackName: `${config.CDK_APP_NAME}-sns-${config.CDK_ENV}`,
+  description: `SNS resources for ${config.CDK_APP_NAME} (${config.CDK_ENV})`,
+  ...(environmentConfig && { env: environmentConfig }),
+});
+
 // Create Lambda Stack
 new LambdaStack(app, `${config.CDK_APP_NAME}-lambda-stack-${config.CDK_ENV}`, {
   appName: config.CDK_APP_NAME,
   envName: config.CDK_ENV,
   stackName: `${config.CDK_APP_NAME}-lambda-${config.CDK_ENV}`,
   description: `Lambda functions and API Gateway for ${config.CDK_APP_NAME} (${config.CDK_ENV})`,
   taskTable: dataStack.taskTable,
+  taskEventTopic: snsStack.taskEventTopic,
   loggingEnabled: config.CDK_APP_LOGGING_ENABLED,
   loggingLevel: config.CDK_APP_LOGGING_LEVEL,
   loggingFormat: config.CDK_APP_LOGGING_FORMAT,

infrastructure/package.json

@@ -31,7 +31,7 @@
     "typescript": "5.9.3"
   },
   "dependencies": {
-    "aws-cdk-lib": "2.232.2",
+    "aws-cdk-lib": "2.233.0",
     "constructs": "10.4.4",
     "dotenv": "17.2.3",
     "source-map-support": "0.5.21",

infrastructure/stacks/lambda-stack.test.ts

@@ -1,6 +1,7 @@
 import * as cdk from 'aws-cdk-lib';
 import { Match, Template } from 'aws-cdk-lib/assertions';
 import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import * as sns from 'aws-cdk-lib/aws-sns';
 import { LambdaStack } from './lambda-stack';
 
 // Mock NodejsFunction to avoid Docker bundling during tests
@@ -35,11 +36,15 @@ describe('LambdaStack', () => {
           type: dynamodb.AttributeType.STRING,
         },
       });
+      const testMockTopic = new sns.Topic(mockTestStack, 'MockTaskEventTopic', {
+        topicName: 'mock-task-event-dev',
+      });
 
       const stack = new LambdaStack(testApp, 'TestLambdaStack', {
         appName: 'lambda-starter',
         envName: 'dev',
         taskTable: testMockTable,
+        taskEventTopic: testMockTopic,
         loggingEnabled: true,
         loggingLevel: 'debug',
         loggingFormat: 'json',
@@ -103,6 +108,7 @@ describe('LambdaStack', () => {
         Environment: {
           Variables: {
             TASKS_TABLE: Match.anyValue(),
+            TASK_EVENT_TOPIC_ARN: Match.anyValue(),
             LOGGING_ENABLED: 'true',
             LOGGING_LEVEL: 'debug',
             LOGGING_FORMAT: 'json',
@@ -218,6 +224,45 @@ describe('LambdaStack', () => {
       });
     });
 
+    it('should grant Lambda SNS publish permissions for create function', () => {
+      template.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+          Statement: Match.arrayWith([
+            Match.objectLike({
+              Action: 'sns:Publish',
+              Resource: Match.anyValue(),
+            }),
+          ]),
+        },
+      });
+    });
+
+    it('should grant Lambda SNS publish permissions for update function', () => {
+      template.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+          Statement: Match.arrayWith([
+            Match.objectLike({
+              Action: 'sns:Publish',
+              Resource: Match.anyValue(),
+            }),
+          ]),
+        },
+      });
+    });
+
+    it('should grant Lambda SNS publish permissions for delete function', () => {
+      template.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+          Statement: Match.arrayWith([
+            Match.objectLike({
+              Action: 'sns:Publish',
+              Resource: Match.anyValue(),
+            }),
+          ]),
+        },
+      });
+    });
+
     it('should export API URL', () => {
       template.hasOutput('ApiUrl', {
         Export: {
@@ -311,11 +356,15 @@ describe('LambdaStack', () => {
           type: dynamodb.AttributeType.STRING,
         },
       });
+      const testMockTopic = new sns.Topic(mockTestStack, 'MockTaskEventTopic', {
+        topicName: 'mock-task-event-prd',
+      });
 
       const stack = new LambdaStack(testApp, 'TestLambdaStack', {
         appName: 'lambda-starter',
         envName: 'prd',
         taskTable: testMockTable,
+        taskEventTopic: testMockTopic,
         loggingEnabled: true,
         loggingLevel: 'info',
         loggingFormat: 'json',
@@ -367,11 +416,15 @@ describe('LambdaStack', () => {
           type: dynamodb.AttributeType.STRING,
         },
       });
+      const testMockTopic = new sns.Topic(mockTestStack, 'MockTaskEventTopic', {
+        topicName: 'mock-task-event-dev',
+      });
 
       const stack = new LambdaStack(testApp, 'TestLambdaStack', {
         appName: 'lambda-starter',
         envName: 'dev',
         taskTable: testMockTable,
+        taskEventTopic: testMockTopic,
         loggingEnabled: true,
         loggingLevel: 'debug',
         loggingFormat: 'json',

infrastructure/stacks/lambda-stack.ts

@@ -4,6 +4,7 @@ import * as apigateway from 'aws-cdk-lib/aws-apigateway';
 import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
 import * as lambda from 'aws-cdk-lib/aws-lambda';
 import * as logs from 'aws-cdk-lib/aws-logs';
+import * as sns from 'aws-cdk-lib/aws-sns';
 import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
 import { Construct } from 'constructs';
 
@@ -26,6 +27,11 @@ export interface LambdaStackProps extends cdk.StackProps {
    */
   taskTable: dynamodb.ITable;
 
+  /**
+   * Reference to the Task Event SNS topic.
+   */
+  taskEventTopic: sns.ITopic;
+
   /**
    * Whether to enable application logging.
    */
@@ -92,6 +98,7 @@ export class LambdaStack extends cdk.Stack {
       entry: path.join(__dirname, '../../src/handlers/list-tasks.ts'),
       environment: {
         TASKS_TABLE: props.taskTable.tableName,
+        TASK_EVENT_TOPIC_ARN: props.taskEventTopic.topicArn,
         LOGGING_ENABLED: props.loggingEnabled.toString(),
         LOGGING_LEVEL: props.loggingLevel,
         LOGGING_FORMAT: props.loggingFormat,
@@ -124,6 +131,7 @@ export class LambdaStack extends cdk.Stack {
       entry: path.join(__dirname, '../../src/handlers/get-task.ts'),
       environment: {
         TASKS_TABLE: props.taskTable.tableName,
+        TASK_EVENT_TOPIC_ARN: props.taskEventTopic.topicArn,
         LOGGING_ENABLED: props.loggingEnabled.toString(),
         LOGGING_LEVEL: props.loggingLevel,
         LOGGING_FORMAT: props.loggingFormat,
@@ -156,6 +164,7 @@ export class LambdaStack extends cdk.Stack {
       entry: path.join(__dirname, '../../src/handlers/create-task.ts'),
       environment: {
         TASKS_TABLE: props.taskTable.tableName,
+        TASK_EVENT_TOPIC_ARN: props.taskEventTopic.topicArn,
         LOGGING_ENABLED: props.loggingEnabled.toString(),
         LOGGING_LEVEL: props.loggingLevel,
         LOGGING_FORMAT: props.loggingFormat,
@@ -180,6 +189,9 @@ export class LambdaStack extends cdk.Stack {
     // Grant the Lambda function write access to the DynamoDB table
     props.taskTable.grantWriteData(this.createTaskFunction);
 
+    // Grant the Lambda function permission to publish to the SNS topic
+    props.taskEventTopic.grantPublish(this.createTaskFunction);
+
     // Create the update task Lambda function
     this.updateTaskFunction = new NodejsFunction(this, 'UpdateTaskFunction', {
       functionName: `${props.appName}-update-task-${props.envName}`,
@@ -188,6 +200,7 @@ export class LambdaStack extends cdk.Stack {
       entry: path.join(__dirname, '../../src/handlers/update-task.ts'),
       environment: {
         TASKS_TABLE: props.taskTable.tableName,
+        TASK_EVENT_TOPIC_ARN: props.taskEventTopic.topicArn,
         LOGGING_ENABLED: props.loggingEnabled.toString(),
         LOGGING_LEVEL: props.loggingLevel,
         LOGGING_FORMAT: props.loggingFormat,
@@ -212,6 +225,9 @@ export class LambdaStack extends cdk.Stack {
     // Grant the Lambda function read and write access to the DynamoDB table
     props.taskTable.grantReadWriteData(this.updateTaskFunction);
 
+    // Grant the Lambda function permission to publish to the SNS topic
+    props.taskEventTopic.grantPublish(this.updateTaskFunction);
+
     // Create the delete task Lambda function
     this.deleteTaskFunction = new NodejsFunction(this, 'DeleteTaskFunction', {
       functionName: `${props.appName}-delete-task-${props.envName}`,
@@ -220,6 +236,7 @@ export class LambdaStack extends cdk.Stack {
       entry: path.join(__dirname, '../../src/handlers/delete-task.ts'),
       environment: {
         TASKS_TABLE: props.taskTable.tableName,
+        TASK_EVENT_TOPIC_ARN: props.taskEventTopic.topicArn,
         LOGGING_ENABLED: props.loggingEnabled.toString(),
         LOGGING_LEVEL: props.loggingLevel,
         LOGGING_FORMAT: props.loggingFormat,
@@ -244,6 +261,9 @@ export class LambdaStack extends cdk.Stack {
     // Grant the Lambda function read and write access to the DynamoDB table
     props.taskTable.grantReadWriteData(this.deleteTaskFunction);
 
+    // Grant the Lambda function permission to publish to the SNS topic
+    props.taskEventTopic.grantPublish(this.deleteTaskFunction);
+
     // Create API Gateway REST API
     this.api = new apigateway.RestApi(this, 'LambdaStarterApi', {
       restApiName: `${props.appName}-api-${props.envName}`,