feat(kafka): New Kafka utility

examples/pom.xml

@@ -39,6 +39,7 @@
         <module>powertools-examples-parameters/sam</module>
         <module>powertools-examples-parameters/sam-graalvm</module>
         <module>powertools-examples-serialization</module>
+        <module>powertools-examples-kafka</module>
         <module>powertools-examples-batch</module>
         <module>powertools-examples-validation</module>
         <module>powertools-examples-cloudformation</module>
@@ -58,4 +59,4 @@
         </plugins>
     </build>
 
-</project>
+</project>

examples/powertools-examples-kafka/README.md

@@ -0,0 +1,77 @@
+# Powertools for AWS Lambda (Java) - Kafka Example
+
+This project demonstrates how to use Powertools for AWS Lambda (Java) to deserialize Kafka Lambda events directly into strongly typed Kafka ConsumerRecords<K, V> using different serialization formats.
+
+## Overview
+
+The example showcases automatic deserialization of Kafka Lambda events into ConsumerRecords using three formats:
+- JSON - Using standard JSON serialization
+- Avro - Using Apache Avro schema-based serialization
+- Protobuf - Using Google Protocol Buffers serialization
+
+Each format has its own Lambda function handler that demonstrates how to use the `@Deserialization` annotation with the appropriate `DeserializationType`, eliminating the need to handle complex deserialization logic manually.
+
+## Build and Deploy
+
+### Prerequisites
+- [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+- Java 11+
+- Maven
+
+### Build
+
+```bash
+# Build the application
+sam build
+```
+
+### Deploy
+
+```bash
+# Deploy the application to AWS
+sam deploy --guided
+```
+
+During the guided deployment, you'll be prompted to provide values for required parameters. After deployment, SAM will output the ARNs of the deployed Lambda functions.
+
+### Build with Different Serialization Formats
+
+The project includes Maven profiles to build with different serialization formats:
+
+```bash
+# Build with JSON only (no Avro or Protobuf)
+mvn clean package -P base
+
+# Build with Avro only
+mvn clean package -P avro-only
+
+# Build with Protobuf only
+mvn clean package -P protobuf-only
+
+# Build with all formats (default)
+mvn clean package -P full
+```
+
+## Testing
+
+The `events` directory contains sample events for each serialization format:
+- `kafka-json-event.json` - Sample event with JSON-serialized products
+- `kafka-avro-event.json` - Sample event with Avro-serialized products
+- `kafka-protobuf-event.json` - Sample event with Protobuf-serialized products
+
+You can use these events to test the Lambda functions:
+
+```bash
+# Test the JSON deserialization function
+sam local invoke JsonDeserializationFunction --event events/kafka-json-event.json
+
+# Test the Avro deserialization function
+sam local invoke AvroDeserializationFunction --event events/kafka-avro-event.json
+
+# Test the Protobuf deserialization function
+sam local invoke ProtobufDeserializationFunction --event events/kafka-protobuf-event.json
+```
+
+## Sample Generator Tool
+
+The project includes a tool to generate sample JSON, Avro, and Protobuf serialized data. See the [tools/README.md](tools/README.md) for more information.

examples/powertools-examples-kafka/events/kafka-avro-event.json

@@ -0,0 +1,51 @@
+{
+  "eventSource": "aws:kafka",
+  "eventSourceArn": "arn:aws:kafka:us-east-1:0123456789019:cluster/SalesCluster/abcd1234-abcd-cafe-abab-9876543210ab-4",
+  "bootstrapServers": "b-2.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092,b-1.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092",
+  "records": {
+    "mytopic-0": [
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 15,
+        "timestamp": 1545084650987,
+        "timestampType": "CREATE_TIME",
+        "key": "NDI=",
+        "value": "0g8MTGFwdG9wUrgehes/j0A=",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      },
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 16,
+        "timestamp": 1545084650988,
+        "timestampType": "CREATE_TIME",
+        "key": "NDI=",
+        "value": "1A8UU21hcnRwaG9uZVK4HoXrv4JA",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      },
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 17,
+        "timestamp": 1545084650989,
+        "timestampType": "CREATE_TIME",
+        "key": null,
+        "value": "1g8USGVhZHBob25lc0jhehSuv2JA",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      }
+    ]
+  }
+}

examples/powertools-examples-kafka/events/kafka-json-event.json

@@ -0,0 +1,51 @@
+{
+  "eventSource": "aws:kafka",
+  "eventSourceArn": "arn:aws:kafka:us-east-1:0123456789019:cluster/SalesCluster/abcd1234-abcd-cafe-abab-9876543210ab-4",
+  "bootstrapServers": "b-2.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092,b-1.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092",
+  "records": {
+    "mytopic-0": [
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 15,
+        "timestamp": 1545084650987,
+        "timestampType": "CREATE_TIME",
+        "key": "NDI=",
+        "value": "eyJwcmljZSI6OTk5Ljk5LCJuYW1lIjoiTGFwdG9wIiwiaWQiOjEwMDF9",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      },
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 15,
+        "timestamp": 1545084650987,
+        "timestampType": "CREATE_TIME",
+        "key": "NDI=",
+        "value": "eyJwcmljZSI6NTk5Ljk5LCJuYW1lIjoiU21hcnRwaG9uZSIsImlkIjoxMDAyfQ==",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      },
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 15,
+        "timestamp": 1545084650987,
+        "timestampType": "CREATE_TIME",
+        "key": null,
+        "value": "eyJwcmljZSI6MTQ5Ljk5LCJuYW1lIjoiSGVhZHBob25lcyIsImlkIjoxMDAzfQ==",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      }
+    ]
+  }
+}

examples/powertools-examples-kafka/events/kafka-protobuf-event.json

@@ -0,0 +1,51 @@
+{
+  "eventSource": "aws:kafka",
+  "eventSourceArn": "arn:aws:kafka:us-east-1:0123456789019:cluster/SalesCluster/abcd1234-abcd-cafe-abab-9876543210ab-4",
+  "bootstrapServers": "b-2.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092,b-1.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092",
+  "records": {
+    "mytopic-0": [
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 15,
+        "timestamp": 1545084650987,
+        "timestampType": "CREATE_TIME",
+        "key": "NDI=",
+        "value": "COkHEgZMYXB0b3AZUrgehes/j0A=",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      },
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 16,
+        "timestamp": 1545084650988,
+        "timestampType": "CREATE_TIME",
+        "key": "NDI=",
+        "value": "COoHEgpTbWFydHBob25lGVK4HoXrv4JA",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      },
+      {
+        "topic": "mytopic",
+        "partition": 0,
+        "offset": 17,
+        "timestamp": 1545084650989,
+        "timestampType": "CREATE_TIME",
+        "key": null,
+        "value": "COsHEgpIZWFkcGhvbmVzGUjhehSuv2JA",
+        "headers": [
+          {
+            "headerKey": [104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101]
+          }
+        ]
+      }
+    ]
+  }
+}