Skip to content

Commit f1bc9f8

Browse files
biffgautbiffgaut
authored
feat(aws-lambda-polly): new construct (#1458)
* Initial framework created * Implementation * Add README.md, drop property tests * Refresh integration tests with inline Lambda code * Destroy S3 bucket in integration tests, Suppress cfnguard messages for tests * Suppress more Custom Resource Lambda function cfnguard warnings * Encrypt test SNS topic * Change name of integration test * Add architecture diagrams and publish docs * Add Polly example, fix example links
1 parent 98ab2d2 commit f1bc9f8

File tree

93 files changed

+18265
-332
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

93 files changed

+18265
-332
lines changed

‎.kiro/specs/aws-lambda-polly/design.md‎

Lines changed: 671 additions & 0 deletions
Large diffs are not rendered by default.

‎.kiro/specs/aws-lambda-polly/requirements.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Requirements Document
2+
3+
## Introduction
4+
5+
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.
6+
7+
## Glossary
8+
9+
- **Lambda_Function**: The AWS Lambda function that invokes Amazon Polly APIs
10+
- **Polly_Service**: Amazon Polly text-to-speech service
11+
- **Output_Bucket**: S3 bucket for storing audio files generated by Polly (async jobs only)
12+
- **Notification_Topic**: SNS topic for receiving completion notifications from asynchronous Polly tasks (async jobs only)
13+
- **Construct**: The aws-lambda-polly CDK construct
14+
- **Client**: Developer using the construct
15+
- **Synchronous_API**: Polly's SynthesizeSpeech API for immediate text-to-speech conversion
16+
- **Asynchronous_API**: Polly's StartSpeechSynthesisTask API for longer text processing
17+
- **VPC**: Virtual Private Cloud for network isolation
18+
19+
## Requirements
20+
21+
### Requirement 1: Lambda Function Deployment
22+
23+
**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.
24+
25+
#### Acceptance Criteria
26+
27+
1. WHEN a Client provides lambdaFunctionProps, THE Construct SHALL create a Lambda_Function with those properties
28+
2. WHEN a Client provides existingLambdaObj, THE Construct SHALL use that Lambda_Function instance
29+
3. WHEN a Client provides both existingLambdaObj and lambdaFunctionProps, THE Construct SHALL reject the configuration with an error
30+
4. WHEN neither existingLambdaObj nor lambdaFunctionProps is provided, THE Construct SHALL create a Lambda_Function with best-practice defaults
31+
5. THE Construct SHALL expose the Lambda_Function as a public property
32+
33+
### Requirement 2: Asynchronous Job Support
34+
35+
**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.
36+
37+
#### Acceptance Criteria
38+
39+
1. WHEN asyncJobs is true, THE Construct SHALL create an Output_Bucket for storing audio files
40+
2. WHEN asyncJobs is true, THE Construct SHALL create a Notification_Topic for receiving completion notifications
41+
3. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permissions for synchronous and asynchronous Polly APIs
42+
4. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT create an Output_Bucket
43+
5. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT create a Notification_Topic
44+
6. WHEN asyncJobs is false or not provided, THE Construct SHALL grant the Lambda_Function permissions only for synchronous Polly APIs
45+
46+
### Requirement 3: S3 Bucket for Audio Output
47+
48+
**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.
49+
50+
#### Acceptance Criteria
51+
52+
1. WHEN asyncJobs is true and bucketProps is provided, THE Construct SHALL create an Output_Bucket with those properties
53+
2. WHEN asyncJobs is true and existingBucketObj is provided, THE Construct SHALL use that Output_Bucket interface
54+
3. WHEN asyncJobs is true and both existingBucketObj and bucketProps are provided, THE Construct SHALL reject the configuration with an error
55+
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
56+
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
57+
6. WHEN asyncJobs is true, THE Construct SHALL expose the bucket interface as a public property of type s3.IBucket
58+
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
59+
8. WHEN asyncJobs is false or not provided, THE Construct SHALL ignore bucketProps and existingBucketObj
60+
61+
### Requirement 4: SNS Topic for Notifications
62+
63+
**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.
64+
65+
#### Acceptance Criteria
66+
67+
1. WHEN asyncJobs is true and topicProps is provided, THE Construct SHALL create a Notification_Topic with those properties
68+
2. WHEN asyncJobs is true and existingTopicObj is provided, THE Construct SHALL use that Notification_Topic instance
69+
3. WHEN asyncJobs is true and both existingTopicObj and topicProps are provided, THE Construct SHALL reject the configuration with an error
70+
4. WHEN asyncJobs is true and neither existingTopicObj nor topicProps is provided, THE Construct SHALL create a Notification_Topic with encryption enabled
71+
5. WHEN asyncJobs is true, THE Construct SHALL expose the Notification_Topic as a public property
72+
6. WHEN asyncJobs is false or not provided, THE Construct SHALL ignore topicProps and existingTopicObj
73+
74+
### Requirement 5: IAM Permissions for Synchronous Polly APIs
75+
76+
**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.
77+
78+
#### Acceptance Criteria
79+
80+
1. THE Construct SHALL grant the Lambda_Function permission to call polly:SynthesizeSpeech
81+
2. THE Construct SHALL NOT grant the Lambda_Function permission to pass IAM roles to Polly_Service
82+
83+
### Requirement 6: IAM Permissions for Asynchronous Polly APIs
84+
85+
**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.
86+
87+
#### Acceptance Criteria
88+
89+
1. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permission to call polly:StartSpeechSynthesisTask
90+
2. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permission to call polly:GetSpeechSynthesisTask
91+
3. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permission to call polly:ListSpeechSynthesisTasks
92+
4. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT grant the Lambda_Function permissions for asynchronous Polly APIs
93+
94+
### Requirement 7: IAM Permissions for S3 Access
95+
96+
**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.
97+
98+
#### Acceptance Criteria
99+
100+
1. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function write permissions to the Output_Bucket
101+
2. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function read permissions to the Output_Bucket
102+
3. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT grant any S3 permissions to the Lambda_Function
103+
104+
### Requirement 8: IAM Permissions for SNS Topic Access
105+
106+
**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.
107+
108+
#### Acceptance Criteria
109+
110+
1. WHEN asyncJobs is true, THE Construct SHALL grant the Lambda_Function permission to publish messages to the Notification_Topic
111+
2. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT grant any SNS permissions to the Lambda_Function
112+
113+
### Requirement 9: Environment Variables for Resource Discovery
114+
115+
**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.
116+
117+
#### Acceptance Criteria
118+
119+
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
120+
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
121+
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
122+
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
123+
5. WHEN asyncJobs is false or not provided, THE Construct SHALL NOT set bucket or topic environment variables on the Lambda_Function
124+
125+
### Requirement 10: VPC Deployment Support
126+
127+
**User Story:** As a developer, I want to optionally deploy the Lambda function in a VPC, so that I can meet network isolation requirements.
128+
129+
#### Acceptance Criteria
130+
131+
1. WHEN deployVpc is true, THE Construct SHALL create a VPC with best-practice configuration
132+
2. WHEN existingVpc is provided, THE Construct SHALL deploy the Lambda_Function in that VPC
133+
3. WHEN vpcProps is provided, THE Construct SHALL create a VPC with those properties
134+
4. WHEN a VPC is used, THE Construct SHALL create a Polly Interface Endpoint for the VPC
135+
5. WHEN a VPC is used and asyncJobs is true, THE Construct SHALL create an S3 Gateway Endpoint for the VPC
136+
6. WHEN a VPC is used, THE Construct SHALL expose the VPC as a public property
137+
7. WHEN both deployVpc and existingVpc are provided, THE Construct SHALL reject the configuration with an error
138+
139+
### Requirement 11: Access Logging Configuration
140+
141+
**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.
142+
143+
#### Acceptance Criteria
144+
145+
1. WHEN asyncJobs is true and logS3AccessLogs is true or undefined, THE Construct SHALL enable access logging on the Output_Bucket
146+
2. WHEN asyncJobs is true and logS3AccessLogs is false, THE Construct SHALL NOT enable access logging on the Output_Bucket
147+
3. WHEN asyncJobs is true and loggingBucketProps is provided, THE Construct SHALL create a logging bucket with those properties
148+
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
149+
5. WHEN asyncJobs is false or not provided, THE Construct SHALL ignore logS3AccessLogs and loggingBucketProps
150+
151+
### Requirement 12: Topic Encryption Configuration
152+
153+
**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.
154+
155+
#### Acceptance Criteria
156+
157+
1. WHEN asyncJobs is true and existingTopicObj is provided with customer-managed encryption, THE Construct SHALL require existingTopicEncryptionKey to be provided
158+
2. WHEN asyncJobs is true and topicEncryptionKey is provided, THE Construct SHALL use that KMS key for Notification_Topic encryption
159+
3. WHEN asyncJobs is true and topicEncryptionKeyProps is provided, THE Construct SHALL create a new KMS key with those properties for Notification_Topic encryption
160+
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
161+
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
162+
6. WHEN asyncJobs is true and topicProps.masterKey is provided, THE Construct SHALL ignore the enableTopicEncryptionWithCustomerManagedKey flag
163+
7. WHEN asyncJobs is true and a customer-managed key is used, THE Construct SHALL expose the encryption key as a public property
164+
8. WHEN asyncJobs is false or not provided, THE Construct SHALL ignore all topic encryption configuration props
165+
166+
### Requirement 13: Props Validation
167+
168+
**User Story:** As a developer, I want clear error messages when I provide conflicting props, so that I can quickly fix configuration issues.
169+
170+
#### Acceptance Criteria
171+
172+
1. WHEN both existingLambdaObj and lambdaFunctionProps are provided, THE Construct SHALL throw an error before creating any resources
173+
2. WHEN asyncJobs is true and both existingBucketObj and bucketProps are provided, THE Construct SHALL throw an error before creating any resources
174+
3. WHEN asyncJobs is true and both existingTopicObj and topicProps are provided, THE Construct SHALL throw an error before creating any resources
175+
4. WHEN both deployVpc and existingVpc are provided, THE Construct SHALL throw an error before creating any resources
176+
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
177+
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
178+
179+
### Requirement 14: Multi-Language Support
180+
181+
**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.
182+
183+
#### Acceptance Criteria
184+
185+
1. THE Construct SHALL be published to NPM for TypeScript and JavaScript
186+
2. THE Construct SHALL be published to PyPI for Python
187+
3. THE Construct SHALL be published to Maven for Java
188+
4. THE Construct SHALL be published to NuGet for .NET
189+
5. THE Construct SHALL maintain consistent prop names and types across all languages

0 commit comments

Comments
 (0)