Add tempest hybrid

settings.gradle.kts

@@ -11,6 +11,7 @@ include("tempest-testing-junit4")
 include("tempest-testing-junit5")
 include("tempest2")
 include("tempest2-testing")
+include("tempest-hybrid")
 include("tempest2-testing-internal")
 include("tempest2-testing-docker")
 include("tempest2-testing-jvm")

tempest-hybrid/build.gradle.kts

@@ -0,0 +1,41 @@
+import com.vanniktech.maven.publish.JavadocJar.Dokka
+import com.vanniktech.maven.publish.MavenPublishBaseExtension
+import com.vanniktech.maven.publish.KotlinJvm
+
+plugins {
+  kotlin("jvm")
+  `java-library`
+  id("com.vanniktech.maven.publish.base")
+}
+
+dependencies {
+  api(project(":tempest2"))
+
+  // AWS SDK for DynamoDB and S3
+  api(libs.awsDynamodb)
+  api("com.amazonaws:aws-java-sdk-s3:1.12.791")
+
+  // Jackson for JSON serialization
+  api(libs.jacksonDatabind)
+  api("com.fasterxml.jackson.module:jackson-module-kotlin:2.20.0")
+
+  // Logging
+  api(libs.slf4jApi)
+
+  // Kotlin
+  implementation(libs.kotlinReflection)
+  implementation(libs.kotlinStdLib)
+
+  // Testing
+  testImplementation(libs.assertj)
+  testImplementation(libs.junitEngine)
+  testImplementation(project(":tempest2-testing-jvm"))
+  testImplementation(project(":tempest2-testing-junit5"))
+  testRuntimeOnly(libs.junitLauncher)
+}
+
+configure<MavenPublishBaseExtension> {
+  configure(
+    KotlinJvm(javadocJar = Dokka("dokkaGfm"))
+  )
+}

tempest-hybrid/src/main/kotlin/app/cash/tempest/hybrid/HybridConfig.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2024 Square Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package app.cash.tempest.hybrid
+
+/** Configuration for pointer-based hybrid storage */
+data class HybridConfig(
+  val s3Config: S3Config,
+  val performanceConfig: PerformanceConfig = PerformanceConfig(),
+) {
+
+  data class S3Config(
+    val bucketName: String,
+    val keyPrefix: String = "", // Currently unused - could be used for S3 key generation
+    val region: String? = null, // Currently only used for logging
+  )
+
+  data class PerformanceConfig(
+    val maxConcurrentS3Reads: Int = 10, // Maximum concurrent S3 reads (0 = sequential)
+  )
+}

tempest-hybrid/src/main/kotlin/app/cash/tempest/hybrid/HybridDynamoDbFactory.kt

@@ -0,0 +1,62 @@
+package app.cash.tempest.hybrid
+
+import app.cash.tempest2.LogicalDb
+import com.amazonaws.services.s3.AmazonS3
+import com.fasterxml.jackson.databind.ObjectMapper
+import org.slf4j.LoggerFactory
+import software.amazon.awssdk.services.dynamodb.DynamoDbClient
+
+/**
+ * Factory for creating S3-aware DynamoDB components.
+ *
+ * This is the main entry point for enabling hybrid storage. It provides methods to wrap existing DynamoDB clients and
+ * LogicalDbs with S3-aware implementations that handle pointer items transparently.
+ */
+class HybridDynamoDbFactory(
+  private val s3Client: AmazonS3,
+  private val objectMapper: ObjectMapper,
+  private val hybridConfig: HybridConfig,
+) {
+
+  companion object {
+    private val logger = LoggerFactory.getLogger(HybridDynamoDbFactory::class.java)
+  }
+
+  /**
+   * Wraps a DynamoDbClient with S3-aware functionality.
+   *
+   * This wrapper intercepts query, scan, and getItem operations to detect and hydrate S3 pointer items before they
+   * reach Tempest.
+   *
+   * S3 pointer items can be minimal, containing only:
+   * - pk (partition key)
+   * - sk (sort key)
+   * - _s3_pointer (S3 location in format s3://bucket/key)
+   *
+   * The wrapper will automatically load the full data from S3 and replace the pointer item with the complete item.
+   */
+  fun wrapDynamoDbClient(client: DynamoDbClient): DynamoDbClient {
+    logger.info("🔧 Creating S3-aware DynamoDB client wrapper")
+    return S3AwareDynamoDbClient(
+      delegate = client,
+      s3Client = s3Client,
+      objectMapper = objectMapper,
+      hybridConfig = hybridConfig,
+    )
+  }
+
+  /**
+   * Wraps a LogicalDb with S3-aware functionality.
+   *
+   * This wrapper ensures that tables created from the LogicalDb use S3-aware codecs that can handle pointer items.
+   */
+  fun wrapLogicalDb(logicalDb: LogicalDb): LogicalDb {
+    logger.info("🔧 Creating S3-aware LogicalDb wrapper")
+    return S3AwareLogicalDb(
+      delegate = logicalDb,
+      s3Client = s3Client,
+      objectMapper = objectMapper,
+      hybridConfig = hybridConfig,
+    )
+  }
+}