Add deprecations on symbols that are getting removed in v4 (#5746)

* Add deprecations on symbols that are getting removed in v4

* Update API dump

* Next version is v3.8.3, not v3.8.4

* Un-deprecate CustomScalarAdapters.adapterContext as it's used in generated code, and it's probably not worth adding @Suppress("DEPRECATION") everywhere

libraries/apollo-api/src/commonMain/kotlin/com/apollographql/apollo3/api/ApolloRequest.kt

@@ -1,5 +1,7 @@
 package com.apollographql.apollo3.api
 
+import com.apollographql.apollo3.annotations.ApolloDeprecatedSince
+import com.apollographql.apollo3.annotations.ApolloDeprecatedSince.Version.v3_8_3
 import com.apollographql.apollo3.annotations.ApolloExperimental
 import com.apollographql.apollo3.api.http.HttpHeader
 import com.apollographql.apollo3.api.http.HttpMethod
@@ -25,7 +27,7 @@ private constructor(
   fun newBuilder(): Builder<D> = newBuilder(operation)
 
   @ApolloExperimental
-  fun <E: Operation.Data> newBuilder(operation: Operation<E>): Builder<E> {
+  fun <E : Operation.Data> newBuilder(operation: Operation<E>): Builder<E> {
     return Builder(operation)
         .requestUuid(requestUuid)
         .executionContext(executionContext)
@@ -43,44 +45,72 @@ private constructor(
   ) : MutableExecutionOptions<Builder<D>> {
     private var requestUuid: Uuid = uuid4()
     override var executionContext: ExecutionContext = ExecutionContext.Empty
+      @Deprecated("Use addExecutionContext() instead")
+      @ApolloDeprecatedSince(v3_8_3)
+      set
 
     override var httpMethod: HttpMethod? = null
+      @Deprecated("Use httpMethod() instead")
+      @ApolloDeprecatedSince(v3_8_3)
+      set
 
     override fun httpMethod(httpMethod: HttpMethod?): Builder<D> = apply {
+      @Suppress("DEPRECATION")
       this.httpMethod = httpMethod
     }
 
     override var httpHeaders: List<HttpHeader>? = null
+      @Deprecated("Use httpHeaders() instead")
+      @ApolloDeprecatedSince(v3_8_3)
+      set
 
     override fun httpHeaders(httpHeaders: List<HttpHeader>?): Builder<D> = apply {
+      @Suppress("DEPRECATION")
       this.httpHeaders = httpHeaders
     }
 
     override fun addHttpHeader(name: String, value: String): Builder<D> = apply {
+      @Suppress("DEPRECATION")
       this.httpHeaders = (this.httpHeaders ?: emptyList()) + HttpHeader(name, value)
     }
 
     override var sendApqExtensions: Boolean? = null
+      @Deprecated("Use sendApqExtensions() instead")
+      @ApolloDeprecatedSince(v3_8_3)
+      set
 
     override fun sendApqExtensions(sendApqExtensions: Boolean?): Builder<D> = apply {
+      @Suppress("DEPRECATION")
       this.sendApqExtensions = sendApqExtensions
     }
 
     override var sendDocument: Boolean? = null
+      @Deprecated("Use sendDocument() instead")
+      @ApolloDeprecatedSince(v3_8_3)
+      set
 
     override fun sendDocument(sendDocument: Boolean?): Builder<D> = apply {
+      @Suppress("DEPRECATION")
       this.sendDocument = sendDocument
     }
 
     override var enableAutoPersistedQueries: Boolean? = null
+      @Deprecated("Use enableAutoPersistedQueries() instead")
+      @ApolloDeprecatedSince(v3_8_3)
+      set
 
     override fun enableAutoPersistedQueries(enableAutoPersistedQueries: Boolean?): Builder<D> = apply {
+      @Suppress("DEPRECATION")
       this.enableAutoPersistedQueries = enableAutoPersistedQueries
     }
 
     override var canBeBatched: Boolean? = null
+      @Deprecated("Use canBeBatched() instead")
+      @ApolloDeprecatedSince(v3_8_3)
+      set
 
     override fun canBeBatched(canBeBatched: Boolean?): Builder<D> = apply {
+      @Suppress("DEPRECATION")
       this.canBeBatched = canBeBatched
     }
 
@@ -89,15 +119,16 @@ private constructor(
     }
 
     fun executionContext(executionContext: ExecutionContext) = apply {
+      @Suppress("DEPRECATION")
       this.executionContext = executionContext
     }
 
     override fun addExecutionContext(executionContext: ExecutionContext) = apply {
+      @Suppress("DEPRECATION")
       this.executionContext = this.executionContext + executionContext
     }
 
     fun build(): ApolloRequest<D> {
-      @Suppress("DEPRECATION")
       return ApolloRequest(
           operation = operation,
           requestUuid = requestUuid,

libraries/apollo-api/src/commonMain/kotlin/com/apollographql/apollo3/api/CompiledGraphQL.kt

@@ -5,6 +5,7 @@ package com.apollographql.apollo3.api
 import com.apollographql.apollo3.annotations.ApolloDeprecatedSince
 import com.apollographql.apollo3.annotations.ApolloDeprecatedSince.Version.v3_0_1
 import com.apollographql.apollo3.annotations.ApolloDeprecatedSince.Version.v3_3_3
+import com.apollographql.apollo3.annotations.ApolloDeprecatedSince.Version.v3_8_3
 import com.apollographql.apollo3.annotations.ApolloExperimental
 import com.apollographql.apollo3.api.json.BufferedSinkJsonWriter
 import com.apollographql.apollo3.api.json.writeAny
@@ -36,6 +37,7 @@ class CompiledField internal constructor(
       name: String,
       variables: Executable.Variables,
   ): Any? {
+    @Suppress("DEPRECATION")
     return resolveVariables(arguments.firstOrNull { it.name == name }?.value, variables)
   }
 
@@ -55,6 +57,7 @@ class CompiledField internal constructor(
       return name
     }
     val map = arguments.associateBy { it.name }.mapValues { it.value.value }
+    @Suppress("DEPRECATION")
     val resolvedArguments = resolveVariables(map, variables)
     return try {
       val buffer = Buffer()
@@ -136,7 +139,7 @@ class CompiledFragment internal constructor(
 }
 
 data class CompiledCondition(val name: String, val inverted: Boolean, val defaultValue: Boolean) {
-  constructor(name: String, inverted: Boolean): this(name, inverted, true)
+  constructor(name: String, inverted: Boolean) : this(name, inverted, true)
 
   fun copy(name: String = this.name, inverted: Boolean = this.inverted) = CompiledCondition(name, inverted, defaultValue)
 }
@@ -168,7 +171,7 @@ sealed class CompiledNamedType(val name: String) : CompiledType() {
 /**
  * A GraphQL scalar type that is mapped to a Kotlin. This is named "Custom" for historical reasons
  * but is also used for builtin scalars
- * 
+ *
  * TODO v4: rename this to ScalarType
  */
 class CustomScalarType(
@@ -302,11 +305,11 @@ class InputObjectType(
 
 class EnumType(
     name: String,
-    val values: List<String>
+    val values: List<String>,
 ) : CompiledNamedType(name) {
   @Deprecated("Use the primary constructor instead")
   @ApolloDeprecatedSince(ApolloDeprecatedSince.Version.v3_5_1)
-  constructor(name: String): this(name, emptyList())
+  constructor(name: String) : this(name, emptyList())
 }
 
 /**
@@ -383,13 +386,16 @@ class CompiledArgument private constructor(
 /**
  * Resolve all variables that may be contained inside `value`
  */
-@Suppress("UNCHECKED_CAST")
+@Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+@ApolloDeprecatedSince(v3_8_3)
+@Suppress("UNCHECKED_CAST", "DEPRECATION")
 fun resolveVariables(value: Any?, variables: Executable.Variables): Any? {
   return when (value) {
     null -> null
     is CompiledVariable -> {
       variables.valueMap[value.name]
     }
+
     is Map<*, *> -> {
       value as Map<String, Any?>
       value.mapValues {
@@ -398,11 +404,13 @@ fun resolveVariables(value: Any?, variables: Executable.Variables): Any? {
           .sortedBy { it.first }
           .toMap()
     }
+
     is List<*> -> {
       value.map {
         resolveVariables(it, variables)
       }
     }
+
     else -> value
   }
 }
@@ -467,6 +475,7 @@ fun CompiledNamedType.isComposite(): Boolean {
     is InterfaceType,
     is ObjectType,
     -> true
+
     else
     -> false
   }

libraries/apollo-api/src/commonMain/kotlin/com/apollographql/apollo3/api/CustomScalarAdapters.kt

@@ -16,8 +16,11 @@ class CustomScalarAdapters private constructor(
     // This is currently used for @skip/@include and @defer.
     // Ideally it should be passed as its own parameter, but we're avoiding a breaking change.
     // See https://github.com/apollographql/apollo-kotlin/pull/3813
+    /**
+     * Note: this shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.
+     */
     val adapterContext: AdapterContext,
-    private val unsafe: Boolean
+    private val unsafe: Boolean,
 ) : ExecutionContext.Element {
 
   private val adaptersMap: Map<String, Adapter<*>> = customScalarAdapters
@@ -62,6 +65,7 @@ class CustomScalarAdapters private constructor(
 
   @Deprecated("Use adapterContext.variables() instead", ReplaceWith("adapterContext.variables()"))
   @ApolloDeprecatedSince(v3_2_1)
+  @Suppress("DEPRECATION")
   fun variables() = adapterContext.variables()
 
   override val key: ExecutionContext.Key<*>
@@ -120,7 +124,6 @@ class CustomScalarAdapters private constructor(
       adaptersMap.clear()
     }
 
-    @Suppress("DEPRECATION")
     fun build() = CustomScalarAdapters(adaptersMap, adapterContext, unsafe)
 
     fun adapterContext(adapterContext: AdapterContext): Builder = apply {

libraries/apollo-api/src/commonMain/kotlin/com/apollographql/apollo3/api/Executables.kt

@@ -8,7 +8,6 @@ import com.apollographql.apollo3.api.json.MapJsonWriter
 import okio.Buffer
 import kotlin.jvm.JvmName
 
-@Suppress("UNCHECKED_CAST")
 fun <D : Executable.Data> Executable<D>.variables(customScalarAdapters: CustomScalarAdapters): Executable.Variables {
   return variables(customScalarAdapters, false)
 }

libraries/apollo-gradle-plugin-external/src/main/kotlin/com/apollographql/apollo3/gradle/api/Service.kt

@@ -4,6 +4,7 @@ import com.android.build.gradle.api.BaseVariant
 import com.apollographql.apollo3.annotations.ApolloDeprecatedSince
 import com.apollographql.apollo3.annotations.ApolloDeprecatedSince.Version.v3_0_0
 import com.apollographql.apollo3.annotations.ApolloDeprecatedSince.Version.v3_0_1
+import com.apollographql.apollo3.annotations.ApolloDeprecatedSince.Version.v3_8_3
 import com.apollographql.apollo3.annotations.ApolloExperimental
 import com.apollographql.apollo3.compiler.OperationIdGenerator
 import com.apollographql.apollo3.compiler.OperationOutputGenerator
@@ -334,6 +335,8 @@ interface Service {
    *
    * Default value: false
    */
+  @Deprecated("Used for backward compat with 2.x, will be removed in a future version")
+  @ApolloDeprecatedSince(v3_8_3)
   val useSchemaPackageNameForFragments: Property<Boolean>
 
   /**
@@ -540,8 +543,10 @@ interface Service {
    * The directory where the test builders will be written.
    * If you want a [DirectoryProperty] that carries the task dependency, use [outputDirConnection]
    */
+  @Deprecated("Test builders are operation based and generate a lot of code. Use data builders instead")
+  @ApolloDeprecatedSince(v3_8_3)
   val testDir: DirectoryProperty
-  
+
   /**
    * Whether to generate the operationOutput.json
    *
@@ -853,6 +858,8 @@ interface Service {
    * - commonTest sourceSet for Kotlin multiplatform projects
    * - test *and* androidTest variants for Android projects
    */
+  @Deprecated("Test builders are operation based and generate a lot of code. Use data builders instead")
+  @ApolloDeprecatedSince(v3_8_3)
   fun testDirConnection(action: Action<in DirectoryConnection>)
 
   /**

libraries/apollo-http-cache/src/main/kotlin/com/apollographql/apollo3/cache/http/CachingHttpInterceptor.kt

@@ -1,6 +1,7 @@
 package com.apollographql.apollo3.cache.http
 
 import com.apollographql.apollo3.annotations.ApolloDeprecatedSince
+import com.apollographql.apollo3.annotations.ApolloDeprecatedSince.Version.v3_8_3
 import com.apollographql.apollo3.api.http.DefaultHttpRequestComposer
 import com.apollographql.apollo3.api.http.HttpHeader
 import com.apollographql.apollo3.api.http.HttpMethod
@@ -33,6 +34,7 @@ class CachingHttpInterceptor internal constructor(
 
   val cache: ApolloHttpCache = lruHttpCache
 
+  @Suppress("DEPRECATION")
   override suspend fun intercept(request: HttpRequest, chain: HttpInterceptorChain): HttpResponse {
     val policy = request.headers.valueOf(CACHE_FETCH_POLICY_HEADER) ?: defaultPolicy(request)
     val cacheKey = request.headers.valueOf(CACHE_KEY_HEADER)!!
@@ -98,6 +100,7 @@ class CachingHttpInterceptor internal constructor(
     }
   }
 
+  @Suppress("DEPRECATION")
   private fun defaultPolicy(request: HttpRequest): String {
     return if (request.headers.firstOrNull { it.name == CACHE_OPERATION_TYPE_HEADER }?.value == "query") {
       CACHE_FIRST
@@ -106,6 +109,7 @@ class CachingHttpInterceptor internal constructor(
     }
   }
 
+  @Suppress("DEPRECATION")
   private suspend fun networkMightThrow(request: HttpRequest, chain: HttpInterceptorChain, cacheKey: String): HttpResponse {
     val response = chain.proceed(request)
 
@@ -127,6 +131,7 @@ class CachingHttpInterceptor internal constructor(
     return response
   }
 
+  @Suppress("DEPRECATION")
   private fun cacheMightThrow(request: HttpRequest, cacheKey: String): HttpResponse {
     val operationName = request.headers.valueOf(DefaultHttpRequestComposer.HEADER_APOLLO_OPERATION_NAME)
     val response = try {
@@ -193,51 +198,75 @@ class CachingHttpInterceptor internal constructor(
       }
     }
 
-    /**
-     *
-     */
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_KEY_HEADER = "X-APOLLO-CACHE-KEY"
 
     internal const val REQUEST_UUID_HEADER = "X-APOLLO-REQUEST-UUID"
 
     /**
      * Cache fetch strategy http header
      */
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_FETCH_POLICY_HEADER = "X-APOLLO-CACHE-FETCH-POLICY"
 
     /**
      * Cache operation type http header
      */
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_OPERATION_TYPE_HEADER = "X-APOLLO-CACHE-OPERATION-TYPE"
 
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_ONLY = "CACHE_ONLY"
+
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val NETWORK_ONLY = "NETWORK_ONLY"
+
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_FIRST = "CACHE_FIRST"
+
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val NETWORK_FIRST = "NETWORK_FIRST"
 
     /**
      * Request served Date/time http header
      */
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_SERVED_DATE_HEADER = "X-APOLLO-SERVED-DATE"
 
     /**
      * Cached response expiration timeout http header (in millisecond)
      */
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_EXPIRE_TIMEOUT_HEADER = "X-APOLLO-EXPIRE-TIMEOUT"
 
     /**
      * Expire cached response flag http header
      */
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_EXPIRE_AFTER_READ_HEADER = "X-APOLLO-EXPIRE-AFTER-READ"
 
     /**
      * Do not store the http response
      */
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val CACHE_DO_NOT_STORE = "X-APOLLO-CACHE-DO-NOT-STORE"
 
     /**
      * Signals that HTTP response comes from the local cache
      */
+    @Deprecated("This shouldn't be part of the public API and will be removed in Apollo Kotlin 4. If you needed this, please open an issue.")
+    @ApolloDeprecatedSince(v3_8_3)
     const val FROM_CACHE = "X-APOLLO-FROM-CACHE"
   }
 }