build: guard jdkhttp keep-rules and harden the shrink-survival harness

OmarAlJarrah · OmarAlJarrah · commit 8fa5a27fcb49 · 2026-06-17T00:43:33.000+03:00
Ship consumer keep-rules for sdk-transport-jdkhttp so both reference
transports protect their construction surface symmetrically, and guard
the new rules for real: the harness now bundles the jdkhttp transport
and drives an R8-shrunk round-trip through both transports via a shared
helper, rather than only okhttp.

Depending on the Java-11 jdkhttp module means sdk-shrink-test now targets
JDK 11 — the honest model, since the pipeline already runs on a JDK 11
(R8 is Java-11 bytecode and the shrunk program runs on the same launcher).
Detekt is skipped here for the same JDK-25-toolchain reason as the other
non-8 modules; ktlint and explicit-API strict mode stay on.

Also:
- Clarify that the harness is shrink-only (obfuscation disabled): correct
  the app KDoc and expand app-rules.pro on why renaming is out of scope.
- r8Run now ignores the exit value and asserts exit code + sentinel in
  doLast, so a failing shrunk run surfaces its captured output instead of
  an empty JavaExec abort.
- Document in CLAUDE.md that check now needs a JDK 11 toolchain and the
  Google Maven repo for the shrink-survival step.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -21,10 +21,17 @@ root `check` task — see `build.gradle.kts`). Detekt is skipped on the two non-
 system toolchain when a module targets a non-8 toolchain; see those build scripts for the upstream issue and
 re-enable conditions. It runs everywhere else, including `sdk-transport-okhttp`.
 
+`check` (so a plain `./gradlew build`) also runs the R8 shrink-survival guard in the test-only
+`sdk-shrink-test` module. That step **requires a JDK 11 toolchain** (Gradle auto-provisions one if absent)
+and network access to **Google's Maven repo** to fetch `com.android.tools:r8`. An offline build, or one
+that cannot provision JDK 11, will fail on `:sdk-shrink-test:r8Run`; scope the build (e.g. build specific
+modules) to skip it. See that module's `build.gradle.kts` for the pipeline.
+
 ## Repository Layout
 
-Nine Gradle modules (see `settings.gradle.kts`). `gradle/libs.versions.toml` is the single source of truth
-for dependency and plugin versions. Group `org.dexpace`, version `0.0.1-alpha.1`.
+Ten Gradle modules (see `settings.gradle.kts`). `gradle/libs.versions.toml` is the single source of truth
+for dependency and plugin versions. Group `org.dexpace`, version `0.0.1-alpha.1`. (The tenth,
+`sdk-shrink-test`, is a test-only, unpublished R8 shrink-survival guard — not listed below.)
 
 | Module | Purpose | JVM target |
 |---|---|---|
diff --git a/sdk-shrink-test/build.gradle.kts b/sdk-shrink-test/build.gradle.kts
@@ -5,6 +5,8 @@
  * SPDX-License-Identifier: MIT
  */
 
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 import java.io.ByteArrayOutputStream
 import java.io.File
 import java.util.zip.ZipFile
@@ -13,24 +15,61 @@ plugins {
     // Kotlin only — no kover, no maven-publish, no signing. This module produces no published
     // artifact and contributes no coverage; it is a build-time regression guard. The root build
     // therefore does NOT add it to the kover aggregate, and `apiValidation.ignoredProjects`
-    // (root build.gradle.kts) keeps it out of the binary-compatibility snapshot. Java-8 bytecode,
-    // explicit-API strict mode, ktlint, and detekt are all inherited from the root build and left
-    // ON — the shrink harness honours the same conventions as the published modules.
+    // (root build.gradle.kts) keeps it out of the binary-compatibility snapshot. Explicit-API
+    // strict mode and ktlint are inherited from the root build and left ON; detekt is disabled
+    // below for the same JDK-25-toolchain reason as the other non-Java-8 modules.
     kotlin("jvm")
 }
 
 group = "org.dexpace"
 version = "0.0.1-alpha.1"
 
