Skip to content

feat(aws-lambda-polly): new construct #1458

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
biffgaut merged 10 commits into from
Feb 9, 2026
Merged

feat(aws-lambda-polly): new construct #1458

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
a6c6ec1
Initial framework created
biffgaut Feb 4, 2026
21d379f
Implementation
biffgaut Feb 5, 2026
6180844
Add README.md, drop property tests
biffgaut Feb 5, 2026
d55ab00
Refresh integration tests with inline Lambda code
biffgaut Feb 5, 2026
ae35efa
Destroy S3 bucket in integration tests, Suppress cfnguard messages fo…
biffgaut Feb 5, 2026
ab3fd89
Suppress more Custom Resource Lambda function cfnguard warnings
biffgaut Feb 5, 2026
380de39
Encrypt test SNS topic
biffgaut Feb 5, 2026
25e3fa3
Change name of integration test
biffgaut Feb 6, 2026
243dc67
Add architecture diagrams and publish docs
biffgaut Feb 6, 2026
4e5bf0e
Add Polly example, fix example links
biffgaut Feb 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
671 changes: 671 additions & 0 deletions .kiro/specs/aws-lambda-polly/design.md
View file
Open in desktop

Large diffs are not rendered by default.

189 changes: 189 additions & 0 deletions .kiro/specs/aws-lambda-polly/requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
# Requirements Document

## Introduction

This document specifies the requirements for the aws-lambda-polly AWS Solutions Construct. This construct integrates AWS Lambda with Amazon Polly (text-to-speech service), providing a well-architected pattern for building applications that convert text to speech. The construct creates a Lambda function with appropriate IAM permissions to call Polly APIs. When asynchronous job support is enabled, it also creates an S3 bucket for storing audio output and an SNS topic for receiving completion notifications from asynchronous synthesis tasks.

## Glossary

- **Lambda_Function**: The AWS Lambda function that invokes Amazon Polly APIs
- **Polly_Service**: Amazon Polly text-to-speech service
- **Output_Bucket**: S3 bucket for storing audio files generated by Polly (async jobs only)
- **Notification_Topic**: SNS topic for receiving completion notifications from asynchronous Polly tasks (async jobs only)
- **Construct**: The aws-lambda-polly CDK construct
- **Client**: Developer using the construct
- **Synchronous_API**: Polly's SynthesizeSpeech API for immediate text-to-speech conversion
- **Asynchronous_API**: Polly's StartSpeechSynthesisTask API for longer text processing
- **VPC**: Virtual Private Cloud for network isolation

## Requirements

### Requirement 1: Lambda Function Deployment

**User Story:** As a developer, I want to deploy a Lambda function configured to call Amazon Polly, so that I can convert text to speech in my application.

#### Acceptance Criteria

1. WHEN a Client provides lambdaFunctionProps, THE Construct SHALL create a Lambda_Function with those properties
2. WHEN a Client provides existingLambdaObj, THE Construct SHALL use that Lambda_Function instance
3. WHEN a Client provides both existingLambdaObj and lambdaFunctionProps, THE Construct SHALL reject the configuration with an error
4. WHEN neither existingLambdaObj nor lambdaFunctionProps is provided, THE Construct SHALL create a Lambda_Function with best-practice defaults
5. THE Construct SHALL expose the Lambda_Function as a public property

### Requirement 2: Asynchronous Job Support

**User Story:** As a developer, I want to enable asynchronous Polly synthesis tasks, so that I can process longer text documents that exceed the synchronous API limits.

#### Acceptance Criteria

1. WHEN asyncJobs is true, THE Construct SHALL create an Output_Bucket for storing audio files
2. WHEN asyncJobs is true, THE Construct SHALL create a Notification_Topic for receiving completion notifications
3. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permissions for synchronous and asynchronous Polly APIs
4. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT create an Output_Bucket
5. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT create a Notification_Topic
6. WHEN asyncJobs is false or not provided, THE Construct SHALL grant the Lambda_Function permissions only for synchronous Polly APIs

### Requirement 3: S3 Bucket for Audio Output

**User Story:** As a developer with asyncJobs enabled, I want an S3 bucket for storing Polly audio output, so that asynchronous synthesis tasks have a destination for generated files.

#### Acceptance Criteria

