refactor: let RequestBuilder.body(null) clear a body and document CONNECT

RequestBuilder.body now accepts null, so a body-carrying request can be
downgraded to a body-forbidden method (GET/HEAD/TRACE/CONNECT) via newBuilder
by clearing the body first — previously there was no way to drop it. build()
also runs the required-field checks before the body/method compatibility check,
so a missing method or url is reported before a body conflict.

Document that CONNECT, like GET/HEAD/TRACE, is rejected a request body at build
time — across Method, Request, and both transport adapters — and correct the
RFC 9110 wording: only TRACE carries a hard "MUST NOT send content" (§9.3.8),
while GET/HEAD/CONNECT payloads merely have no generally defined semantics.
Adds tests for the body(null) clear, the newBuilder downgrade recovery path,
and CONNECT coverage in the core and transport suites.

Author: OmarAlJarrah

sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/request/Method.kt

@@ -15,12 +15,15 @@ package org.dexpace.sdk.core.http.request
  * request line without translation.
  *
  * @property method Canonical uppercase method token sent in the request line.
- * @property permitsRequestBody Whether HTTP allows this method to carry a request body. `false`
- *   for `GET`, `HEAD`, and `TRACE`: GET/HEAD have no defined payload semantics (RFC 9110
- *   §9.3.1/§9.3.2) and a TRACE request "MUST NOT send content" (§9.3.8). Transports disagree on
- *   how to handle a body on these methods — OkHttp throws `IllegalArgumentException`, the JDK
- *   builder silently ignores it — so a body on a body-forbidden method is rejected at request
- *   construction (see `Request.RequestBuilder.build`) rather than left to diverge per transport.
+ * @property permitsRequestBody Whether this SDK permits the method to carry a request body.
+ *   `false` for `GET`, `HEAD`, `TRACE`, and `CONNECT`. Of these only `TRACE` is forbidden a body
+ *   outright by HTTP — a TRACE request "MUST NOT send content" (RFC 9110 §9.3.8); for `GET`/`HEAD`
+ *   (§9.3.1/§9.3.2) and `CONNECT` (§9.3.6) a request payload has no generally defined semantics
+ *   and is discouraged rather than illegal. The SDK rejects a body on all four as one consistent
+ *   policy, because the reference transports otherwise diverge on the case — OkHttp throws
+ *   `IllegalArgumentException`, the JDK builder silently ignores the body — so it is rejected once
+ *   at request construction (see `Request.RequestBuilder.build`) rather than left to behave
+ *   differently per transport.
  */
 @Suppress("unused")
 public enum class Method(

sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/request/Request.kt

@@ -39,7 +39,7 @@ import java.net.URL
  * @property headers Request headers; may be empty but never `null`.
  * @property body Request body, or `null` for methods without a payload. A non-`null` body is
  *   only valid on a method that permits one ([Method.permitsRequestBody]); building a `GET`,
- *   `HEAD`, or `TRACE` request with a body throws `IllegalArgumentException`.
+ *   `HEAD`, `TRACE`, or `CONNECT` request with a body throws `IllegalArgumentException`.
  */
 @ConsistentCopyVisibility
 public data class Request private constructor(
@@ -119,12 +119,16 @@ public data class Request private constructor(
             }
 
         /**
-         * Sets the request body.
+         * Sets the request body, or clears it when [body] is `null`.
          *
-         * @param body The request body.
+         * Passing `null` is the way to drop a body carried over by [newBuilder] — for example
+         * when downgrading a body-carrying request to `GET`, `HEAD`, `TRACE`, or `CONNECT`, whose
+         * [build] rejects a non-`null` body ([Method.permitsRequestBody] is `false` for them).
+         *
+         * @param body The request body, or `null` to clear any previously-set body.
          * @return This builder.
          */
-        public fun body(body: RequestBody): RequestBuilder =
+        public fun body(body: RequestBody?): RequestBuilder =
             apply {
                 this.body = body
             }
@@ -250,25 +254,27 @@ public data class Request private constructor(
          * Builds the [Request].
          *
          * A body set on a method that forbids one ([Method.permitsRequestBody] is `false` —
-         * `GET`, `HEAD`, `TRACE`) is rejected here rather than passed to a transport: the two
-         * reference transports disagree on the case (OkHttp throws, the JDK builder drops the
-         * body and may consume a single-use stream for nothing), so the SDK fails fast at
-         * construction with one consistent error instead.
+         * `GET`, `HEAD`, `TRACE`, `CONNECT`) is rejected here rather than passed to a transport:
+         * the two reference transports disagree on the case (OkHttp throws, the JDK builder drops
+         * the body and may consume a single-use stream for nothing), so the SDK fails fast at
+         * construction with one consistent error instead. To downgrade a body-carrying request to
+         * one of these methods, clear the body first with `body(null)`.
          *
          * @return The built request.
          * @throws IllegalStateException If a required field is missing.
          * @throws IllegalArgumentException If a body is set on a method that forbids one
-         *         ([Method.GET], [Method.HEAD], or [Method.TRACE]).
+         *         ([Method.GET], [Method.HEAD], [Method.TRACE], or [Method.CONNECT]).
          */
         override fun build(): Request {
             val resolvedMethod = checkRequired("method", method)
+            val resolvedUrl = checkRequired("url", url)
             require(body == null || resolvedMethod.permitsRequestBody) {
                 "$resolvedMethod must not carry a request body; remove the body or use a " +
                     "method that permits one (e.g. POST/PUT/PATCH)."
             }
             return Request(
                 method = resolvedMethod,
-                url = checkRequired("url", url),
+                url = resolvedUrl,
                 headers = headersBuilder.build(),
                 body = body,
             )

sdk-core/src/test/kotlin/org/dexpace/sdk/core/http/request/RequestTest.kt

@@ -226,7 +226,7 @@ class RequestTest {
 
     @Test
     fun `build rejects a body on a body-forbidden method`() {
-        for (method in listOf(Method.GET, Method.HEAD, Method.TRACE)) {
+        for (method in listOf(Method.GET, Method.HEAD, Method.TRACE, Method.CONNECT)) {
             val ex =
                 assertFailsWith<IllegalArgumentException>("expected rejection for $method") {
                     Request.builder()
@@ -258,7 +258,7 @@ class RequestTest {
 
     @Test
     fun `build allows a body-less body-forbidden method`() {
-        for (method in listOf(Method.GET, Method.HEAD, Method.TRACE)) {
+        for (method in listOf(Method.GET, Method.HEAD, Method.TRACE, Method.CONNECT)) {
             val req =
                 Request.builder()
                     .url("https://example.test")
@@ -282,6 +282,39 @@ class RequestTest {
         }
     }
 
+    @Test
+    fun `body null clears a previously-set body`() {
+        val req =
+            Request.builder()
+                .url("https://example.test")
+                .method(Method.POST)
+                .body(RequestBody.create("x", null))
+                .body(null)
+                .build()
+        assertNull(req.body, "body(null) should clear the previously-set body")
+    }
+
+    @Test
+    fun `newBuilder downgrade to a body-forbidden method succeeds after clearing the body`() {
+        val post =
+            Request.builder()
+                .url("https://example.test")
+                .method(Method.POST)
+                .body(RequestBody.create("x", null))
+                .build()
+
+        // Clearing the body with body(null) is the supported way to downgrade a body-carrying
+        // request to a method that forbids one.
+        val get =
+            post.newBuilder()
+                .method(Method.GET)
+                .body(null)
+                .build()
+
+        assertEquals(Method.GET, get.method)
+        assertNull(get.body, "downgraded GET must not retain the original body")
+    }
+
     // ---------------------------------------------------------------------
     // Equality — compares url by external form, never resolving DNS.
     // ---------------------------------------------------------------------

sdk-transport-jdkhttp/src/main/kotlin/org/dexpace/sdk/transport/jdkhttp/internal/RequestAdapter.kt

@@ -61,7 +61,8 @@ internal class RequestAdapter(
      * that take a [HttpRequest.BodyPublisher] and those that force [HttpRequest.BodyPublishers.noBody]
      * reflects the HTTP semantics enforced by the JDK builder:
      *
-     *  - `GET` / `HEAD` / `TRACE` — no body. [Method.permitsRequestBody] is `false` for these, so
+     *  - `GET` / `HEAD` / `TRACE` — no body. [Method.permitsRequestBody] is `false` for these (and
+     *    for `CONNECT`, which is rejected outright in its own branch below), so
      *    `Request.RequestBuilder.build` rejects a body on them at construction; an SDK request can
      *    never carry one here. The adapter sends `noBody()` unconditionally rather than adapting
      *    `request.body` — there is nothing to adapt, and `noBody()` consumes nothing (the previous

sdk-transport-jdkhttp/src/test/kotlin/org/dexpace/sdk/transport/jdkhttp/JdkHttpTransportTest.kt

@@ -114,7 +114,7 @@ class JdkHttpTransportTest {
         assertEquals("/echo", recorded.url.encodedPath)
     }
 
-    // -------- body on a body-forbidden method (GET/HEAD/TRACE) --------
+    // -------- body on a body-forbidden method (GET/HEAD/TRACE/CONNECT) --------
 
     @Test
     fun `bodyOnForbiddenMethodIsRejectedBeforeDispatch`() {
@@ -123,7 +123,7 @@ class JdkHttpTransportTest {
         // array that is then discarded. The SDK rejects the body at request construction
         // (Request.RequestBuilder.build), so such a request is never built and never reaches the
         // transport, and no body is consumed for nothing.
-        for (method in listOf(Method.GET, Method.HEAD, Method.TRACE)) {
+        for (method in listOf(Method.GET, Method.HEAD, Method.TRACE, Method.CONNECT)) {
             assertFailsWith<IllegalArgumentException>("expected rejection for $method") {
                 Request.builder()
                     .method(method)

sdk-transport-okhttp/src/main/kotlin/org/dexpace/sdk/transport/okhttp/internal/RequestAdapter.kt

@@ -31,11 +31,11 @@ import org.dexpace.sdk.core.http.request.RequestBody as SdkRequestBody
  *     body for POST/PUT/PATCH (the methods OkHttp treats as requiring one). The SDK model
  *     makes a body optional for every method, so a body-less POST is a valid request; to keep
  *     it from crashing with `IllegalArgumentException`, the adapter substitutes a zero-length
- *     body for those methods (see [requiresRequestBody]). GET/HEAD/OPTIONS/TRACE/DELETE keep
- *     their `null` body. The inverse case — a body on a body-forbidden method, which OkHttp's
+ *     body for those methods (see [requiresRequestBody]). GET/HEAD/OPTIONS/TRACE/DELETE/CONNECT
+ *     keep their `null` body. The inverse case — a body on a body-forbidden method, which OkHttp's
  *     `Request.Builder.method` rejects with `IllegalArgumentException("method GET must not have a
  *     request body.")` — cannot reach here: `Request.RequestBuilder.build` rejects a body on
- *     GET/HEAD/TRACE at construction, so `request.body` is always `null` for those methods.
+ *     GET/HEAD/TRACE/CONNECT at construction, so `request.body` is always `null` for those methods.
  *
  * The adapter is stateless — the [logger] is the only field it carries so the DEBUG log
  * naming dropped headers attributes to the transport.

sdk-transport-okhttp/src/test/kotlin/org/dexpace/sdk/transport/okhttp/OkHttpTransportTest.kt

@@ -159,7 +159,7 @@ class OkHttpTransportTest {
         assertEquals("0", recorded.headers["Content-Length"], "empty body must report zero length")
     }
 
-    // -------- body on a body-forbidden method (GET/HEAD/TRACE) --------
+    // -------- body on a body-forbidden method (GET/HEAD/TRACE/CONNECT) --------
 
     @Test
     fun bodyOnForbiddenMethodIsRejectedBeforeDispatch() {
@@ -168,7 +168,7 @@ class OkHttpTransportTest {
         // execute's @Throws(IOException) contract. The SDK rejects the body at request
         // construction (Request.RequestBuilder.build), so such a request is never built and never
         // reaches the transport.
-        for (method in listOf(Method.GET, Method.HEAD, Method.TRACE)) {
+        for (method in listOf(Method.GET, Method.HEAD, Method.TRACE, Method.CONNECT)) {
             assertFailsWith<IllegalArgumentException>("expected rejection for $method") {
                 Request.builder()
                     .method(method)