Merge remote-tracking branch 'origin/1177-feature-implement-appconfig-provider' into 1177-feature-implement-appconfig-provider

Author: shdq

.devcontainer/Dockerfile

@@ -1,6 +1,6 @@
 # See here for image contents: https://github.com/microsoft/vscode-dev-containers/blob/v0.212.0/containers/javascript-node/.devcontainer/base.Dockerfile
-# [Choice] Node.js version (use -bullseye variants on local arm64/Apple Silicon): 16, 14, 16-bullseye, 14-bullseye, 16-buster, 14-buster
-ARG VARIANT="16-bullseye"
+# [Choice] Node.js version (use -bullseye variants on local arm64/Apple Silicon): 18, 16, 14, 18-bullseye, 16-bullseye, 14-bullseye, 18-buster, 16-buster, 14-buster
+ARG VARIANT="18-bullseye"
 FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${VARIANT}
 
 # This section to install additional OS packages.

.devcontainer/devcontainer.json

@@ -4,11 +4,11 @@
   "name": "Node.js",
   "build": {
     "dockerfile": "Dockerfile",
-    // Update 'VARIANT' to pick a Node version: 16, 14.
+    // Update 'VARIANT' to pick a Node version: 18, 16, 14.
     // Append -bullseye or -buster to pin to an OS version.
     // Use -bullseye variants on local arm64/Apple Silicon.
     "args": {
-      "VARIANT": "16-bullseye"
+      "VARIANT": "18-bullseye"
     }
   },
   // Set *default* container specific settings.json values on container create.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -58,8 +58,9 @@ body:
     attributes:
       label: AWS Lambda function runtime
       options:
-        - 14.x
+        - 18.x
         - 16.x
+        - 14.x
     validations:
       required: true
   - type: dropdown

.github/workflows/make-release.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Setup NodeJS
         uses: actions/setup-node@v3
         with:
-          node-version: "16"
+          node-version: "18"
           cache: "npm"
       - name: Setup npm
         run: |
@@ -33,7 +33,7 @@ jobs:
           path: "./node_modules"
           # Use the combo between node version, name, and SHA-256 hash of the lock file as cache key so that
           # if one of them changes the cache is invalidated/discarded
-          key: 16-cache-utils-node-modules-${{ hashFiles('./package-lock.json') }}
+          key: 18-cache-utils-node-modules-${{ hashFiles('./package-lock.json') }}
       - name: Build packages
         run: |
           npm run build -w packages/commons

.github/workflows/publish_layer.yaml

@@ -34,7 +34,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: "16.12"
+          node-version: "18"
       - name: Set release notes tag
         run: |
           RELEASE_INPUT=${{ inputs.latest_published_version }}

.github/workflows/reusable-publish-docs.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Setup NodeJS
         uses: actions/setup-node@v3
         with:
-          node-version: "16"
+          node-version: "18"
           cache: "npm"
       # Use the combo between node version, name, and SHA-256 hash of the lock file as cache key so that
       # if one of them changes the cache is invalidated/discarded
@@ -47,7 +47,7 @@ jobs:
         uses: actions/cache@v3
         with:
           path: "./node_modules"
-          key: 16-cache-utils-node-modules-${{ hashFiles('./package-lock.json') }}
+          key: 18-cache-utils-node-modules-${{ hashFiles('./package-lock.json') }}
       - name: Install dependencies
         # We can skip the installation if there was a cache hit
         if: steps.cache-node-modules.outputs.cache-hit != 'true'

.github/workflows/reusable-run-linting-check-and-unit-tests.yml

@@ -10,7 +10,7 @@ jobs:
       NODE_ENV: dev
     strategy:
       matrix:
-        version: [14, 16]
+        version: [14, 16, 18]
       fail-fast: false
     steps:
       - name: Checkout code

.github/workflows/reusable_deploy_layer_stack.yml

@@ -62,7 +62,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: "16.12"
+          node-version: "18"
       - name: install cdk and deps
         run: |
           npm install -g [email protected]

.github/workflows/run-e2e-tests.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       matrix:
         package: [logger, metrics, tracer]
-        version: [14, 16]
+        version: [14, 16, 18]
       fail-fast: false
     steps:
       - name: Checkout Repo
@@ -70,7 +70,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        version: [14, 16]
+        version: [14, 16, 18]
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v3
@@ -93,8 +93,8 @@ jobs:
       - name: Setup NodeJS
         uses: actions/setup-node@v3
         with:
-          # Always use version 16 as we use TypeScript target es2020
-          node-version: 16
+          # Always use version 18
+          node-version: 18
       - name: Setup npm
         run: npm i -g npm@next-8
       - name: "Configure AWS credentials"

.nvmrc

@@ -1 +1 @@
-lts/gallium
+lts/hydrogen

CONTRIBUTING.md

@@ -71,20 +71,20 @@ The alternative is to use a Cloud IDE like [Gitpod](https://www.gitpod.io/) or [
 
 The following tools need to be installed on your system prior to starting working on a pull request:
 
-- [Node.js >= 16.x](https://nodejs.org/download/release/latest-v16.x/)
+- [Node.js >= 18.x](https://nodejs.org/download/release/latest-v18.x/)
   - We recommend using a version in [Active LTS](https://nodejs.org/en/about/releases/)
   - If you use [nvm](https://github.com/nvm-sh/nvm#nvmrc) or [fnm](https://github.com/Schniz/fnm) you can install the latest LTS version with `nvm use` or `fnm use` respectively. Both will use the `.nvmrc` file in the project's root.
 - [npm 8.x](https://www.npmjs.com/)
   - After installing Node.js, you can install `npm` with `npm install -g npm@next-8` 
-- [AWS SAM CLI >= 1.49.0](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+- [AWS SAM CLI >= 1.65.0](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
   - AWS SAM CLI is a command line interface for AWS Serverless Application Model (SAM), it's used in one of the examples, and it's part of the pre-push hook.
 - [Docker](https://docs.docker.com/get-docker/)
   - Docker is used to build documentation and Layer.
 
 First, [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository, and then run the following commands to clone and initialize the repository locally.
 
 > **Note**
-> In order for the commands below to work you need Node.js `16.x` and npm `8.x`
+> In order for the commands below to work you need Node.js `18.x` and npm `8.x`
 
 ```console
 git clone https://github.com/{your-account}/aws-lambda-powertools-typescript.git
@@ -272,7 +272,7 @@ Contributions via pull requests are much appreciated.
 
 ### Summary
 
-* This project uses `node@16.x` and `[email protected]` for development (see [Setup](#setup)).
+* This project uses `node@18.x` and `[email protected]` for development (see [Setup](#setup)).
 * Before opening a Pull Request, please find the existing related issue or open a new one to discuss the proposed changes. A PR without a related issue or discussion has a high risk of being rejected. We are very appreciative and thankful for your time and efforts, and we want to make sure they are not wasted.
 * After your proposal has been reviewed and accepted by at least one of the project's maintainers, you can submit a pull request.
 * When opening a PR, make sure to follow the checklist inside the pull request template.

examples/cdk/README.md

@@ -2,9 +2,16 @@
 
 This is a deployable CDK app that deploys AWS Lambda functions as part of a CloudFormation stack. These Lambda functions use the utilities made available as part of AWS Lambda Powertools for TypeScript to demonstrate their usage.
 
-You will need to have a valid AWS Account in order to deploy these resources. These resources may incur costs to your AWS Account. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
+> **Note**
+> You will need to have a valid AWS Account in order to deploy these resources. These resources may incur costs to your AWS Account. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
 
-The example functions, located in the `src` folder, are invoked automatically, twice, when deployed using the CDK construct defined in `src/example-function.ts`. The first invocation demonstrates the effect on logs/metrics/annotations when the Lambda function has a cold start, and the latter without a cold start.
+The example functions, located in the `functions` folder, are frontend by a REST API that is deployed using AWS API Gateway.
+
+The API has three endpoints:
+
+ * `POST /` - Adds an item to the DynamoDB table
+ * `GET /` - Retrieves all items from the DynamoDB table
+ * `GET /{id}` - Retrieves a specific item from the DynamoDB table
 
 ## Deploying the stack
 
@@ -14,10 +21,59 @@ The example functions, located in the `src` folder, are invoked automatically, t
 
 Note: Prior to deploying you may need to run `cdk bootstrap aws://<YOU_AWS_ACCOUNT_ID>/<AWS_REGION> --profile <YOUR_AWS_PROFILE>` if you have not already bootstrapped your account for CDK.
 
-## Viewing Utility Outputs
+> **Note**
+> You can find your API Gateway Endpoint URL in the output values displayed after deployment.
+
+## Execute the functions via API Gateway
+
+Use the API Gateway Endpoint URL from the output values to execute the functions. First, let's add two items to the DynamoDB Table by running:
+
+```bash
+curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myfirstitem","name":"Some Name for the first item"}' https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/
+curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myseconditem","name":"Some Name for the second item"}' https://randomid1245.execute-api.eu-central-1.amazonaws.com/prod/
+````
+
+Now, let's retrieve all items by running:
+
+```sh
+curl -XGET https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/
+```
+
+And finally, let's retrieve a specific item by running:
+```bash
+curl -XGET https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/myseconditem/
+```
+
+## Observe the outputs in AWS CloudWatch & X-Ray
+
+### CloudWatch
+
+If we check the logs in CloudWatch, we can see that the logs are structured like this
+```
+2022-04-26T17:00:23.808Z	e8a51294-6c6a-414c-9777-6b0f24d8739b	DEBUG	
+{
+    "level": "DEBUG",
+    "message": "retrieved items: 0",
+    "service": "getAllItems",
+    "timestamp": "2022-04-26T17:00:23.808Z",
+    "awsRequestId": "e8a51294-6c6a-414c-9777-6b0f24d8739b"
+}
+```
+
+By having structured logs like this, we can easily search and analyse them in [CloudWatch Logs Insight](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html). Run the following query to get all messages for a specific `awsRequestId`:
+
+````
+filter awsRequestId="bcd50969-3a55-49b6-a997-91798b3f133a"
+ | fields timestamp, message
+````
+### AWS X-Ray
+
+As we have enabled tracing for our Lambda-Funtions, you can visit [AWS CloudWatch Console](https://console.aws.amazon.com/cloudwatch/) and see [Traces](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-traces) and a [Service Map](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-using-xray-maps.html) for our application.
+
+## Cleanup
 
-All utility outputs can be viewed in the Amazon CloudWatch console.
+To delete the sample application that you created, run the command below while in the `examples/sam` directory:
 
- * `Logger` output can be found in Logs > Log groups
- * `Metrics` output can be found in Metrics > All metrics > CdkExample
- * `Tracer` output can be found in  X-Ray traces > Traces
+```bash
+cdk delete
+```

examples/cdk/functions/common/constants.ts

@@ -0,0 +1,6 @@
+// Get the DynamoDB table name from environment variables
+const tableName = process.env.SAMPLE_TABLE;
+
+export {
+  tableName
+};

examples/cdk/functions/common/dynamodb-client.ts

@@ -0,0 +1,29 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { tracer } from './powertools';
+
+// Create DynamoDB Client and patch it for tracing
+const ddbClient = tracer.captureAWSv3Client(new DynamoDBClient({}));
+
+const marshallOptions = {
+  // Whether to automatically convert empty strings, blobs, and sets to `null`.
+  convertEmptyValues: false, // false, by default.
+  // Whether to remove undefined values while marshalling.
+  removeUndefinedValues: false, // false, by default.
+  // Whether to convert typeof object to map attribute.
+  convertClassInstanceToMap: false, // false, by default.
+};
+
+const unmarshallOptions = {
+  // Whether to return numbers as a string instead of converting them to native JavaScript numbers.
+  wrapNumbers: false, // false, by default.
+};
+
+const translateConfig = { marshallOptions, unmarshallOptions };
+
+// Create the DynamoDB Document client.
+const docClient = DynamoDBDocumentClient.from(ddbClient, translateConfig);
+
+export {
+  docClient
+};

examples/cdk/functions/common/powertools.ts

@@ -0,0 +1,32 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+
+const awsLambdaPowertoolsVersion = '1.5.0';
+
+const defaultValues = {
+  region: process.env.AWS_REGION || 'N/A',
+  executionEnv: process.env.AWS_EXECUTION_ENV || 'N/A'
+};
+
+const logger = new Logger({
+  persistentLogAttributes: {
+    ...defaultValues,
+    logger: {
+      name: '@aws-lambda-powertools/logger',
+      version: awsLambdaPowertoolsVersion,
+    }
+  },
+});
+
+const metrics = new Metrics({
+  defaultDimensions: defaultValues
+});
+
+const tracer = new Tracer();
+
+export {
+  logger,
+  metrics,
+  tracer
+};