@aws-cdk/aws-lambda-event-sources

AWS Lambda Event Sources

---

---

This module includes classes that allow using various AWS services as event sources for AWS Lambda via the high-level lambda.addEventSource(source) API.

NOTE: In most cases, it is also possible to use the resource APIs to invoke an AWS Lambda function. This library provides a uniform API for all Lambda event sources regardless of the underlying mechanism they use.

SQS

Amazon Simple Queue Service (Amazon SQS) allows you to build asynchronous workflows. For more information about Amazon SQS, see Amazon Simple Queue Service. You can configure AWS Lambda to poll for these messages as they arrive and then pass the event to a Lambda function invocation. To view a sample event, see Amazon SQS Event.

To set up Amazon Simple Queue Service as an event source for AWS Lambda, you first create or update an Amazon SQS queue and select custom values for the queue parameters. The following parameters will impact Amazon SQS's polling behavior:

• visibilityTimeout: May impact the period between retries.
• receiveMessageWaitTime: Will determine long poll duration. The default value is 20 seconds.

import sqs = require('@aws-cdk/aws-sqs');
import { SqsEventSource } from '@aws-cdk/aws-lambda-event-sources';
import { Duration } from '@aws-cdk/core';

const queue = new sqs.Queue(this, 'MyQueue', {
  visibilityTimeout: Duration.seconds(30)      // default,
  receiveMessageWaitTime: Duration.seconds(20) // default
});

