Merge branch 'main' into fix/async-adaptation-failure-delivery

Author: OmarAlJarrah

build.gradle.kts

@@ -142,6 +142,11 @@ allprojects {
 
         dependencies {
             add("compileOnly", libs.slf4j.api)
+            // Modern nullability annotations on the compile classpath. kotlin-stdlib pins the ancient
+            // org.jetbrains:annotations:13.0 transitively, which lacks @UnknownNullability; Kotlin 2.4.0
+            // tooling materialises inferred platform types with that annotation and reports it as
+            // inaccessible against 13.0. compileOnly keeps it out of the published POM and ABI.
+            add("compileOnly", libs.jetbrains.annotations)
         }
     }
 

docs/pipelines.md

@@ -232,6 +232,29 @@ fed to the next recovery step — recovery exceptions never bypass downstream re
 pipeline's `apply` method never throws; callers inspect the returned outcome to decide whether
 to surface a `Response` or rethrow.
 
+#### Close ownership: discarding a `Success` response
+
+When a step is handed a `ResponseOutcome.Success`, the wrapped `Response` holds an open
+transport connection / body stream that must be closed exactly once. The `ResponsePipeline`
+takes that responsibility on **only one path: when a step throws while holding the response.**
+Both the success-path (`applyResponseSteps`) and the recovery chain (`invokeRecovery`)
+close-before-propagate — they close the in-hand response and attach any close error to the
+step's throwable as suppressed, so a throwing step never strands the connection.
+
+The pipeline does **not** close the response on the path where a step is handed a `Success` and
+*deliberately returns a different outcome*:
+
+- **Success → Failure transform** — e.g. a status-to-typed-exception recovery step that turns a
+  `Success(response)` into a `Failure(HttpException)`. The original successful `response` is
+  discarded.
+- **Success → substitute Success** — replacing the response with a different one.
+
+On both of these the pipeline never observes the dropped response, so **the step that performs
+the transform owns closing the response it discards**. Such a step must call
+`outcome.response.close()` on the response it is dropping before returning the replacement
+outcome, or the connection leaks. (The recovery "Replace" path — `Failure(t1)` → `Failure(t2)`
+— operates on a `Failure`, which carries no response, so there is nothing to close there.)
+
 ### ResponseOutcome
 
 ```kotlin

gradle/libs.versions.toml

@@ -1,7 +1,11 @@
 [versions]
-kotlin = "2.3.21"
+kotlin = "2.4.0"
 kotlinx-coroutines = "1.11.0"
 slf4j = "2.0.18"
+# Compile-only nullability annotations (@NotNull/@Nullable/@UnknownNullability). kotlin-stdlib drags
+# in the ancient 13.0 transitively, which predates UnknownNullability; Kotlin 2.4.0 tooling materialises
+# inferred platform types with that annotation, so a modern version must be on the compile classpath.
+jetbrains-annotations = "26.0.2"
 okio = "3.17.0"
 okhttp = "5.0.0"
 mockwebserver = "5.0.0"
@@ -10,15 +14,17 @@ netty = "4.2.13.Final"
 jackson = "2.18.2"
 junit-jupiter = "5.10.2"
 # R8 is used only by the test-only sdk-shrink-test module to verify the SDK survives consumer-side
-# shrinking. It is fetched from Google's Maven repo and never enters a published artifact.
-r8 = "8.9.35"
+# shrinking. It is fetched from Google's Maven repo and never enters a published artifact. Kept current
+# with the Kotlin bump so R8 can parse the metadata version emitted by the Kotlin compiler.
+r8 = "9.1.31"
 kover = "0.9.8"
 binary-compatibility-validator = "0.16.3"
 ktlint-plugin = "12.1.1"
 detekt = "1.23.6"
 
 [libraries]
 kotlin-reflect = { module = "org.jetbrains.kotlin:kotlin-reflect", version.ref = "kotlin" }
+jetbrains-annotations = { module = "org.jetbrains:annotations", version.ref = "jetbrains-annotations" }
 slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }
 slf4j-nop = { module = "org.slf4j:slf4j-nop", version.ref = "slf4j" }
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }

sdk-async-virtualthreads/src/main/kotlin/org/dexpace/sdk/async/virtualthreads/MdcAwareExecutor.kt

@@ -44,32 +44,36 @@ import java.util.concurrent.TimeUnit
  * [VirtualThreadAsyncHttpClient] for the `close()` path so shutdown semantics are unchanged.
  */
 internal class MdcAwareExecutor(private val delegate: ExecutorService) : ExecutorService by delegate {
+    private fun MdcSnapshot.wrap(command: Runnable): Runnable = Runnable { withMdc { command.run() } }
+
+    private fun <T> MdcSnapshot.wrap(task: Callable<T>): Callable<T> = Callable { withMdc { task.call() } }
+
     override fun execute(command: Runnable) {
         val snapshot = MdcSnapshot.capture()
-        delegate.execute { snapshot.withMdc { command.run() } }
+        delegate.execute(snapshot.wrap(command))
     }
 
     override fun <T : Any?> submit(task: Callable<T>): Future<T> {
         val snapshot = MdcSnapshot.capture()
-        return delegate.submit(Callable { snapshot.withMdc { task.call() } })
+        return delegate.submit(snapshot.wrap(task))
     }
 
     override fun submit(task: Runnable): Future<*> {
         val snapshot = MdcSnapshot.capture()
-        return delegate.submit { snapshot.withMdc { task.run() } }
+        return delegate.submit(snapshot.wrap(task))
     }
 
     override fun <T : Any?> submit(
         task: Runnable,
         result: T,
     ): Future<T> {
         val snapshot = MdcSnapshot.capture()
-        return delegate.submit({ snapshot.withMdc { task.run() } }, result)
+        return delegate.submit(snapshot.wrap(task), result)
     }
 
     override fun <T : Any?> invokeAll(tasks: MutableCollection<out Callable<T>>): MutableList<Future<T>> {
         val snapshot = MdcSnapshot.capture()
-        return delegate.invokeAll(tasks.map { task -> Callable { snapshot.withMdc { task.call() } } })
+        return delegate.invokeAll(tasks.map { task -> snapshot.wrap(task) })
     }
 
     override fun <T : Any?> invokeAll(
@@ -78,12 +82,12 @@ internal class MdcAwareExecutor(private val delegate: ExecutorService) : Executo
         unit: TimeUnit,
     ): MutableList<Future<T>> {
         val snapshot = MdcSnapshot.capture()
-        return delegate.invokeAll(tasks.map { task -> Callable { snapshot.withMdc { task.call() } } }, timeout, unit)
+        return delegate.invokeAll(tasks.map { task -> snapshot.wrap(task) }, timeout, unit)
     }
 
     override fun <T : Any?> invokeAny(tasks: MutableCollection<out Callable<T>>): T {
         val snapshot = MdcSnapshot.capture()
-        return delegate.invokeAny(tasks.map { task -> Callable { snapshot.withMdc { task.call() } } })
+        return delegate.invokeAny(tasks.map { task -> snapshot.wrap(task) })
     }
 
     override fun <T : Any?> invokeAny(
@@ -92,6 +96,6 @@ internal class MdcAwareExecutor(private val delegate: ExecutorService) : Executo
         unit: TimeUnit,
     ): T {
         val snapshot = MdcSnapshot.capture()
-        return delegate.invokeAny(tasks.map { task -> Callable { snapshot.withMdc { task.call() } } }, timeout, unit)
+        return delegate.invokeAny(tasks.map { task -> snapshot.wrap(task) }, timeout, unit)
     }
 }

sdk-async-virtualthreads/src/main/kotlin/org/dexpace/sdk/async/virtualthreads/VirtualThreads.kt

@@ -80,6 +80,10 @@ public class VirtualThreadAsyncHttpClient internal constructor(
      * Shuts down the virtual-thread executor and waits for in-flight tasks to complete.
      * Idempotent: a second (or later) call returns immediately without touching the executor
      * or logging again.
+     *
+     * The `executor.closed` event is logged at DEBUG by design: closing the executor is a
+     * routine lifecycle event, not an operationally noteworthy condition that warrants a
+     * higher level.
      */
     override fun close() {
         if (!closed.compareAndSet(false, true)) return

sdk-core/api/sdk-core.api

@@ -28,6 +28,8 @@ public final class org/dexpace/sdk/core/config/Configuration {
 	public static final field LOG_LEVEL Ljava/lang/String;
 	public static final field MAX_RETRY_ATTEMPTS Ljava/lang/String;
 	public static final field NO_PROXY Ljava/lang/String;
+	public static final fun builder ()Lorg/dexpace/sdk/core/config/ConfigurationBuilder;
+	public final fun derive (Ljava/util/function/Consumer;)Lorg/dexpace/sdk/core/config/Configuration;
 	public final fun get (Ljava/lang/String;)Ljava/lang/String;
 	public final fun get (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String;
 	public static synthetic fun get$default (Lorg/dexpace/sdk/core/config/Configuration;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Ljava/lang/String;
@@ -36,20 +38,25 @@ public final class org/dexpace/sdk/core/config/Configuration {
 	public static final fun getGlobalConfiguration ()Lorg/dexpace/sdk/core/config/Configuration;
 	public final fun getInt (Ljava/lang/String;I)I
 	public final fun getProperty (Ljava/lang/String;)Ljava/lang/String;
+	public final fun newBuilder ()Lorg/dexpace/sdk/core/config/ConfigurationBuilder;
 	public static final fun setGlobalConfiguration (Lorg/dexpace/sdk/core/config/Configuration;)V
 }
 
 public final class org/dexpace/sdk/core/config/Configuration$Companion {
+	public final fun builder ()Lorg/dexpace/sdk/core/config/ConfigurationBuilder;
 	public final fun getGlobalConfiguration ()Lorg/dexpace/sdk/core/config/Configuration;
 	public final fun setGlobalConfiguration (Lorg/dexpace/sdk/core/config/Configuration;)V
 }
 
-public final class org/dexpace/sdk/core/config/ConfigurationBuilder {
+public final class org/dexpace/sdk/core/config/ConfigurationBuilder : org/dexpace/sdk/core/generics/Builder {
 	public fun <init> ()V
-	public final fun build ()Lorg/dexpace/sdk/core/config/Configuration;
+	public fun <init> (Lorg/dexpace/sdk/core/config/Configuration;)V
+	public synthetic fun build ()Ljava/lang/Object;
+	public fun build ()Lorg/dexpace/sdk/core/config/Configuration;
 	public final fun envSource (Ljava/util/function/Function;)Lorg/dexpace/sdk/core/config/ConfigurationBuilder;
 	public final fun propsSource (Ljava/util/function/Function;)Lorg/dexpace/sdk/core/config/ConfigurationBuilder;
 	public final fun put (Ljava/lang/String;Ljava/lang/String;)Lorg/dexpace/sdk/core/config/ConfigurationBuilder;
+	public final fun remove (Ljava/lang/String;)Lorg/dexpace/sdk/core/config/ConfigurationBuilder;
 }
 
 public abstract interface class org/dexpace/sdk/core/generics/Builder {
@@ -2418,3 +2425,9 @@ public final class org/dexpace/sdk/core/util/SdkInfo {
 	public final fun getSdkVersion ()Ljava/lang/String;
 }
 
+public final class org/dexpace/sdk/core/util/ValueEquality {
+	public static final field INSTANCE Lorg/dexpace/sdk/core/util/ValueEquality;
+	public static final fun contentEquals (Ljava/lang/Object;Ljava/lang/Object;)Z
+	public static final fun contentHashCode (Ljava/lang/Object;)I
+}
+

sdk-core/src/main/kotlin/org/dexpace/sdk/core/config/Configuration.kt

@@ -9,6 +9,7 @@ package org.dexpace.sdk.core.config
 
 import java.time.Duration
 import java.util.Locale
+import java.util.function.Consumer
 import java.util.function.Function
 
 /**
@@ -21,18 +22,64 @@ import java.util.function.Function
  * Typed accessors (`getInt`, `getBoolean`, `getDuration`) return the provided default on parse failures —
  * configuration issues never throw at the lookup site.
  *
- * Constructed via [ConfigurationBuilder].
+ * Constructed via [ConfigurationBuilder]; derive a reconfigured copy of an existing instance with
+ * [derive] or [newBuilder].
+ *
+ * ## Deriving a reconfigured copy (copy-on-write)
+ * [derive] returns a **new** immutable [Configuration] with a mutator applied on top of this
+ * one, leaving the receiver untouched:
+ *
+ * ```java
+ * Configuration base = Configuration.builder().put("MAX_RETRY_ATTEMPTS", "3").build();
+ * Configuration derived = base.derive(b -> b.put("LOG_LEVEL", "DEBUG"));
+ * // base is unchanged; derived carries both overrides.
+ * ```
+ *
+ * The derivation is copy-on-write in the value sense: the override map is copied so the original and
+ * the derived instance never alias the same mutable state, while the [envSource]/[propsSource]
+ * lookup functions are shared by reference (they are pure read seams and are never mutated). A
+ * mutator that touches no override and replaces no source produces an independent instance equal in
+ * behaviour to the original. [newBuilder] exposes the same prefilled builder for callers that prefer
+ * to thread it through other builder-folding code before [ConfigurationBuilder.build].
  *
  * ## Thread-safety
  * Instances are immutable once built (the override map is copied) and safe to share across threads.
  * The process-wide global slot is published via `@Volatile`; readers observe the most-recently-set
  * configuration under last-write-wins semantics.
  */
 public class Configuration internal constructor(
-    private val overrides: Map<String, String>,
-    private val envSource: Function<String, String?> = Function { name -> System.getenv(name) },
-    private val propsSource: Function<String, String?> = Function { name -> System.getProperty(name) },
+    @get:JvmSynthetic
+    internal val overrides: Map<String, String>,
+    @get:JvmSynthetic
+    internal val envSource: Function<String, String?> = Function { name -> System.getenv(name) },
+    @get:JvmSynthetic
+    internal val propsSource: Function<String, String?> = Function { name -> System.getProperty(name) },
 ) {
+    /**
+     * Returns a fresh [ConfigurationBuilder] preloaded with this instance's overrides and lookup
+     * sources. Mutating the returned builder never affects this [Configuration]; the override map is
+     * copied up front. Use this when you want to thread the builder through other configuration code
+     * before calling [ConfigurationBuilder.build]; prefer [derive] for the common
+     * derive-in-one-call case.
+     */
+    public fun newBuilder(): ConfigurationBuilder = ConfigurationBuilder(this)
+
+    /**
+     * Derive a new immutable [Configuration] by applying [mutator] to a builder prefilled from this
+     * instance, then building it. This [Configuration] is left unchanged (copy-on-write): the
+     * override map is copied before [mutator] runs, so overrides added, replaced, or removed inside
+     * [mutator] never leak back into the receiver. The env/property lookup seams are inherited by
+     * reference.
+     *
+     * Kotlin's compiler-generated non-null parameter check raises `NullPointerException` when a Java
+     * caller passes `null` for [mutator], so no explicit guard is needed here.
+     */
+    public fun derive(mutator: Consumer<ConfigurationBuilder>): Configuration {
+        val builder = newBuilder()
+        mutator.accept(builder)
+        return builder.build()
+    }
+
     /**
      * Look up a configuration value by [name].
      *
@@ -95,6 +142,14 @@ public class Configuration internal constructor(
     ): Duration = get(name)?.let { parseDuration(it) } ?: default
 
     public companion object {
+        /**
+         * Returns a fresh empty [ConfigurationBuilder]. Java-friendly entry point matching the
+         * `builder()` idiom every other SDK model exposes; build from scratch with this, or derive a
+         * reconfigured copy of an existing instance with [newBuilder] / [derive].
+         */
+        @JvmStatic
+        public fun builder(): ConfigurationBuilder = ConfigurationBuilder()
+
         // Well-known keys. `const val` so callers reference them as `Configuration.MAX_RETRY_ATTEMPTS`
         // from both Kotlin and Java without going through `Companion`.
 
@@ -147,7 +202,7 @@ public class Configuration internal constructor(
             // ISO-8601 path: `PT5S`, `P1D`, etc. Reject negative durations (e.g. `PT-5S`) for the
             // same reason the shorthand path does below — downstream consumers (Clock.sleep,
             // Futures.delay) assume a non-negative duration and throw on a negative one.
-            if (Character.toUpperCase(raw[0]) == 'P') {
+            if (raw[0].uppercaseChar() == 'P') {
                 return try {
                     val d = Duration.parse(raw)
                     if (d.isNegative) null else d

sdk-core/src/main/kotlin/org/dexpace/sdk/core/config/ConfigurationBuilder.kt

@@ -7,22 +7,41 @@
 
 package org.dexpace.sdk.core.config
 
+import org.dexpace.sdk.core.generics.Builder
 import java.util.function.Function
 
 /**
  * Builder for [Configuration]. Use [put] to add explicit overrides (which win over env vars and
  * system properties), and [envSource] / [propsSource] as test seams to substitute the env / property
  * lookups with hermetic functions.
  *
+ * Implements the generic [Builder] contract so it can be folded by builder-style configuration code.
+ * Construct empty for a configuration built from scratch, or via [Configuration.newBuilder] /
+ * [Configuration.derive] to derive a reconfigured copy of an existing [Configuration].
+ *
  * ## Thread-safety
  * Builders are *not* thread-safe — construct, configure, and [build] from a single thread. The
  * resulting [Configuration] is immutable and safe to share.
  */
-public class ConfigurationBuilder {
+public class ConfigurationBuilder : Builder<Configuration> {
     private val overrides = mutableMapOf<String, String>()
     private var envSource: Function<String, String?> = Function { name -> System.getenv(name) }
     private var propsSource: Function<String, String?> = Function { name -> System.getProperty(name) }
 
+    /** Creates an empty builder with the default env / system-property lookup sources. */
+    public constructor()
+
+    /**
+     * Creates a builder preloaded with [source]'s overrides and lookup sources. The override map is
+     * copied, so mutating this builder never affects [source]. Used by [Configuration.newBuilder] and
+     * [Configuration.derive].
+     */
+    public constructor(source: Configuration) {
+        overrides.putAll(source.overrides)
+        envSource = source.envSource
+        propsSource = source.propsSource
+    }
+
     /**
      * Register an explicit override. Overrides win over every other layer. Kotlin's
      * compiler-generated non-null parameter check raises `NullPointerException` when a Java
@@ -36,6 +55,22 @@ public class ConfigurationBuilder {
             overrides[name] = value
         }
 
+    /**
+     * Remove the explicit override for [name], if one is set. This drops only the override layer:
+     * a later [Configuration.get] for [name] falls through to the environment-variable and
+     * system-property seams (and finally the caller's default) exactly as if the override had never
+     * been registered — it does **not** force the key to resolve to `null`. Removing a key that
+     * carries no override is a no-op. As the inverse of [put], this is what lets
+     * [Configuration.derive] un-pin an override inherited from the source instance.
+     *
+     * Kotlin's compiler-generated non-null parameter check raises `NullPointerException` when a
+     * Java caller passes `null` for [name], so no explicit guard is needed here.
+     */
+    public fun remove(name: String): ConfigurationBuilder =
+        apply {
+            overrides.remove(name)
+        }
+
     /** Test seam: override the environment-variable source. */
     public fun envSource(source: Function<String, String?>): ConfigurationBuilder = apply { envSource = source }
 
@@ -46,5 +81,5 @@ public class ConfigurationBuilder {
      * Materialize the immutable [Configuration]. The current override map is defensively copied so
      * subsequent [put] calls on this builder do not mutate the returned configuration.
      */
-    public fun build(): Configuration = Configuration(overrides.toMap(), envSource, propsSource)
+    override fun build(): Configuration = Configuration(overrides.toMap(), envSource, propsSource)
 }