feat(graalvm): GraalVM support for Idempotency utility

.github/dependency-review-config.yml

@@ -27,4 +27,5 @@ allow-licenses:
   - 'BSD-3-Clause-No-Nuclear-License-2014'
   - 'BSD-3-Clause-No-Nuclear-Warranty'
   - 'BSD-3-Clause-Open-MPI'
-comment-summary-in-pr: on-failure
+  - 'UPL-1.0'
+comment-summary-in-pr: on-failure

.github/workflows/check-build.yml

@@ -2,15 +2,13 @@
 #
 # Description:
 #   Runs the build for every java version we support
-#   
+#
 # Triggers:
 #   - pull_request: when a PR is sent to us
 #   - push: when code is pushed to a specified branch
 #
 # Notes:
-#   The matrix build for this workflow is unusual, we need to make it dyanmic since 
-#   we need to change java versions we build for depending on the branch.
-
+#   Builds against Java 11, 17, and 21 which are the supported versions.
 
 on:
   workflow_dispatch:
@@ -38,7 +36,7 @@ on:
   push:
     branches:
       - main
-    paths: # add other modules when there are under e2e tests
+    paths:
       - 'powertools-batch/**'
       - 'powertools-core/**'
       - 'powertools-cloudformation/**'
@@ -60,34 +58,16 @@ on:
       - '.github/workflows/**'
 
 name: Build
+permissions:
+  contents: read
 run-name: Build - ${{ github.event_name }}
 
 jobs:
-  setup:
-    runs-on: ubuntu-latest
-    outputs:
-      build_matrix: ${{ format('{0}{1}', steps.build_matrix_v1.outputs.build_matrix, steps.build_matrix_v1.outputs.build_matrix) }}
-    steps:
-      - id: base
-        name: Base
-        run: |
-          echo build_version=$(test ${{ github.ref }} == "v2" && echo "v2" || echo "v1") >> $GITHUB_OUTPUT
-      - id: build_matrix_v1
-        name: Build matrix (v1)
-        if: ${{ steps.base.outputs.build_version == 'v1' }}
-        run: |
-          echo build_matrix='["8", "11", "17", "21"]' >> "$GITHUB_OUTPUT"
-      - id: build_matrix_v2
-        name: Build matrix (v2)
-        if: ${{ steps.base.outputs.build_version == 'v2' }}
-        run: |
-          echo build_matrix='["11", "17", "21"]'>> "$GITHUB_OUTPUT"
-  build:
+  java-build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         java:
-          - 8
           - 11
           - 17
           - 21
@@ -96,13 +76,39 @@ jobs:
         name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: Setup Java
-        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165
+        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
         with:
           distribution: corretto
           java-version: ${{ matrix.java }}
           cache: maven
       - id: build-maven
         name: Build (Maven)
-        if: ${{ matrix.java != '8' }}
         run: |
-          mvn -B install --file pom.xml
+          mvn -B install --file pom.xml
+
+  graalvm-build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: checkout
+        name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Setup GraalVM
+        uses: graalvm/setup-graalvm@7f488cf82a3629ee755e4e97342c01d6bed318fa # v1.3.5
+        with:
+          java-version: "21"
+          distribution: "graalvm"
+          cache: maven
+      - id: graalvm-native-test
+        name: GraalVM Native Test
+        run: |
+          # Find modules with graalvm-native profile and run tests.
+          # This will make sure to discover new GraalVM supported modules automatically in the future.
+          for module in powertools-*/pom.xml; do
+            if grep -q "<id>graalvm-native</id>" "$module"; then
+              module_dir=$(dirname "$module")
+              echo "Regenerating GraalVM metadata for $module_dir"
+              mvn -B -f "$module" -Pgenerate-graalvm-files clean test
+              echo "Running GraalVM native tests for $module_dir"
+              mvn -B -f "$module" -Pgraalvm-native test
+            fi
+          done

examples/README.md

@@ -1,26 +1,35 @@
 #  Powertools for AWS Lambda (Java) Examples 
 
 This directory holds example projects demoing different components of the Powertools for AWS Lambda (Java).
+
 Each example can be copied from its subdirectory and used independently of the rest of this repository.
 
 ## Examples
 
 * [powertools-examples-core-utilities](powertools-examples-core-utilities) - Demonstrates the core logging, tracing, and metrics modules with different build tools and languages 
   * [CDK](./powertools-examples-core-utilities/cdk)
