fix(response): drop unused import, tighten ParsedResponse contract and handler docs

Remove the unused reified `deserialize` import in JsonResponseHandler — the only
call site binds to the member `deserialize(stream, Class<T>)` overload, so the
extension was dead and ktlint's no-unused-imports broke the build.

Documentation and ergonomics follow-ups:
- ParsedResponse.value() now states that handler failures of any type (commonly
  unchecked, e.g. SerdeException from the Jackson handler) propagate and are
  memoized, so callers do not assume IOException is the only escape.
- Add a comment explaining the deliberate catch(Throwable) in the memoization
  path: the single-use body cannot be re-read, so even an Error is pinned rather
  than masked by a re-parse.
- Make ParsedResponse's primary constructor internal (factories `of` /
  `parsedWith` remain the entry points), matching the immutable-model convention;
  api snapshot regenerated.
- Warn on ResponseHandler.string() that it reads an unbounded body into memory,
  unsuitable for untrusted or large payloads.
- Soften the DRAIN_CHUNK_BYTES comment so it cannot drift from the I/O segment
  size, and include the target type name in the null-body SerdeException message.

Author: OmarAlJarrah

sdk-core/api/sdk-core.api

@@ -1125,7 +1125,6 @@ public final class org/dexpace/sdk/core/http/response/LoggableResponseBody : org
 
 public final class org/dexpace/sdk/core/http/response/ParsedResponse : java/io/Closeable {
 	public static final field Companion Lorg/dexpace/sdk/core/http/response/ParsedResponse$Companion;
-	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Lorg/dexpace/sdk/core/http/response/ResponseHandler;)V
 	public fun close ()V
 	public final fun getHeaders ()Lorg/dexpace/sdk/core/http/common/Headers;
 	public final fun getMessage ()Ljava/lang/String;

sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/response/ParsedResponse.kt

@@ -46,7 +46,7 @@ import kotlin.concurrent.withLock
  * @param raw The underlying raw response. Header / status / metadata access reads from here.
  * @param handler Strategy that maps [raw] to the typed value on first [value] access.
  */
-public class ParsedResponse<out T>(
+public class ParsedResponse<out T> internal constructor(
     public val raw: Response,
     private val handler: ResponseHandler<T>,
 ) : Closeable {
@@ -80,8 +80,12 @@ public class ParsedResponse<out T>(
      * typically consumes and closes the body); subsequent calls return the same value, or
      * re-throw the same failure, without re-running the handler.
      *
+     * Any failure the handler throws is memoized and re-thrown verbatim on every later call — not
+     * just [IOException]. Handlers commonly throw **unchecked** exceptions (the Jackson `jsonHandler`
+     * throws `SerdeException`), so callers should not assume the only escape is [IOException].
+     *
      * @return The parsed value (which may be `null` if the handler produces `null`).
-     * @throws IOException If the handler failed — the original failure is cached and re-thrown.
+     * @throws IOException If the handler failed with an [IOException] — cached and re-thrown.
      */
     @Throws(IOException::class)
     public fun value(): T {
@@ -94,6 +98,10 @@ public class ParsedResponse<out T>(
                 try {
                     Outcome.Success(handler.handle(raw))
                 } catch (t: Throwable) {
+                    // Catch Throwable, not Exception, on purpose: once the handler has touched the
+                    // single-use body, re-running it would read an already-consumed stream. Even an
+                    // Error (e.g. an OOM mid-parse) is memoized so a later call re-throws it rather
+                    // than re-reading the body and masking the original failure.
                     Outcome.Failure(t)
                 }
             outcome = resolved

sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/response/ResponseHandler.kt

@@ -57,6 +57,11 @@ public fun interface ResponseHandler<out T> {
          * A handler that reads the entire response body as a UTF-8 [String] and closes the
          * response. A bodyless response (e.g. `204 No Content`) yields an empty string.
          *
+         * **Unbounded.** This reads the whole body into a single in-memory [String] with no size
+         * cap, so it is an unbounded-allocation vector against a hostile or misbehaving server.
+         * Unlike the bounded body-logging path elsewhere in the SDK, it applies no limit — use it
+         * only for trusted endpoints with bounded payloads, not for untrusted or large bodies.
+         *
          * @return A stateless [String] handler.
          */
         @JvmStatic
@@ -90,7 +95,10 @@ public fun interface ResponseHandler<out T> {
                 }
             }
 
-        /** Per-read pump size for the discarding drain — matches the I/O segment size. */
+        /**
+         * Per-read pump size for the discarding drain — a reasonable chunk size. `read` treats it
+         * as an upper bound, so the exact value is not load-bearing for correctness.
+         */
         private const val DRAIN_CHUNK_BYTES: Long = 8 * 1024
     }
 }

sdk-serde-jackson/src/main/kotlin/org/dexpace/sdk/serde/jackson/JsonResponseHandler.kt

@@ -12,7 +12,6 @@ import org.dexpace.sdk.core.http.response.Response
 import org.dexpace.sdk.core.http.response.ResponseHandler
 import org.dexpace.sdk.core.serde.Serde
 import org.dexpace.sdk.core.serde.SerdeException
-import org.dexpace.sdk.core.serde.deserialize
 
 /**
  * A [ResponseHandler] that streams the response body through [serde]'s deserializer into a value
@@ -40,7 +39,7 @@ public fun <T> jsonHandler(
     type: Class<T>,
 ): ResponseHandler<T> =
     ResponseHandler { response ->
-        decode(response) { stream -> serde.deserializer.deserialize(stream, type) }
+        decode(response, type.typeName) { stream -> serde.deserializer.deserialize(stream, type) }
     }
 
 /**
@@ -60,7 +59,7 @@ public fun <T> jsonHandler(
     type: TypeReference<T>,
 ): ResponseHandler<T> =
     ResponseHandler { response ->
-        decode(response) { stream -> serde.deserializeAs(stream, type) }
+        decode(response, type.type.typeName) { stream -> serde.deserializeAs(stream, type) }
     }
 
 /**
@@ -70,13 +69,14 @@ public fun <T> jsonHandler(
  */
 private inline fun <T> decode(
     response: Response,
+    targetType: String,
     decoder: (java.io.InputStream) -> T,
 ): T =
     response.use { resp ->
         val body =
             resp.body
                 ?: throw SerdeException(
-                    "Cannot deserialize a ${resp.status.code} response that has no body.",
+                    "Cannot deserialize a ${resp.status.code} response with no body into $targetType.",
                 )
         try {
             decoder(body.source().inputStream())

sdk-serde-jackson/src/test/kotlin/org/dexpace/sdk/serde/jackson/JsonResponseHandlerTest.kt

@@ -103,7 +103,9 @@ class JsonResponseHandlerTest {
                 .protocol(Protocol.HTTP_1_1)
                 .status(Status.NO_CONTENT)
                 .build()
-        assertFailsWith<SerdeException> { jsonHandler(serde, Dto::class.java).handle(resp) }
+        val ex = assertFailsWith<SerdeException> { jsonHandler(serde, Dto::class.java).handle(resp) }
+        // The message names the target type so a failure log says what the decode was aiming for.
+        assertEquals(true, ex.message?.contains(Dto::class.java.typeName) == true)
     }
 
     @Test