Add @ExperimentalMiskApi (#3272)

Shamelessly cribbed from [ExperimentalOkHttpApi](https://github.com/square/okhttp/blob/54238b4c713080c3fd32fb1a070fb5d6814c9a09/okhttp/src/main/kotlin/okhttp3/ExperimentalOkHttpApi.kt), this new annotation will allow us to better communicate the unstable nature of new public classes and methods. This will allow us to more rapidly iterate on these features without worrying as much about breaking changes, which is good both for code authors and reviewers. It's also good for Misk users who will have a clearer signal about what is and isn't safe to start using.

This PR also demonstrates usage of the annotation by applying it to `TaggedLogger`, a class which was created recently and is being iterated on [right now](#3270).

Author: ean5533

CHANGELOG.md

@@ -7,6 +7,11 @@ The Changelog consequently will not be updated regularly since releases only inc
 
 Major and breaking changes will still be documented in the Changelog.
 
+Version 2024.05.22
+---------------------------------
+Breaking changes:
+- Added `@ExperimentalMiskApi` to `TaggedLogger`. Any code that uses this class will need to `@OptIn(ExperimentalMiskApi::class)`.
+
 Version 2024.05.16
 ---------------------------------
 Breaking changes:

misk-api/api/misk-api.api

@@ -1,3 +1,6 @@
+public abstract interface annotation class misk/annotation/ExperimentalMiskApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface class misk/api/HttpRequest {
 	public abstract fun getDispatchMechanism ()Lmisk/web/DispatchMechanism;
 	public abstract fun getRequestHeaders ()Lokhttp3/Headers;

misk-api/src/main/kotlin/misk/annotation/ExperimentalMiskApi.kt

@@ -0,0 +1,31 @@
+package misk.annotation
+
+/**
+ * Marks declarations that are experimental and subject to change without following SemVer
+ * conventions. Both binary and source-incompatible changes are possible, including complete removal
+ * of the experimental API.
+ *
+ * Do not use these APIs in modules that may be executed using a version of Misk different from
+ * the version the module was compiled with.
+ *
+ * Do not use these APIs in published libraries.
+ *
+ * Do not use these APIs if you aren't willing to track changes to them.
+ */
+@MustBeDocumented
+@Retention(value = AnnotationRetention.BINARY)
+@Target(
+  AnnotationTarget.CLASS,
+  AnnotationTarget.ANNOTATION_CLASS,
+  AnnotationTarget.PROPERTY,
+  AnnotationTarget.FIELD,
+  AnnotationTarget.LOCAL_VARIABLE,
+  AnnotationTarget.VALUE_PARAMETER,
+  AnnotationTarget.CONSTRUCTOR,
+  AnnotationTarget.FUNCTION,
+  AnnotationTarget.PROPERTY_GETTER,
+  AnnotationTarget.PROPERTY_SETTER,
+  AnnotationTarget.TYPEALIAS,
+)
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
+annotation class ExperimentalMiskApi

misk-aws/build.gradle.kts

@@ -30,6 +30,7 @@ dependencies {
   implementation(libs.prometheusClient)
   implementation(libs.slf4jApi)
   implementation(libs.tracingDatadog)
+  implementation(project(":misk-api"))
   implementation(project(":wisp:wisp-deployment"))
   implementation(project(":wisp:wisp-logging"))
   implementation(project(":wisp:wisp-tracing"))

misk-aws/src/main/kotlin/misk/jobqueue/sqs/SqsJobConsumer.kt

@@ -11,6 +11,7 @@ import io.opentracing.tag.StringTag
 import io.opentracing.tag.Tags
 import jakarta.inject.Inject
 import jakarta.inject.Singleton
+import misk.annotation.ExperimentalMiskApi
 import misk.feature.Feature
 import misk.feature.FeatureFlags
 import misk.jobqueue.JobConsumer
@@ -182,6 +183,7 @@ internal class SqsJobConsumer @Inject internal constructor(
       }.join()
     }
 
+    @OptIn(ExperimentalMiskApi::class)
     private fun handleMessages(messages: List<SqsJob>): List<CompletableFuture<Status>> {
       return messages.map { message ->
         CompletableFuture.supplyAsync(

misk-aws/src/test/kotlin/misk/jobqueue/sqs/TaggedLoggerJobQueueTest.kt

@@ -5,6 +5,7 @@ import ch.qos.logback.classic.spi.ILoggingEvent
 import com.amazonaws.services.sqs.AmazonSQS
 import com.amazonaws.services.sqs.model.CreateQueueRequest
 import jakarta.inject.Inject
+import misk.annotation.ExperimentalMiskApi
 import misk.clustering.fake.lease.FakeLeaseManager
 import misk.inject.KAbstractModule
 import misk.jobqueue.JobQueue
@@ -160,6 +161,7 @@ internal class TaggedLoggerJobQueueTest {
     val normalLogger = getLogger<TaggedLoggerJobQueueTest>()
   }
 
+  @OptIn(ExperimentalMiskApi::class)
   data class SqsJobQueueTestTaggedLogger<L: Any>(val logClass: KClass<L>, val tags: Set<Tag> = emptySet()): TaggedLogger<L, SqsJobQueueTestTaggedLogger<L>>(logClass, tags),
     Copyable<SqsJobQueueTestTaggedLogger<L>> {
     fun testTag(value: String) = tag(Tag("testTag", value))

misk/src/main/kotlin/misk/web/exceptions/ExceptionHandlingInterceptor.kt

@@ -5,6 +5,7 @@ import com.squareup.wire.GrpcStatus
 import com.squareup.wire.ProtoAdapter
 import jakarta.inject.Inject
 import misk.Action
+import misk.annotation.ExperimentalMiskApi
 import misk.exceptions.UnauthenticatedException
 import misk.exceptions.UnauthorizedException
 import misk.grpc.GrpcMessageSink
@@ -45,6 +46,7 @@ class ExceptionHandlingInterceptor(
   private val mapperResolver: ExceptionMapperResolver
 ) : NetworkInterceptor {
 
+  @OptIn(ExperimentalMiskApi::class)
   override fun intercept(chain: NetworkChain) {
     try {
       chain.proceed(chain.httpCall)

misk/src/test/kotlin/misk/web/exceptions/TaggedLoggerExceptionHandlingInterceptorTest.kt

@@ -1,9 +1,12 @@
+@file:OptIn(ExperimentalMiskApi::class)
+
 package misk.web.exceptions
 
 import ch.qos.logback.classic.Level
 import com.google.common.testing.FakeTicker
 import jakarta.inject.Inject
 import misk.MiskTestingServiceModule
+import misk.annotation.ExperimentalMiskApi
 import misk.inject.KAbstractModule
 import misk.logging.LogCollectorModule
 import misk.web.exceptions.TaggedLoggerExceptionHandlingInterceptorTest.LogMDCContextTestAction.LogMDCContextTestActionLogger.Companion.getTaggedLogger

wisp/wisp-logging/build.gradle.kts

@@ -6,6 +6,8 @@ dependencies {
     api(libs.kotlinLogging)
     api(libs.slf4jApi)
     api(project(":wisp:wisp-sampling"))
+  
+    implementation(project(":misk-api"))
 
     testImplementation(libs.assertj)
     testImplementation(libs.junitApi)

wisp/wisp-logging/src/main/kotlin/wisp/logging/TaggedLogger.kt

@@ -1,5 +1,6 @@
 package wisp.logging
 
+import misk.annotation.ExperimentalMiskApi
 import mu.KLogger
 import mu.KotlinLogging
 import org.slf4j.MDC
@@ -74,7 +75,7 @@ import kotlin.reflect.KClass
  *
  */
 
-
+@ExperimentalMiskApi
 abstract class TaggedLogger<L:Any, out R> (
   private val kLogger: KLogger,
   private val tags: Set<Tag>