+// This module targets JDK 11, not the root's Java-8 default. It depends on sdk-transport-jdkhttp
+// (Java-11 bytecode) so it can exercise that transport through R8, and the whole shrink pipeline
+// already runs on a JDK 11 (R8 itself is Java-11 bytecode, and the shrunk program runs on the same
+// 11 launcher) — so a downstream consumer that uses the jdkhttp transport is, by construction, an
+// 11+ consumer. Override all three knobs the way sdk-transport-jdkhttp documents (S2.12 — Toolchain
+// discipline): the toolchain, the `java {}` source/target, and every Kotlin compile task's target.
+kotlin {
+    jvmToolchain(11)
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_11
+    targetCompatibility = JavaVersion.VERSION_11
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(11))
+    }
+}
+
+tasks.withType<KotlinCompile>().configureEach {
+    compilerOptions {
+        jvmTarget.set(JvmTarget.JVM_11)
+    }
+}
+
+// Detekt is disabled here for the same reason as sdk-transport-jdkhttp and sdk-async-virtualthreads:
+// detekt 1.23.x crashes parsing the JDK 25+ system toolchain version when a module targets a non-8
+// toolchain (detekt/detekt#8714). Re-enable when detekt 1.23.x embeds Kotlin >= 2.1.20 or the build
+// moves to detekt 2.x. ktlint and explicit-API strict mode stay on.
+tasks.matching { it.name == "detekt" }.configureEach {
+    enabled = false
+}
+
 // The shrink harness exercises the SDK exactly as a downstream consumer would: it depends on the
-// published modules (core, the Okio I/O adapter, the OkHttp transport, the Jackson serde) and
+// published modules (core, the Okio I/O adapter, both reference transports, the Jackson serde) and
 // their real transitive runtime dependencies, then bundles the lot into a single program for R8
