feat: binary compatibility validator (#808)

CONTRIBUTING.md

@@ -179,6 +179,18 @@ across both repos, it's best to create/use the same branch name in both location
 
 This check enforces the changelog requirements [described above](#Changelog).
 
+#### Binary Compatibility Validation
+This repository uses [Kotlin's binary compatibility validator plugin](https://github.com/Kotlin/binary-compatibility-validator)
+to help preserve backwards compatibility across releases.
+
+The plugin will automatically run during a build with no extra steps needed from the developer.
+If a backwards incompatible change is introduced, the build will fail.
+
+If the backwards incompatibility is expected, the appropriate `.api` files must be updated as part of the PR.
+The `.api` files can be updated by running `./gradlew apiDump`.
+
+The binary compatibility validator can also be run manually using `./gradlew apiCheck`.
+
 ## Finding contributions to work on
 Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
 

build.gradle.kts

@@ -20,6 +20,7 @@ plugins {
     kotlin("jvm") apply false
     id("org.jetbrains.dokka")
     id("io.github.gradle-nexus.publish-plugin") version "1.1.0"
+    id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.12.1"
 }
 
 allprojects {
@@ -161,3 +162,27 @@ tasks.register<JavaExec>("ktlintFormat") {
     main = "com.pinterest.ktlint.Main"
     args = listOf("-F") + lintPaths
 }
+
+apiValidation {
+    nonPublicMarkers.add("aws.smithy.kotlin.runtime.InternalApi")
+
+    ignoredProjects.addAll(setOf(
+        "dokka-smithy",
+        "ktlint-rules",
+        "aws-signing-tests",
+        "test-suite",
+        "http-test",
+        "smithy-test",
+        "testing",
+        "smithy-kotlin-codegen",
+        "smithy-kotlin-codegen-testutils",
+        "aws-signing-benchmarks",
+        "channel-benchmarks",
+        "http-benchmarks",
+        "serde-benchmarks",
+        "serde-benchmarks-codegen",
+        "paginator-tests",
+        "waiter-tests",
+        "compile"
+    ))
+}

runtime/auth/aws-credentials/api/aws-credentials.api

@@ -0,0 +1,51 @@
+public final class aws/smithy/kotlin/runtime/auth/awscredentials/CachedCredentialsProvider : aws/smithy/kotlin/runtime/auth/awscredentials/CloseableCredentialsProvider {
+	public synthetic fun <init> (Laws/smithy/kotlin/runtime/auth/awscredentials/CredentialsProvider;JJLaws/smithy/kotlin/runtime/time/Clock;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public synthetic fun <init> (Laws/smithy/kotlin/runtime/auth/awscredentials/CredentialsProvider;JJLaws/smithy/kotlin/runtime/time/Clock;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun close ()V
+	public fun getCredentials (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+}
+
+public final class aws/smithy/kotlin/runtime/auth/awscredentials/CachedCredentialsProviderKt {
+	public static final field DEFAULT_CREDENTIALS_REFRESH_SECONDS I
+}
+
+public abstract interface class aws/smithy/kotlin/runtime/auth/awscredentials/CloseableCredentialsProvider : aws/smithy/kotlin/runtime/auth/awscredentials/CredentialsProvider, java/io/Closeable {
+}
+
+public final class aws/smithy/kotlin/runtime/auth/awscredentials/Credentials {
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Laws/smithy/kotlin/runtime/time/Instant;Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Laws/smithy/kotlin/runtime/time/Instant;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun component2 ()Ljava/lang/String;
+	public final fun component3 ()Ljava/lang/String;
+	public final fun component4 ()Laws/smithy/kotlin/runtime/time/Instant;
+	public final fun component5 ()Ljava/lang/String;
+	public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Laws/smithy/kotlin/runtime/time/Instant;Ljava/lang/String;)Laws/smithy/kotlin/runtime/auth/awscredentials/Credentials;
+	public static synthetic fun copy$default (Laws/smithy/kotlin/runtime/auth/awscredentials/Credentials;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Laws/smithy/kotlin/runtime/time/Instant;Ljava/lang/String;ILjava/lang/Object;)Laws/smithy/kotlin/runtime/auth/awscredentials/Credentials;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getAccessKeyId ()Ljava/lang/String;
+	public final fun getExpiration ()Laws/smithy/kotlin/runtime/time/Instant;
+	public final fun getProviderName ()Ljava/lang/String;
+	public final fun getSecretAccessKey ()Ljava/lang/String;
+	public final fun getSessionToken ()Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public abstract interface class aws/smithy/kotlin/runtime/auth/awscredentials/CredentialsProvider {
+	public abstract fun getCredentials (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+}
+
+public class aws/smithy/kotlin/runtime/auth/awscredentials/CredentialsProviderChain : aws/smithy/kotlin/runtime/auth/awscredentials/CloseableCredentialsProvider {
+	public fun <init> ([Laws/smithy/kotlin/runtime/auth/awscredentials/CredentialsProvider;)V
+	public fun close ()V
+	public fun getCredentials (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	protected final fun getProviders ()[Laws/smithy/kotlin/runtime/auth/awscredentials/CredentialsProvider;
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class aws/smithy/kotlin/runtime/auth/awscredentials/CredentialsProviderException : aws/smithy/kotlin/runtime/ClientException {
+	public fun <init> (Ljava/lang/String;Ljava/lang/Throwable;)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+}
+