feat: initial release of Developer Preview of DynamoDB Mapper for Kotlin (#1451)

* initial poc commit of DynamoDB Mapper (#1232)

* add support for Mapper initialization (#1237)

* implement mapper pipeline (#1266)

* initial implementation of codegen for low-level operations/types (#1357)

* initial implementation of secondary index support (#1375)

* Create new codegen module and refactor annotation processor to use it (#1382)

* feat: add Schema generator Gradle plugin (#1385)

* Fix plugin test package

* add attribute converters for "standard" values (#1381)

* fix: schema generator plugin test module (#1394)

* feat: annotation processor codegen configuration (#1392)

* feat: add `@DynamoDbIgnore` annotation (#1402)

* DDB Mapper filter expressions (runtime components) (#1401)

* feat: basic annotation processing (#1399)

* add DSL overloads, paginators, and better builder integration for DDB Mapper ops codegen (#1409)

* chore: split dynamodb-mapper-codegen into two modules (#1414)

* emit DDB_MAPPER business metric (#1426)

* feat: setup DynamoDbMapper publication (#1419)

* DDB Mapper filter expressions (codegen components) (#1424)

* correct docs

* mark every HLL/DDBM API experimental (#1428)

* fix accidental inclusion of expression attribute members in high-level DynamoDB Mapper requests (#1432)

* Upgrade to latest build plugin version

* fix: various issues found during testing (#1450)

* chore: update Athena changelog notes for 1.3.57 (2024-10-18) release (#1449)

* feat: update AWS API models

* feat: update AWS service endpoints metadata

* chore: release 1.3.60

* chore: bump snapshot version to 1.3.61-SNAPSHOT

* feat: initial release of Developer Preview of DynamoDB Mapper for Kotlin

* Fix Kotlin gradle-plugin version

* fix: ddb mapper tests (#1453)

* Bump build plugin version

---------

Co-authored-by: Matas <lauzmata@amazon.com>
Co-authored-by: aws-sdk-kotlin-ci <aws-kotlin-sdk-automation@amazon.com>

Author: 3 people

.brazil.json

@@ -1,19 +1,21 @@
 {
   "dependencies": {
+    "org.jetbrains.kotlin:kotlin-gradle-plugin:2.*": "KotlinGradlePlugin-2.x",
     "org.jetbrains.kotlin:kotlin-stdlib-common:2.*.*": "KotlinStdlibCommon-2.x",
     "org.jetbrains.kotlin:kotlin-stdlib-jdk8:2.*.*": "KotlinStdlibJdk8-2.x",
     "org.jetbrains.kotlin:kotlin-stdlib:2.*.*": "KotlinStdlib-2.x",
     "org.jetbrains.kotlinx:atomicfu:0.*.*": "Atomicfu-0.x",
     "org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.*": "KotlinxCoroutinesCoreJvm-1.x",
-    "org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:1.*": "KotlinxCoroutinesJdk8-1.x"
+    "org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:1.*": "KotlinxCoroutinesJdk8-1.x",
+    "com.google.devtools.ksp:symbol-processing-api:2.*": "Maven-com-google-devtools-ksp_symbol-processing-api-2.x",
+    "com.google.devtools.ksp:symbol-processing-gradle-plugin:2.*": "Maven-com-google-devtools-ksp_symbol-processing-gradle-plugin-2.x"
   },
   "packageHandlingRules": {
     "versioning": {
       "defaultVersionLayout": "{MAJOR}.0.x"
     },
     "ignore": [
       "aws.sdk.kotlin:bom",
-      "aws.sdk.kotlin.crt:aws-crt-kotlin-android",
       "aws.sdk.kotlin:testing",
       "aws.sdk.kotlin:version-catalog"
     ],

.changes/e4f3b5cb-9cdc-4bc7-b12d-e0a17b635f23.json

@@ -0,0 +1,9 @@
+{
+    "id": "e4f3b5cb-9cdc-4bc7-b12d-e0a17b635f23",
+    "type": "feature",
+    "description": "Initial release of Developer Preview of **DynamoDB Mapper** for Kotlin",
+    "issues": [
+        "awslabs/aws-sdk-kotlin#472"
+    ],
+    "module": "dynamodb-mapper"
+}

aws-runtime/aws-http/api/aws-http.api

@@ -141,6 +141,7 @@ public final class aws/sdk/kotlin/runtime/http/interceptors/AddUserAgentMetadata
 }
 
 public final class aws/sdk/kotlin/runtime/http/interceptors/AwsBusinessMetric : java/lang/Enum, aws/smithy/kotlin/runtime/businessmetrics/BusinessMetric {
+	public static final field DDB_MAPPER Laws/sdk/kotlin/runtime/http/interceptors/AwsBusinessMetric;
 	public static final field S3_EXPRESS_BUCKET Laws/sdk/kotlin/runtime/http/interceptors/AwsBusinessMetric;
 	public static fun getEntries ()Lkotlin/enums/EnumEntries;
 	public fun getIdentifier ()Ljava/lang/String;

aws-runtime/aws-http/common/src/aws/sdk/kotlin/runtime/http/interceptors/BusinessMetricsInterceptor.kt

@@ -64,4 +64,5 @@ private fun formatMetrics(metrics: MutableSet<String>): String {
 @InternalApi
 public enum class AwsBusinessMetric(public override val identifier: String) : BusinessMetric {
     S3_EXPRESS_BUCKET("J"),
+    DDB_MAPPER("d"),
 }

build.gradle.kts

@@ -145,6 +145,8 @@ configureNexus()
 val lintPaths = listOf(
     "**/*.{kt,kts}",
     "!**/generated-src/**",
+    "!**/generated/ksp/**",
+    "!**/kspCaches/**",
     "!**/smithyprojections/**",
 )
 

gradle.properties

@@ -14,4 +14,9 @@ smithyKotlinDocBaseUrl=https://sdk.amazonaws.com/kotlin/api/smithy-kotlin/api/$s
 # atomicfu
 kotlinx.atomicfu.enableJvmIrTransformation=true
 # FIXME - https://github.com/Kotlin/kotlinx-atomicfu/issues/274
-kotlinx.atomicfu.enableNativeIrTransformation=false
+kotlinx.atomicfu.enableNativeIrTransformation=false
+
+# https://github.com/google/ksp/blob/main/docs/ksp2.md
+# Disable KSP2 due to a bug around subsequent invocations
+# https://github.com/google/dagger/issues/4181 / https://github.com/google/ksp/issues/1678
+ksp.useKSP2=false

gradle/libs.versions.toml

@@ -1,8 +1,10 @@
 [versions]
 kotlin-version = "2.0.21"
+ksp-version = "2.0.21-1.0.25" # Keep in sync with kotlin-version
+
 dokka-version = "1.9.10"
 
-aws-kotlin-repo-tools-version = "0.4.13"
+aws-kotlin-repo-tools-version = "0.4.14"
 
 # libs
 coroutines-version = "1.9.0"
@@ -16,6 +18,7 @@ smithy-kotlin-codegen-version = "0.33.17"
 smithy-version = "1.51.0"
 
 # testing
+ddb-local-version = "2.5.2"
 junit-version = "5.10.5"
 kotest-version = "5.9.1"
 kotlinx-benchmark-version = "0.4.12"
@@ -26,8 +29,8 @@ slf4j-version = "2.0.16"
 [libraries]
 aws-kotlin-repo-tools-build-support = { module="aws.sdk.kotlin.gradle:build-support", version.ref = "aws-kotlin-repo-tools-version" }
 
-kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin-version"}
-kotlin-stdlib-jdk8 = { module = "org.jetbrains.kotlin:kotlin-stdlib-jdk8", version.ref = "kotlin-version"}
+kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin-version" }
+kotlin-stdlib-jdk8 = { module = "org.jetbrains.kotlin:kotlin-stdlib-jdk8", version.ref = "kotlin-version" }
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin-version" }
 kotlin-test-junit5 = { module = "org.jetbrains.kotlin:kotlin-test-junit5", version.ref = "kotlin-version" }
 dokka-core = { module = "org.jetbrains.dokka:dokka-core", version.ref = "dokka-version" }
@@ -42,6 +45,9 @@ kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-c
 kotlinx-coroutines-jdk8 = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-jdk8", version.ref = "coroutines-version" }
 kotlinx-coroutines-slf4j = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-slf4j", version.ref = "coroutines-version" }
 
+ksp-api = { module = "com.google.devtools.ksp:symbol-processing-api", version.ref = "ksp-version" }
+ksp-gradle-plugin = { module = "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin", version.ref = "ksp-version" }
+
 slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j-version" }
 slf4j-simple = { module = "org.slf4j:slf4j-simple", version.ref = "slf4j-version" }
 
@@ -107,6 +113,8 @@ kotlinx-benchmark-runtime = { module = "org.jetbrains.kotlinx:kotlinx-benchmark-
 kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization-version" }
 mockk = { module = "io.mockk:mockk", version.ref = "mockk-version" }
 
+ddb-local = { module = "com.amazonaws:DynamoDBLocal", version.ref = "ddb-local-version" }
+
 [bundles]
 # bundle of smithy-kotlin dependencies all AWS service clients have
 smithy-kotlin-service-client = [
@@ -134,6 +142,8 @@ kotlin-multiplatform = {id = "org.jetbrains.kotlin.multiplatform", version.ref =
 kotlinx-benchmark = { id = "org.jetbrains.kotlinx.benchmark", version.ref = "kotlinx-benchmark-version" }
 kotlinx-binary-compatibility-validator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version = "0.13.2" }
 kotlinx-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin-version"}
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp-version" }
 aws-kotlin-repo-tools-kmp = { id = "aws.sdk.kotlin.gradle.kmp", version.ref = "aws-kotlin-repo-tools-version" }
 aws-kotlin-repo-tools-smithybuild = { id = "aws.sdk.kotlin.gradle.smithybuild", version.ref = "aws-kotlin-repo-tools-version" }
 aws-kotlin-repo-tools-artifactsizemetrics = { id = "aws.sdk.kotlin.gradle.artifactsizemetrics", version.ref = "aws-kotlin-repo-tools-version" }
+gradle-plugin-publish = { id = "com.gradle.plugin-publish", version = "1.2.1"}

hll/build.gradle.kts

@@ -0,0 +1,115 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import aws.sdk.kotlin.gradle.dsl.configurePublishing
+import aws.sdk.kotlin.gradle.kmp.*
+import aws.smithy.kotlin.runtime.InternalApi
+import aws.smithy.kotlin.runtime.text.ensureSuffix
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+description = "High-level libraries for the AWS SDK for Kotlin"
+extra["displayName"] = "AWS :: SDK :: Kotlin :: HLL"
+extra["moduleName"] = "aws.sdk.kotlin.hll"
+
+// FIXME 🔽🔽🔽 This is all copied from :aws-runtime and should be commonized 🔽🔽🔽
+
+plugins {
+    alias(libs.plugins.dokka)
+    alias(libs.plugins.kotlinx.binary.compatibility.validator)
+    alias(libs.plugins.aws.kotlin.repo.tools.kmp) apply false
+    jacoco
+}
+
+val sdkVersion: String by project
+
+// capture locally - scope issue with custom KMP plugin
+val libraries = libs
+
+val optinAnnotations = listOf(
+    "aws.smithy.kotlin.runtime.ExperimentalApi",
+    "aws.smithy.kotlin.runtime.InternalApi",
+    "aws.sdk.kotlin.runtime.InternalSdkApi",
+    "kotlin.RequiresOptIn",
+)
+
+@OptIn(InternalApi::class)
+val hllPreviewVersion = if (sdkVersion.contains("-SNAPSHOT")) { // e.g. 1.3.29-beta-SNAPSHOT
+    sdkVersion
+        .removeSuffix("-SNAPSHOT")
+        .ensureSuffix("-beta-SNAPSHOT")
+} else {
+    sdkVersion.ensureSuffix("-beta") // e.g. 1.3.29-beta
+}
+
+subprojects {
+    group = "aws.sdk.kotlin"
+    version = hllPreviewVersion
+    configurePublishing("aws-sdk-kotlin")
+}
+
+subprojects {
+    if (!needsKmpConfigured) {
+        return@subprojects
+    }
+
+    apply {
+        plugin("org.jetbrains.kotlin.multiplatform")
+        plugin("org.jetbrains.dokka")
+        plugin(libraries.plugins.aws.kotlin.repo.tools.kmp.get().pluginId)
+    }
+
+    kotlin {
+        explicitApi()
+
+        sourceSets {
+            // dependencies available for all subprojects
+
+            all {
+                optinAnnotations.forEach(languageSettings::optIn)
+            }
+
+            named("commonTest") {
+                dependencies {
+                    implementation(libraries.kotest.assertions.core)
+                }
+            }
+
+            named("jvmTest") {
+                dependencies {
+                    implementation(libraries.kotest.assertions.core.jvm)
+                    implementation(libraries.slf4j.simple)
+                }
+            }
+        }
+    }
+
+    dependencies {
+        dokkaPlugin(project(":dokka-aws"))
+    }
+
+    tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_1_8)
+            freeCompilerArgs.add("-Xexpect-actual-classes")
+        }
+    }
+    tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinNativeCompile> {
+        compilerOptions {
+            freeCompilerArgs.add("-Xexpect-actual-classes")
+        }
+    }
+}
+
+apiValidation {
+    val availableSubprojects = subprojects.map { it.name }.toSet()
+
+    ignoredProjects += listOf(
+        "hll-codegen",
+        "dynamodb-mapper-codegen",
+        "dynamodb-mapper-ops-codegen",
+        "dynamodb-mapper-schema-codegen",
+        "dynamodb-mapper-schema-generator-plugin-test",
+    ).filter { it in availableSubprojects } // Some projects may not be in the build depending on bootstrapping
+}

hll/dynamodb-mapper/dynamodb-mapper-annotations/api/dynamodb-mapper-annotations.api

@@ -0,0 +1,17 @@
+public abstract interface annotation class aws/sdk/kotlin/hll/dynamodbmapper/DynamoDbAttribute : java/lang/annotation/Annotation {
+	public abstract fun name ()Ljava/lang/String;
+}
+
+public abstract interface annotation class aws/sdk/kotlin/hll/dynamodbmapper/DynamoDbIgnore : java/lang/annotation/Annotation {
+}
+
+public abstract interface annotation class aws/sdk/kotlin/hll/dynamodbmapper/DynamoDbItem : java/lang/annotation/Annotation {
+	public abstract fun converterName ()Ljava/lang/String;
+}
+
+public abstract interface annotation class aws/sdk/kotlin/hll/dynamodbmapper/DynamoDbPartitionKey : java/lang/annotation/Annotation {
+}
+
+public abstract interface annotation class aws/sdk/kotlin/hll/dynamodbmapper/DynamoDbSortKey : java/lang/annotation/Annotation {
+}
+

hll/dynamodb-mapper/dynamodb-mapper-annotations/build.gradle.kts

@@ -0,0 +1,8 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+description = "DynamoDbMapper annotations"
+extra["displayName"] = "AWS :: SDK :: Kotlin :: HLL :: DynamoDbMapper :: Annotations"
+extra["moduleName"] = "aws.sdk.kotlin.hll.dynamodbmapper.annotations"