Skip to content

Commit 717bc01

Browse files
biffgautbiffgaut
authored
feat(aws-lambda-translate): new construct (#1434)
* Initial package.json * Code Complete - review and testing required * Tests all pass, async jobs doesn't work * Everything works and tests pass, about to move stuff to translate-helper.ts * Complete * Update docs * Center figure labels * tweak * final figure tweak * more * nore * Sync integ-runner config * Assign a specific resource to iam:PassRole * Check for proper role association * Reflect Code Review comments
1 parent 7fb4620 commit 717bc01

File tree

79 files changed

+15451
-1064
lines changed

Some content is hidden

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

79 files changed

+15451
-1064
lines changed

‎.kiro/prompts/new-construct.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Implement New AWS Solutions Construct
2+
3+
You are tasked with implementing a new AWS Solutions Construct based on the specification file at `specs/{{arg1}}` and the README.adoc file that has already been created.
4+
5+
## Implementation Steps
6+
7+
1. **Read the specification file** at `specs/{{arg1}}` to understand:
8+
- Main services involved
9+
- Interface requirements (props)
10+
- Incoming props validation checks
11+
- Configuration and integration logic
12+
- Construct properties to expose
13+
14+
2. **Review the existing README.adoc** in the construct directory to ensure alignment with documented behavior
15+
16+
3. **Create the directory structure** following the pattern:
17+
```
18+
source/patterns/@aws-solutions-constructs/aws-{service1}-{service2}/
19+
├── lib/
20+
│ └── index.ts
21+
├── test/
22+
│ ├── integ.*.test.ts
23+
│ └── test.*.test.ts
24+
├── package.json
25+
├── .npmignore
26+
├── .gitignore
27+
└── README.md (brief)
28+
```
29+
30+
4. **Implement lib/index.ts**:
31+
- Add Apache 2.0 license header
32+
- Import required CDK modules and core helpers
33+
- Define Props interface matching README.adoc documentation
34+
- Implement Construct class with:
35+
- Public properties for all created resources
36+
- Constructor that validates props, creates resources, and configures integrations
37+
- Follow patterns from similar existing constructs
38+
39+
5. **Add core helper functions** if needed:
40+
- Create `core/lib/{service}-helper.ts` for new services
41+
- Add validation functions (e.g., `CheckTranslateProps()`)
42+
- Add VPC endpoint support if required
43+
44+
6. **Create package.json**:
45+
- Set correct name: `@aws-solutions-constructs/aws-{service1}-{service2}`
46+
- Configure JSII targets for TypeScript, Python, Java, .NET
47+
- Add dependencies on `@aws-solutions-constructs/core` and `aws-cdk-lib`
48+
- Include standard scripts: build, lint, test, integ
49+
50+
7. **Write unit tests** in `test/test.*.test.ts`:
51+
- Test default configuration
52+
- Test with custom props
53+
- Test with existing resources
54+
- Test VPC deployment scenarios
55+
- Test error conditions and validation
56+
- Achieve 95%+ code coverage
57+
58+
8. **Write integration tests** in `test/integ.*.test.ts`:
59+
- Test default deployment
60+
- Test major architectural variations (with/without VPC, existing resources, etc.)
61+
- Use `generateIntegStackName()` and `SetConsistentFeatureFlags()`
62+
63+
9. **Create supporting files**:
64+
- `.npmignore` - exclude test files and source maps
65+
- `.gitignore` - exclude build artifacts
66+
- `README.md` - brief description pointing to README.adoc
67+
68+
10. **Validate implementation**:
69+
- Run `npm run build` to compile TypeScript
70+
- Run `npm run lint` to check code style
71+
- Run `npm test` to verify unit tests pass with coverage
72+
- Run `npm run integ` to create integration test snapshots
73+
74+
## Key Requirements
75+
76+
- Follow naming conventions from structure.md
77+
- Use core helper functions for resource creation
78+
- Implement least-privilege IAM permissions
79+
- Add environment variables for resource discovery
80+
- Support VPC deployment when appropriate
81+
- Match all prop and property descriptions to README.adoc comments
82+
- Ensure consistency with existing constructs for shared services
83+
- Follow ESLint rules in eslintrc.config.mjs
84+
- Add license headers to all source files
85+
86+
## Reference Documentation
87+
88+
Refer to the steering files for detailed guidance:
89+
- `.kiro/steering/structure.md` - Repository structure and patterns
90+
- `.kiro/steering/product.md` - Product requirements and best practices
91+
- `.kiro/steering/tech.md` - Technical implementation details
92+
- `.kiro/steering/test.md` - Testing requirements and patterns
93+
- `.kiro/steering/exceptions.md` - Known exceptions to standard patterns
94+
95+
## Output
96+
97+
Provide a complete, working implementation that:
98+
- Compiles without errors
99+
- Passes all linting checks
100+
- Has comprehensive test coverage
101+
- Follows all Solutions Constructs patterns and conventions
102+
- Matches the behavior documented in README.adoc

‎.kiro/prompts/new-readme.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Create README.adoc for New AWS Solutions Construct
2+
3+
You are tasked with creating a README.adoc file for a new AWS Solutions Construct based on the specification file at `.kiro/specs/{{arg1}}`.
4+
5+
## Implementation Steps
6+
7+
1. **Read the specification file** at `.kiro/specs/{{arg1}}` to understand:
8+
- Construct name (aws-{service1}-{service2})
9+
- Main services involved
10+
- Interface requirements (all props)
11+
- Configuration and default settings
12+
- Construct properties to expose
13+
14+
2. **Determine the correct location**:
15+
- Path: `source/patterns/@aws-solutions-constructs/aws-{service1}-{service2}/README.adoc`
16+
17+
3. **Review similar constructs** for reference:
18+
- For Lambda-based constructs, reference `aws-lambda-dynamodb` or `aws-lambda-transcribe`
19+
- Match the structure and style of existing README.adoc files
20+
21+
4. **Create README.adoc** with the following sections:
22+
23+
**Header:**
24+
- Module name and title
25+
- Stability badge (use Experimental for new constructs)
26+
- Reference documentation link
27+
- Language package table (TypeScript, Python, Java)
28+
29+
**Overview:**
30+
- Brief description of what the construct does
31+
- Minimal deployable examples in TypeScript, Python, and Java
32+
- Use realistic runtime versions (NODEJS_20_X, PYTHON_3_11, etc.)
33+
34+
**Pattern Construct Props:**
35+
- Table with columns: Name, Type, Description
36+
- Include all props from the spec interface
37+
- Link to AWS CDK API documentation for all types
38+
- Mark optional props with `?`
39+
- Ensure descriptions match what will be in the code comments
40+
41+
**Pattern Properties:**
42+
- Table with columns: Name, Type, Description
43+
- List all public properties exposed by the construct
44+
- Link to AWS CDK API documentation for all types
45+
46+
**Default Settings:**
47+
- Subsection for each major service
48+
- Bullet list of default configurations applied
49+
- Highlight security best practices (encryption, IAM, logging, etc.)
50+
51+
**Architecture:**
52+
- Reference to architecture diagram: `image::aws-{service1}-{service2}.png`
53+
- Brief description of the diagram
54+
55+
**Example Lambda Function Implementation (if applicable):**
56+
- For Lambda constructs, link to AWS SDK example code
57+
- Use github.com/awsdocs/aws-doc-sdk-examples links
58+
59+
**Footer:**
60+
- Copyright notice
61+
62+
## Key Requirements
63+
64+
- Use AsciiDoc format with proper syntax
65+
- Ensure prop descriptions will match code comments exactly
66+
- Include links to AWS CDK API documentation for all types
67+
- Use tabbed code blocks for multi-language examples
68+
- Follow the exact structure and style of existing README.adoc files
69+
- Mark new constructs as Experimental stability
70+
- Ensure all props from the spec are documented
71+
- Document VPC-related props if applicable
72+
- Document S3 bucket props if applicable
73+
- Be precise about default values and optional parameters
74+
75+
## Reference Examples
76+
77+
Review these existing constructs for structure:
78+
- `aws-lambda-dynamodb/README.adoc` - Basic Lambda pattern
79+
- `aws-lambda-transcribe/README.adoc` - Lambda with S3 buckets and async jobs
80+
81+
## Output
82+
83+
Create a complete README.adoc file at the correct location that:
84+
- Follows all Solutions Constructs documentation patterns
85+
- Accurately reflects the spec requirements
86+
- Provides clear, working examples in multiple languages
87+
- Documents all props and properties comprehensively
88+
- Matches the style and structure of existing constructs

‎.kiro/specs/aws-lambda-translate.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# AWS Solutions Constructs Product Documentation
2+
3+
## Spec for aws-lambda-translate
4+
This should only be referenced when generating code and artifacts for aws-lambda-translate, for any other tasks it should be ignored
5+
6+
### Main Services
7+
* Lambda Function
8+
* Amazon Translate - Translate is an API, there are no depoyed resources. So there are no translateProps in the construct interface
9+
10+
### Interface
11+
* All required props for Lambda based constructs
12+
* This is the first Construct using Translate, so this will define the interface for Translate constructs
13+
* A flag, asyncJobs, that defaults to false
14+
* Source and Destination S3 bucket props, modeled on those created for aws-lamba-transcribe
15+
* AdditionalPermissions - an array of strings listing additional IAM permissions to grant the Lambda function. Default will be List* and Read*, is asyncJobs is true it will add StartTextTranslationJob and StopTextTranslationJob
16+
17+
### Incoming Props Checks
18+
* All Lambda checks in CheckLambdaProps()
19+
* A new CheckTranslateProps() in core/translat-helper.ts that includes
20+
* If any Source and Destination bucket info is provided when asyncJobs is false, an error is thrown
21+
* If useSameBucket is set and any Destination bucket props are provided and error is thrown
22+
23+
### Configuration
24+
* Obtain the Lambda function
25+
* Grant the Lambda function access to
26+
* Translate:Read* and Translate:List*
27+
* if asyncJobs is true add StartTextTranslationJob and StopTextTranslationJob
28+
* Add any additionalPermissions
29+
* if asyncJobs is true, grant read access to the source bucket and write access to the destination bucket
30+
* As instructed, create or use a VPC and add a Translate VPC endpoint to the VPC
31+
* This will require adding Translate VPC Endpoints to the core library
32+
* If asyncJobs is true
33+
* Add StartTextTranslationJob and StopTextTranslationJob actions to the Lambda IAM policy
34+
* Create the source and destination bucket(s) following the pattern in aws-lambda-transcribe
35+
36+
### Construct Properties
37+
* Standard Lambda Function properties
38+
* Translate does not require any exposed properties on the construct

‎.kiro/steering/exceptions.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# AWS Solutions Constructs - Exceptions List
2+
3+
## Overview
4+
The rules for construct architecture laid out in product.md, tech.md, structure.md and test.md are not unversally followed, for various reasons, including:
5+
* Improved understanding of how services should be defined as the library grew
6+
* Scenarios where resources must be declared by a particular construct, so other constructs can only accept an existing construct (example - API Gateway must be launched integrated with a backend service, so aws-cloudfront-apigateway can only accept an existing service)
7+
* Services must be launched at the top level due to the need to export specific elements (example - Bedrock Inference Profiles are launched in aws-lambda-bedrockinferenceprofile/lib/index.ts)
8+
This document will explicitly list new exceptions and gradually document exceptions that have already been implemented.
9+
10+
### VPCs Required for OpenSearch and Elasticsearch
11+
OpenSearch domains and Elasticsearch domains must be launched in a VPC - so any construct referencing these services does not expose the deployVpc property as it MUST be true.
12+

0 commit comments

Comments
 (0)