-// to shrink. MockWebServer drives a genuine in-process HTTP round-trip so the shrunk program
-// proves the transport still works end-to-end, not merely that its classes survived.
+// to shrink. MockWebServer drives a genuine in-process HTTP round-trip through each transport so
+// the shrunk program proves they still work end-to-end, not merely that their classes survived.
+//
+// Both transports are included so the harness guards each one's shipped keep-rules symmetrically:
+// dropping a rule from either sdk-transport-okhttp or sdk-transport-jdkhttp would fail this module.
+// Depending on the Java-11 jdkhttp module is why this module itself targets JDK 11 (see above).
 dependencies {
     implementation(project(":sdk-core"))
     implementation(project(":sdk-io-okio3"))
     implementation(project(":sdk-transport-okhttp"))
+    implementation(project(":sdk-transport-jdkhttp"))
     implementation(project(":sdk-serde-jackson"))
     implementation(libs.okhttp.mockwebserver.junit5)
 
@@ -47,7 +86,7 @@ dependencies {
 // ---------------------------------------------------------------------------------------------
 // R8 shrink-survival pipeline
 //
-//   buildShrinkInputJar  -> fat jar: consumer program + SDK + okio + okhttp + jackson + stdlib
+//   buildShrinkInputJar  -> fat jar: consumer program + SDK + okio + transports + jackson + stdlib
 //   r8Shrink             -> runs R8 in full mode over that jar with the SHIPPED consumer rules
 //   r8Run                -> runs the shrunk program and asserts it prints the success sentinel
 //
@@ -83,6 +122,7 @@ val shippedConsumerRulePaths: List<String> =
         "META-INF/proguard/sdk-core.pro",
         "META-INF/proguard/sdk-io-okio3.pro",
         "META-INF/proguard/sdk-transport-okhttp.pro",
+        "META-INF/proguard/sdk-transport-jdkhttp.pro",
         "META-INF/proguard/sdk-serde-jackson.pro",
     )
 
@@ -201,13 +241,25 @@ val r8Run by tasks.registering(JavaExec::class) {
 
     val captured = ByteArrayOutputStream()
     standardOutput = captured
+    // Capture rather than inherit stderr too, so a stack trace from a failing shrunk run is folded
+    // into the diagnostic below instead of racing the captured stdout to the console.
+    errorOutput = captured
+    // Do not let a non-zero exit abort the task before doLast: if the shrunk program throws (the
+    // SDK did not survive shrinking), JavaExec's default behaviour would fail here and discard the
+    // captured output — exactly the diagnostic we need. We assert success ourselves in doLast.
+    isIgnoreExitValue = true
+    // `executionResult` is a member of JavaExec, but inside `doLast` the lambda receiver is the bare
+    // Task; capture the provider here so the exit code is reachable when the action runs.
+    val execResult = executionResult
 
     doLast {
         val output = captured.toString("UTF-8")
         logger.lifecycle(output.trim())
-        check(output.contains(successSentinel)) {
-            "The R8-shrunk consumer did not print the success sentinel. The SDK did not survive " +
-                "shrinking with its shipped keep-rules. Program output was:\n$output"
+        val exitValue = execResult.get().exitValue
+        check(exitValue == 0 && output.contains(successSentinel)) {
+            "The R8-shrunk consumer did not survive shrinking with its shipped keep-rules " +
+                "(exit code $exitValue). The SDK surface a downstream R8 build relies on was " +
+                "stripped or broken. Program output was:\n$output"
         }
         resultMarker.get().asFile.writeText("ok\n")
     }
diff --git a/sdk-shrink-test/src/main/kotlin/org/dexpace/sdk/shrinktest/ShrinkSurvivalApp.kt b/sdk-shrink-test/src/main/kotlin/org/dexpace/sdk/shrinktest/ShrinkSurvivalApp.kt
@@ -9,6 +9,7 @@ package org.dexpace.sdk.shrinktest
 
 import mockwebserver3.MockResponse
 import mockwebserver3.MockWebServer
+import org.dexpace.sdk.core.client.HttpClient
 import org.dexpace.sdk.core.http.common.CommonMediaTypes
 import org.dexpace.sdk.core.http.request.Method
 import org.dexpace.sdk.core.http.request.Request
@@ -18,6 +19,7 @@ import org.dexpace.sdk.core.io.Io
 import org.dexpace.sdk.core.serde.Tristate
 import org.dexpace.sdk.io.OkioIoProvider
 import org.dexpace.sdk.serde.jackson.JacksonSerde
+import org.dexpace.sdk.transport.jdkhttp.JdkHttpTransport
 import org.dexpace.sdk.transport.okhttp.OkHttpTransport
 
 /**
@@ -27,8 +29,12 @@ import org.dexpace.sdk.transport.okhttp.OkHttpTransport
  * [SUCCESS_SENTINEL] on a clean run.
  *
  * The harness runs this from the R8-shrunk jar. Because that run performs a real HTTP round-trip
- * and a real JSON round-trip, it proves not merely that the kept classes still exist but that their
- * members remain wired correctly after tree-shaking and (potential) renaming.
+ * and a real JSON round-trip, it proves not merely that the kept classes still exist after R8's
+ * tree-shaking but that their members remain wired correctly and functional. The harness runs R8
+ * in shrink-only mode (obfuscation is disabled in `src/r8/app-rules.pro`, see the rationale there),
+ * so it guards against dead-code elimination of the SDK's reflective and SPI surface — not against
+ * member renaming, which a downstream that also obfuscates would additionally need its own rules
+ * for the third-party libraries on its classpath.
  */
 public object ShrinkSurvivalApp {
     /** Printed verbatim to stdout once every exercise below has passed. */
@@ -39,7 +45,7 @@ public object ShrinkSurvivalApp {
         // 1. I/O provider seam — install the only adapter through the documented entry point.
         Io.installProvider(OkioIoProvider)
 
-        exerciseTransportRoundTrip()
+        exerciseTransportRoundTrips()
         exerciseSerdeRoundTrip()
 
         // Reaching here means every kept surface resolved and behaved. Emit the sentinel the
@@ -48,49 +54,64 @@ public object ShrinkSurvivalApp {
     }
 
     /**
-     * Drives a full request/response exchange through [OkHttpTransport] against an in-process
-     * [MockWebServer]. Exercises the request builder, [RequestBody], the transport's sync
-     * `execute` path, and reading the [org.dexpace.sdk.core.http.response.Response] body via the
-     * I/O seam.
+     * Drives a full request/response exchange through each reference transport — [OkHttpTransport]
+     * and [JdkHttpTransport] — against an in-process [MockWebServer]. Exercises the request builder,
+     * [RequestBody], the transport's sync `execute` path, and reading the
+     * [org.dexpace.sdk.core.http.response.Response] body via the I/O seam. Both transports are
+     * driven so the harness guards each module's shipped keep-rules; the construction path of either
+     * being stripped would surface here.
      */
-    private fun exerciseTransportRoundTrip() {
+    private fun exerciseTransportRoundTrips() {
         MockWebServer().use { server ->
-            server.enqueue(
-                MockResponse.Builder()
-                    .code(Status.OK.code)
-                    .addHeader("Content-Type", "application/json")
-                    .body("""{"echo":"pong"}""")
-                    .build(),
-            )
+            // One queued response per transport — they each issue a single request below.
+            repeat(2) {
+                server.enqueue(
+                    MockResponse.Builder()
+                        .code(Status.OK.code)
+                        .addHeader("Content-Type", "application/json")
+                        .body("""{"echo":"pong"}""")
+                        .build(),
+                )
+            }
             server.start()
 
             val baseUrl = server.url("/echo").toString()
 
-            OkHttpTransport.builder().build().use { transport ->
-                val request =
-                    Request.builder()
-                        .method(Method.POST)
-                        .url(baseUrl)
-                        .addHeader("Accept", "application/json")
-                        .body(
-                            RequestBody.create(
-                                """{"ping":"ping"}""",
-                                CommonMediaTypes.APPLICATION_JSON,
-                            ),
-                        )
-                        .build()
-
-                val response = transport.execute(request)
-                val status = response.status.code
-                val payload = response.body?.source()?.readUtf8().orEmpty()
-                response.close()
-
-                check(status == Status.OK.code) { "unexpected status from transport: $status" }
-                check(payload.contains("pong")) { "unexpected body from transport: $payload" }
-            }
+            OkHttpTransport.builder().build().use { roundTrip(it, baseUrl) }
+            JdkHttpTransport.builder().build().use { roundTrip(it, baseUrl) }
         }
     }
 
+    /**
+     * Issues one POST through [transport] (typed as the core [HttpClient] SPI, so the exercise stays
+     * transport-agnostic) and asserts the response came back intact through the I/O seam.
+     */
+    private fun roundTrip(
+        transport: HttpClient,
+        baseUrl: String,
+    ) {
+        val request =
+            Request.builder()
+                .method(Method.POST)
+                .url(baseUrl)
+                .addHeader("Accept", "application/json")
+                .body(
+                    RequestBody.create(
+                        """{"ping":"ping"}""",
+                        CommonMediaTypes.APPLICATION_JSON,
+                    ),
+                )
+                .build()
+
+        val response = transport.execute(request)
+        val status = response.status.code
+        val payload = response.body?.source()?.readUtf8().orEmpty()
+        response.close()
+
+        check(status == Status.OK.code) { "unexpected status from transport: $status" }
+        check(payload.contains("pong")) { "unexpected body from transport: $payload" }
+    }
+
     /**
      * Round-trips a model carrying a [Tristate] field through [JacksonSerde]. This is the most
      * shrink-fragile path: Jackson binds the model reflectively and the custom Tristate module
diff --git a/sdk-shrink-test/src/r8/app-rules.pro b/sdk-shrink-test/src/r8/app-rules.pro
@@ -13,6 +13,14 @@
 
 # Target a desktop/server JVM, not Android: emit classfiles, do not require a min API, and keep
 # enough debug info that a stack trace from the shrunk run is legible.
+#
+# Obfuscation (member/class renaming) is deliberately OFF. This harness guards SHRINK survival:
+# that R8's dead-code elimination does not strip the SDK's reflective and SPI surface. It does not
+# guard obfuscation survival, because renaming would also rename the third-party libraries bundled
+# here (OkHttp, Okio, Jackson), each of which ships its own consumer keep-rules that a real
+# obfuscating consumer applies — reproducing that whole closure is out of scope for this module.
+# The SDK's own shipped rules use `-keep ... { *; }`, which already pins names against renaming, so
+# enabling obfuscation here would mostly test the bundled libraries' rules, not the SDK's.
 -dontobfuscate
 -keepattributes SourceFile,LineNumberTable
 
diff --git a/sdk-transport-jdkhttp/src/main/resources/META-INF/proguard/sdk-transport-jdkhttp.pro b/sdk-transport-jdkhttp/src/main/resources/META-INF/proguard/sdk-transport-jdkhttp.pro
@@ -0,0 +1,14 @@
+# Copyright (c) 2026 dexpace and Omar Aljarrah
+#
+# Licensed under the MIT License. See LICENSE in the project root.
+# SPDX-License-Identifier: MIT
+
+# Consumer ProGuard/R8 keep rules for sdk-transport-jdkhttp.
+#
+# JdkHttpTransport is the public entry point; callers construct it through builder() / create()
+# and then use it only through the HttpClient / AsyncHttpClient interfaces. Keep the class, its
+# Builder, and the static factories so the construction path survives shrinking. This mirrors the
+# rules sdk-transport-okhttp ships for its own transport — every reference transport protects the
+# same construction surface.
+-keep class org.dexpace.sdk.transport.jdkhttp.JdkHttpTransport { *; }
+-keep class org.dexpace.sdk.transport.jdkhttp.JdkHttpTransport$Builder { *; }