-  * [Gradle](./powertools-examples-core-utilities/gradle)
   * [SAM](./powertools-examples-core-utilities/sam) 
+  * [SAM GraalVM](./powertools-examples-core-utilities/sam-graalvm)
   * [Serverless](./powertools-examples-core-utilities/serverless)
+  * [Terraform](./powertools-examples-core-utilities/terraform)
+  * [Gradle](./powertools-examples-core-utilities/gradle)
   * [Kotlin](./powertools-examples-core-utilities/kotlin)
 * [powertools-examples-idempotency](powertools-examples-idempotency) - An idempotent HTTP API
+  * [SAM](./powertools-examples-idempotency/sam)
+  * [SAM GraalVM](./powertools-examples-idempotency/sam-graalvm)
 * [powertools-examples-parameters](powertools-examples-parameters) - Uses the parameters module to provide runtime parameters to a function
+  * [SAM](./powertools-examples-parameters/sam)
+  * [SAM GraalVM](./powertools-examples-parameters/sam-graalvm)
 * [powertools-examples-serialization](powertools-examples-serialization) - Uses the serialization module to serialize and deserialize API Gateway & SQS payloads
+  * [SAM](./powertools-examples-serialization/sam)
+  * [SAM GraalVM](./powertools-examples-serialization/sam-graalvm)
 * [powertools-examples-validation](powertools-examples-validation) - Uses the validation module to validate user requests received via API Gateway
 * [powertools-examples-cloudformation](powertools-examples-cloudformation) - Deploys a Cloudformation custom resource
 * [powertools-examples-batch](powertools-examples-batch) - Examples for each of the different batch processing deployments
+* [powertools-examples-kafka](powertools-examples-kafka) - Examples for Kafka event processing
 
 ## Working with AWS Serverless Application Model (SAM) Examples