1. WHEN asyncJobs is true and bucketProps is provided, THE Construct SHALL create an Output_Bucket with those properties
2. WHEN asyncJobs is true and existingBucketObj is provided, THE Construct SHALL use that Output_Bucket interface
3. WHEN asyncJobs is true and both existingBucketObj and bucketProps are provided, THE Construct SHALL reject the configuration with an error
4. WHEN asyncJobs is true and neither existingBucketObj nor bucketProps is provided, THE Construct SHALL create an Output_Bucket with encryption, versioning, and access logging enabled
5. WHEN asyncJobs is true and the Construct creates an Output_Bucket, THE Construct SHALL expose the bucket as a public property of type s3.Bucket
6. WHEN asyncJobs is true, THE Construct SHALL expose the bucket interface as a public property of type s3.IBucket
7. WHEN asyncJobs is true and the Construct creates a logging bucket, THE Construct SHALL expose the logging bucket as a public property of type s3.Bucket
8. WHEN asyncJobs is false or not provided, THE Construct SHALL ignore bucketProps and existingBucketObj

### Requirement 4: SNS Topic for Notifications

**User Story:** As a developer with asyncJobs enabled, I want an SNS topic for receiving Polly task completion notifications, so that I can process audio files when asynchronous synthesis completes.

#### Acceptance Criteria

1. WHEN asyncJobs is true and topicProps is provided, THE Construct SHALL create a Notification_Topic with those properties
2. WHEN asyncJobs is true and existingTopicObj is provided, THE Construct SHALL use that Notification_Topic instance
3. WHEN asyncJobs is true and both existingTopicObj and topicProps are provided, THE Construct SHALL reject the configuration with an error
4. WHEN asyncJobs is true and neither existingTopicObj nor topicProps is provided, THE Construct SHALL create a Notification_Topic with encryption enabled
5. WHEN asyncJobs is true, THE Construct SHALL expose the Notification_Topic as a public property
6. WHEN asyncJobs is false or not provided, THE Construct SHALL ignore topicProps and existingTopicObj

### Requirement 5: IAM Permissions for Synchronous Polly APIs

**User Story:** As a developer, I want the Lambda function to have least-privilege permissions to call synchronous Polly APIs, so that my application is secure and follows AWS best practices.

#### Acceptance Criteria

1. THE Construct SHALL grant the Lambda_Function permission to call polly:SynthesizeSpeech
2. THE Construct SHALL NOT grant the Lambda_Function permission to pass IAM roles to Polly_Service

### Requirement 6: IAM Permissions for Asynchronous Polly APIs

**User Story:** As a developer with asyncJobs enabled, I want the Lambda function to have permissions to call asynchronous Polly APIs, so that I can start and monitor long-running synthesis tasks.

#### Acceptance Criteria

1. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permission to call polly:StartSpeechSynthesisTask
2. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permission to call polly:GetSpeechSynthesisTask
3. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permission to call polly:ListSpeechSynthesisTasks
4. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT grant the Lambda_Function permissions for asynchronous Polly APIs

### Requirement 7: IAM Permissions for S3 Access

**User Story:** As a developer with asyncJobs enabled, I want the Lambda function to have permissions to access the S3 bucket, so that it can configure Polly to use the bucket for output and optionally retrieve generated audio files.

#### Acceptance Criteria

1. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function write permissions to the Output_Bucket
2. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function read permissions to the Output_Bucket
3. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT grant any S3 permissions to the Lambda_Function

### Requirement 8: IAM Permissions for SNS Topic Access

**User Story:** As a developer with asyncJobs enabled, I want the Lambda function to have permissions to access the SNS topic, so that it can configure Polly notification settings for asynchronous tasks.

#### Acceptance Criteria

1. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permission to publish messages to the Notification_Topic
2. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT grant any SNS permissions to the Lambda_Function

### Requirement 9: Environment Variables for Resource Discovery

**User Story:** As a developer with asyncJobs enabled, I want the Lambda function to receive environment variables with resource identifiers, so that my Lambda code can discover and use the S3 bucket and SNS topic.

#### Acceptance Criteria

1. WHEN asyncJobs is true and bucketEnvironmentVariableName is provided, THE Construct SHALL set that environment variable name on the Lambda_Function with the Output_Bucket name as the value
2. WHEN asyncJobs is true and bucketEnvironmentVariableName is not provided, THE Construct SHALL set OUTPUT_BUCKET_NAME environment variable on the Lambda_Function with the Output_Bucket name as the value
3. WHEN asyncJobs is true and topicEnvironmentVariableName is provided, THE Construct SHALL set that environment variable name on the Lambda_Function with the Notification_Topic ARN as the value
4. WHEN asyncJobs is true and topicEnvironmentVariableName is not provided, THE Construct SHALL set SNS_TOPIC_ARN environment variable on the Lambda_Function with the Notification_Topic ARN as the value
5. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT set bucket or topic environment variables on the Lambda_Function

### Requirement 10: VPC Deployment Support

**User Story:** As a developer, I want to optionally deploy the Lambda function in a VPC, so that I can meet network isolation requirements.

#### Acceptance Criteria