lambda.addEventSource(new SqsEventSource(queue, {
  batchSize: 10 // default
});

S3

You can write Lambda functions to process S3 bucket events, such as the object-created or object-deleted events. For example, when a user uploads a photo to a bucket, you might want Amazon S3 to invoke your Lambda function so that it reads the image and creates a thumbnail for the photo.

You can use the bucket notification configuration feature in Amazon S3 to configure the event source mapping, identifying the bucket events that you want Amazon S3 to publish and which Lambda function to invoke.

import s3 = require('@aws-cdk/aws-s3');
import { S3EventSource } from '@aws-cdk/aws-lambda-event-sources';

const bucket = new s3.Bucket(...);

lambda.addEventSource(new S3EventSource(bucket, {
  events: [ s3.EventType.OBJECT_CREATED, s3.EventType.OBJECT_REMOVED ],
  filters: [ { prefix: 'subdir/' } ] // optional
}));

SNS

You can write Lambda functions to process Amazon Simple Notification Service notifications. When a message is published to an Amazon SNS topic, the service can invoke your Lambda function by passing the message payload as a parameter. Your Lambda function code can then process the event, for example publish the message to other Amazon SNS topics, or send the message to other AWS services.

This also enables you to trigger a Lambda function in response to Amazon CloudWatch alarms and other AWS services that use Amazon SNS.

For an example event, see Appendix: Message and JSON Formats and Amazon SNS Sample Event. For an example use case, see Using AWS Lambda with Amazon SNS from Different Accounts.

import sns = require('@aws-cdk/aws-sns');
import { SnsEventSource } from '@aws-cdk/aws-lambda-event-sources';

const topic = new sns.Topic(...);

lambda.addEventSource(new SnsEventSource(topic));

When a user calls the SNS Publish API on a topic that your Lambda function is subscribed to, Amazon SNS will call Lambda to invoke your function asynchronously. Lambda will then return a delivery status. If there was an error calling Lambda, Amazon SNS will retry invoking the Lambda function up to three times. After three tries, if Amazon SNS still could not successfully invoke the Lambda function, then Amazon SNS will send a delivery status failure message to CloudWatch.

DynamoDB Streams

You can write Lambda functions to process change events from a DynamoDB Table. An event is emitted to a DynamoDB stream (if configured) whenever a write (Put, Delete, Update) operation is performed against the table. See Using AWS Lambda with Amazon DynamoDB for more information.

To process events with a Lambda function, first create or update a DynamoDB table and enable a stream specification. Then, create a DynamoEventSource and add it to your Lambda function. The following parameters will impact Amazon DynamoDB's polling behavior:

• batchSize: Determines how many records are buffered before invoking your lambda function - could impact your function's memory usage (if too high) and ability to keep up with incoming data velocity (if too low).
• startingPosition: Will determine where to being consumption, either at the most recent ('LATEST') record or the oldest record ('TRIM_HORIZON'). 'TRIM_HORIZON' will ensure you process all available data, while 'LATEST' will ignore all reocrds that arrived prior to attaching the event source.

import dynamodb = require('@aws-cdk/aws-dynamodb');
import lambda = require('@aws-cdk/aws-lambda');
import { DynamoEventSource } from '@aws-cdk/aws-lambda-event-sources';

const table = new dynamodb.Table(..., {
  partitionKey: ...,
  stream: dynamodb.StreamViewType.NEW_IMAGE // make sure stream is configured
});

const function = new lambda.Function(...);
function.addEventSource(new DynamoEventSource(table, {
  startingPosition: lambda.StartingPosition.TRIM_HORIZON
}));

Kinesis

You can write Lambda functions to process streaming data in Amazon Kinesis Streams. For more information about Amazon SQS, see Amazon Kinesis Service. To view a sample event, see Amazon SQS Event.

To set up Amazon Kinesis as an event source for AWS Lambda, you first create or update an Amazon Kinesis stream and select custom values for the event source parameters. The following parameters will impact Amazon Kinesis's polling behavior:

• batchSize: Determines how many records are buffered before invoking your lambnda function - could impact your function's memory usage (if too high) and ability to keep up with incoming data velocity (if too low).
• startingPosition: Will determine where to being consumption, either at the most recent ('LATEST') record or the oldest record ('TRIM_HORIZON'). 'TRIM_HORIZON' will ensure you process all available data, while 'LATEST' will ignore all reocrds that arrived prior to attaching the event source.

import lambda = require('@aws-cdk/aws-lambda');
import kinesis = require('@aws-cdk/aws-kinesis');
import { KinesisEventSource } from '@aws-cdk/aws-lambda-event-sources';

const stream = new kinesis.Stream(this, 'MyStream');

myFunction.addEventSource(new KinesisEventSource(queue, {
  batchSize: 100, // default
  startingPosition: lambda.StartingPosition.TRIM_HORIZON
});

Roadmap

Eventually, this module will support all the event sources described under Supported Event Sources in the AWS Lambda Developer Guide.

Changelog

1.18.0 (2019-11-25)

General Availability of AWS CDK for .NET and Java!! 🎉🎉🥂🥂🍾🍾

We are excited to announce the general availability of support for the .NET family of languages (C#, F#, ...) as well as Java!

We want to express our gratitude to all of our early customers as well as the amazing contributors for all the help and support in making this release possible. Thank you for all the feedback provided during the Developer Preview of .NET and Java support, without which the product would not be what it is today.

Special thanks go out to a handful of amazing people who have provided instrumental support in bringing .NET and Java support to this point:

• Aaron Costley
• Ben Maizels
• Daniel Dinu
• Erik Karlsson
• Hamza Assyad
• Jerry Kindall
• Noah Litov
• Richard Boyd

Of course, we continue to be amazed and thrilled by the community contributions we received besides language support. The passion demonstrated by the CDK community is heartwarming and largely contributes to making maintaining the CDK an enjoyable, enriching experience!

Features

• lambda: node12.x, python3.8 and java11 runtimes (#5107) (e62f9fb)
• lambda: unlock the lambda environment variables restriction in China regions (#5122) (cc13009)

Bug Fixes

• init/chsarp: correct README for sample-app C# template (#5144) (b2031f6)
• init/sample-app: numerous fixes and additions to the sample-app init templates (#5119) (02c3b05), closes #5130 #5130
• init/java: add -e to mvn command so errors aren't hidden (#5129) (5427106), closes #5128
• init/csharp: .NET semantic fixes for init templates (#5154) (04a1b32)

Known Issues

The following known issues were identified that specifically affect .NET and Java support in the CDK, and which will be promptly addressed in upcoming CDK releases (in no particular order). See the GitHub issues for more information and workarounds where applicable.

• .NET and Java: [aws/jsii#1011] - abstract members are not marked as such on their .NET and Java representations
• .NET: [aws/jsii#1029] - user-defined classes implementing CDK interfaces must extend Amazon.Jsii.Runtime.Deputy.DeputyBase
• .NET: [aws/jsii#1042] - Parameters typed object accept only primitive types, instances of CDK types, Dictionary<string,?>
• .NET: [aws/jsii#1044] - Unable to pass interface instance through in a Dictionary<string,object>
• Java: [aws/jsii#1034] - Implementing or overriding overloaded methods in Java does not work consistently
• Java: [aws/jsii#1035] - Returning Lazy.anyValue from an method whose return type is java.lang.Object may result in Resolution Errors
• Java: [aws/jsii#1005] - property getter implementations (e.g: from an interface) may be ignored