-Many of the examples use [AWS Serverless Application Model](https://aws.amazon.com/serverless/sam/) (SAM). To get started
-with them, you can use the SAM Command Line Interface (SAM CLI) to build it and deploy an example to AWS. 
+Many of the examples use [AWS Serverless Application Model](https://aws.amazon.com/serverless/sam/) (SAM). To get started with them, you can use the SAM Command Line Interface (SAM CLI) to build it and deploy an example to AWS. 
 
 To use the SAM CLI, you need the following tools.
 
@@ -29,17 +38,13 @@ To use the SAM CLI, you need the following tools.
 * Maven - [Install Maven](https://maven.apache.org/install.html)
 * Docker - [Install Docker community edition](https://hub.docker.com/search/?type=edition&offering=community)
 
-To learn more about SAM, 
-[check out the developer guide](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli.html).
-You can use the CLI to [test events locally](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-local-invoke.html),
-and [run the application locally](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-local-start-api.html),
-amongst other things.
+To learn more about SAM, [check out the developer guide](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli.html). You can use the CLI to [test events locally](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-local-invoke.html), and [run the application locally](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-local-start-api.html), amongst other things.
 
 To build and deploy an example application for the first time, run the following in your shell:
 
 ```bash
 # Switch to the directory containing an example for the powertools-idempotency module
-$ cd powertools-examples-idempotency
+$ cd powertools-examples-idempotency/sam
 
 # Build and deploy the example
 $ sam build
@@ -56,7 +61,7 @@ The first command will build the source of your application. The second command
 
 You can find your API Gateway Endpoint URL in the output values displayed after deployment.
 
-If you're not using SAM, you can look for examples for other tools under [powertools-examples-core](./powertools-examples-core)
+If you're not using SAM, you can look for examples for other tools under [powertools-examples-core-utilities](./powertools-examples-core-utilities)
 
 ### External examples
 
@@ -69,10 +74,9 @@ You can find more examples in the https://github.com/aws/aws-sam-cli-app-templat
 
 ### SAM - Other Tools 
 
-If you prefer to use an integrated development environment (IDE) to build and test your application, you can use the AWS Toolkit.  
-The AWS Toolkit is an open source plug-in for popular IDEs that uses the SAM CLI to build and deploy serverless applications on AWS. The AWS Toolkit also adds a simplified step-through debugging experience for Lambda function code. See the following links to get started.
+If you prefer to use an integrated development environment (IDE) to build and test your application, you can use the AWS Toolkit. The AWS Toolkit is an open source plug-in for popular IDEs that uses the SAM CLI to build and deploy serverless applications on AWS. The AWS Toolkit also adds a simplified step-through debugging experience for Lambda function code. See the following links to get started.
 
 * [PyCharm](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/welcome.html)
 * [IntelliJ](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/welcome.html)
 * [VS Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/welcome.html)
-* [Visual Studio](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/welcome.html)
+* [Visual Studio](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/welcome.html)

examples/pom.xml

@@ -35,7 +35,8 @@
         <module>powertools-examples-core-utilities/cdk/infra</module>
         <module>powertools-examples-core-utilities/serverless</module>
         <module>powertools-examples-core-utilities/terraform</module>
-        <module>powertools-examples-idempotency</module>
+        <module>powertools-examples-idempotency/sam</module>
+        <module>powertools-examples-idempotency/sam-graalvm</module>
         <module>powertools-examples-parameters/sam</module>
         <module>powertools-examples-parameters/sam-graalvm</module>
         <module>powertools-examples-serialization/sam</module>

examples/powertools-examples-core-utilities/sam/pom.xml

@@ -45,6 +45,11 @@
             <artifactId>aspectjrt</artifactId>
             <version>${aspectj.version}</version>
         </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>s3</artifactId>
+            <version>2.32.8</version>
+        </dependency>
     </dependencies>
 
     <build>

examples/powertools-examples-core-utilities/sam/src/main/java/helloworld/App.java

@@ -34,6 +34,13 @@
 import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
 import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
 
+import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
+import software.amazon.awssdk.core.SdkSystemSetting;
+import software.amazon.awssdk.core.interceptor.ExecutionAttributes;
+import software.amazon.awssdk.core.interceptor.ExecutionInterceptor;
+import software.amazon.awssdk.http.SdkHttpRequest;
+import software.amazon.awssdk.regions.Region;
+import software.amazon.awssdk.services.s3.S3Client;
 import software.amazon.lambda.powertools.logging.Logging;
 import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.Metrics;
@@ -50,13 +57,32 @@
  */
 public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
     private static final Logger log = LoggerFactory.getLogger(App.class);
+    private static final S3Client s3Client = S3Client.builder()
+            .region(Region.of(System.getenv(SdkSystemSetting.AWS_REGION.environmentVariable())))
+            .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
+            .overrideConfiguration(c -> c.addExecutionInterceptor(new ExecutionInterceptor() {
+                @Override
+                public void beforeTransmission(
+                        software.amazon.awssdk.core.interceptor.Context.BeforeTransmission context,
+                        ExecutionAttributes executionAttributes) {
+                    SdkHttpRequest request = context.httpRequest();
+                    log.info("User-Agent header: {}", request.headers().get("User-Agent"));
+                }
+            }))
+            .build();
     private static final Metrics metrics = MetricsFactory.getMetricsInstance();
 
+    public App() {
+        log.info("sdk.ua.appId system property: {}", System.getProperty("sdk.ua.appId"));
+        s3Client.listBuckets();
+    }
+
     @Logging(logEvent = true, samplingRate = 0.7)
     @Tracing(captureMode = CaptureMode.RESPONSE_AND_ERROR)
     @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
+        s3Client.listBuckets();
 
         headers.put("Content-Type", "application/json");
         headers.put("X-Custom-Header", "application/json");

examples/powertools-examples-core-utilities/sam/template.yaml

@@ -19,11 +19,22 @@ Globals:
         POWERTOOLS_METRICS_NAMESPACE: Coreutilities
 
 Resources:
+  TestBucket:
+    Type: AWS::S3::Bucket
+
   HelloWorldFunction:
     Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
     Properties:
       CodeUri: .
       Handler: helloworld.App::handleRequest
+      Policies:
+        - S3ReadPolicy:
+            BucketName: !Ref TestBucket
+        - Statement:
+            - Effect: Allow
+              Action:
+                - s3:ListAllMyBuckets
+              Resource: "*"
       Environment: # More info about Env Vars: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#environment-object
         Variables:
           POWERTOOLS_SERVICE_NAME: hello

examples/powertools-examples-idempotency/sam-graalvm/Dockerfile

@@ -0,0 +1,14 @@
+# Use the official AWS SAM base image for Java 21
+FROM public.ecr.aws/sam/build-java21@sha256:a5554d68374e19450c6c88448516ac95a9acedc779f318040f5c230134b4e461
+
+# Install GraalVM dependencies
+RUN curl -4 -L curl https://download.oracle.com/graalvm/21/latest/graalvm-jdk-21_linux-x64_bin.tar.gz | tar -xvz
+RUN mv graalvm-jdk-21.* /usr/lib/graalvm
+
+# Make native image and mvn available on CLI
+RUN ln -s /usr/lib/graalvm/bin/native-image /usr/bin/native-image
+RUN ln -s /usr/lib/maven/bin/mvn /usr/bin/mvn
+
+# Set GraalVM as default
+ENV JAVA_HOME=/usr/lib/graalvm
+ENV PATH=/usr/lib/graalvm/bin:$PATH

examples/powertools-examples-idempotency/sam-graalvm/Makefile

@@ -0,0 +1,5 @@
+build-IdempotencyFunction:
+	chmod +x target/hello-world
+	cp target/hello-world $(ARTIFACTS_DIR) # (ARTIFACTS_DIR --> https://github.com/aws/aws-lambda-builders/blob/develop/aws_lambda_builders/workflows/custom_make/DESIGN.md#implementation)
+	chmod +x src/main/config/bootstrap
+	cp src/main/config/bootstrap $(ARTIFACTS_DIR)

examples/powertools-examples-idempotency/sam-graalvm/README.md

@@ -0,0 +1,61 @@
+# Powertools for AWS Lambda (Java) - Idempotency Example with SAM on GraalVM
+
+This project contains an example of a Lambda function using the idempotency module of Powertools for AWS Lambda (Java). For more information on this module, please refer to the [documentation](https://docs.powertools.aws.dev/lambda-java/utilities/idempotency/).
+
+The example exposes a HTTP POST endpoint. When the user sends the address of a webpage to it, the endpoint fetches the contents of the URL and returns them to the user.
+
+Have a look at [App.java](src/main/java/helloworld/App.java) for the full details.
+
+## Build the sample application
+
+> [!NOTE]
+> Building AWS Lambda packages on macOS (ARM64/Intel) for deployment on AWS Lambda (Linux x86_64 or ARM64) will result in incompatible binary dependencies that cause import errors at runtime.
+
+Choose the appropriate build method based on your operating system:
+
+### Build locally using Docker
+
+Recommended for macOS and Windows users: Cross-compile using Docker to match target platform of Lambda:
+
+```shell
+docker build --platform linux/amd64 . -t powertools-examples-idempotency-sam-graalvm
+docker run --platform linux/amd64 -it -v `pwd`:`pwd` -w `pwd` -v ~/.m2:/root/.m2 powertools-examples-idempotency-sam-graalvm mvn clean -Pnative-image package -DskipTests
+sam build --use-container --build-image powertools-examples-idempotency-sam-graalvm
+```
+
+**Note**: The Docker run command mounts your local Maven cache (`~/.m2`) and builds the native binary with SNAPSHOT support, then SAM packages the pre-built binary.
+
+### Build on native OS
+
+For Linux users with GraalVM installed:
+
+```shell
+export JAVA_HOME=<path to GraalVM>
+mvn clean -Pnative-image package -DskipTests
+sam build
+```
+
+## Deploy the sample application
+
+```shell
+sam deploy
+```
+
+This sample is based on Serverless Application Model (SAM). To deploy it, check out the instructions for getting started with SAM in [the examples directory](../../README.md)
+
+## Test the application
+
+```bash
+curl -X POST https://[REST-API-ID].execute-api.[REGION].amazonaws.com/Prod/helloidem/ -H "Content-Type: application/json" -d '{"address": "https://checkip.amazonaws.com"}'
+```
+
+this should return the contents of the webpage, for instance:
+
+```json
+{ "message": "hello world", "location": "123.123.123.1" }
+```
+
+- First call will execute the handleRequest normally, and store the response in the idempotency table (Look into DynamoDB)
+- Second call (and next ones) will retrieve from the cache (if cache is enabled, which is by default) or from the store, the handler won't be called. Until the expiration happens (by default 1 hour).
+
+Check out [App.java](src/main/java/helloworld/App.java) to see how it works!