1. WHEN deployVpc is true, THE Construct SHALL create a VPC with best-practice configuration
2. WHEN existingVpc is provided, THE Construct SHALL deploy the Lambda_Function in that VPC
3. WHEN vpcProps is provided, THE Construct SHALL create a VPC with those properties
4. WHEN a VPC is used, THE Construct SHALL create a Polly Interface Endpoint for the VPC
5. WHEN a VPC is used and asyncJobs is true, THE Construct SHALL create an S3 Gateway Endpoint for the VPC
6. WHEN a VPC is used, THE Construct SHALL expose the VPC as a public property
7. WHEN both deployVpc and existingVpc are provided, THE Construct SHALL reject the configuration with an error

### Requirement 11: Access Logging Configuration

**User Story:** As a developer with asyncJobs enabled, I want to configure access logging for the S3 bucket, so that I can audit access to audio files.

#### Acceptance Criteria

1. WHEN asyncJobs is true and logS3AccessLogs is true or undefined, THE Construct SHALL enable access logging on the Output_Bucket
2. WHEN asyncJobs is true and logS3AccessLogs is false, THE Construct SHALL NOT enable access logging on the Output_Bucket
3. WHEN asyncJobs is true and loggingBucketProps is provided, THE Construct SHALL create a logging bucket with those properties
4. WHEN asyncJobs is true and logS3AccessLogs is true and loggingBucketProps is not provided, THE Construct SHALL create a logging bucket with best-practice defaults
5. WHEN asyncJobs is false or not provided, THE Construct SHALL ignore logS3AccessLogs and loggingBucketProps

### Requirement 12: Topic Encryption Configuration

**User Story:** As a developer with asyncJobs enabled, I want to configure encryption for the SNS topic, so that I can meet security and compliance requirements.

#### Acceptance Criteria

1. WHEN asyncJobs is true and existingTopicObj is provided with customer-managed encryption, THE Construct SHALL require existingTopicEncryptionKey to be provided
2. WHEN asyncJobs is true and topicEncryptionKey is provided, THE Construct SHALL use that KMS key for Notification_Topic encryption
3. WHEN asyncJobs is true and topicEncryptionKeyProps is provided, THE Construct SHALL create a new KMS key with those properties for Notification_Topic encryption
4. WHEN asyncJobs is true and enableTopicEncryptionWithCustomerManagedKey is true and no encryption key is specified, THE Construct SHALL create a new customer-managed KMS key for Notification_Topic encryption
5. WHEN asyncJobs is true and enableTopicEncryptionWithCustomerManagedKey is false and no encryption key is specified, THE Construct SHALL create the Notification_Topic with AWS-managed encryption
6. WHEN asyncJobs is true and topicProps.masterKey is provided, THE Construct SHALL ignore the enableTopicEncryptionWithCustomerManagedKey flag
7. WHEN asyncJobs is true and a customer-managed key is used, THE Construct SHALL expose the encryption key as a public property
8. WHEN asyncJobs is false or not provided, THE Construct SHALL ignore all topic encryption configuration props

### Requirement 13: Props Validation

**User Story:** As a developer, I want clear error messages when I provide conflicting props, so that I can quickly fix configuration issues.

#### Acceptance Criteria

1. WHEN both existingLambdaObj and lambdaFunctionProps are provided, THE Construct SHALL throw an error before creating any resources
2. WHEN asyncJobs is true and both existingBucketObj and bucketProps are provided, THE Construct SHALL throw an error before creating any resources
3. WHEN asyncJobs is true and both existingTopicObj and topicProps are provided, THE Construct SHALL throw an error before creating any resources
4. WHEN both deployVpc and existingVpc are provided, THE Construct SHALL throw an error before creating any resources
5. WHEN asyncJobs is false or not provided and any of existingBucketObj, bucketProps, bucketEnvironmentVariableName, or loggingBucketProps is provided, THE Construct SHALL throw an error before creating any resources
6. WHEN asyncJobs is false or not provided and any of existingTopicObj, topicProps, topicEnvironmentVariableName, existingTopicEncryptionKey, topicEncryptionKey, topicEncryptionKeyProps, or enableTopicEncryptionWithCustomerManagedKey is provided, THE Construct SHALL throw an error before creating any resources

### Requirement 14: Multi-Language Support

**User Story:** As a developer using TypeScript, Python, Java, or .NET, I want to use the construct in my preferred language, so that it integrates with my existing CDK application.

#### Acceptance Criteria

1. THE Construct SHALL be published to NPM for TypeScript and JavaScript
2. THE Construct SHALL be published to PyPI for Python
3. THE Construct SHALL be published to Maven for Java
4. THE Construct SHALL be published to NuGet for .NET
5. THE Construct SHALL maintain consistent prop names and types across all languages
Loading