fix: Switch DefaultHttpAdapter from OkHttp to HttpURLConnection

Replace OkHttp transport with java.net.HttpURLConnection; remove okhttp
and logging-interceptor compile dependencies. Preserve debug logging
behind RECURLY_INSECURE + RECURLY_DEBUG using System.out.println.

Fix 411 errors on POST/PUT with null body by sending Content-Length: 0,
matching OkHttp prior behavior. Add contract tests for this case.

Update the implementation guide to use OkHttp as the example adapter
instead of java.net.http.HttpClient.

Co-Authored-By: Claude <noreply@anthropic.com>

feat: Add gzip response decompression to DefaultHttpAdapter

DefaultHttpAdapter now sets Accept-Encoding: gzip on outgoing requests
(unless the caller already set one) and transparently decompresses
gzip-encoded response and error bodies via GZIPInputStream, matching
the behavior OkHttp provided automatically before the HttpURLConnection
migration. content-encoding and content-length are stripped from the
returned headers once decompressed since they no longer describe the
decompressed body.

Co-Authored-By: Claude <noreply@anthropic.com>

fix: Exclude WireMock-dependent tests from testCompile on JDK 8

WireMock 3.x ships Java 11 class files, which javac on a JDK 8
toolchain cannot read from the classpath regardless of source/target
level. @DisabledOnJre(JRE.JAVA_8) only skips execution, not
compilation, so the Java 8 CI job was failing to build.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

fix: Update RequestOptions header tests for HttpAdapter migration

Rebase onto v3-v2021-02-25 merged in idempotency-key/custom-header
tests written against the old OkHttp-based BaseClient. Rewrite them
against the HttpAdapter mock so they compile and assert against the
headers map passed to httpAdapter.execute.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: douglasmiller

docs/http-adapter-implementation-guide.md

@@ -11,8 +11,7 @@ middleware you prefer. Common reasons to do this:
 ## Registering your implementation
 
 ```java
-ClientOptions options = new ClientOptions();
-options.setHttpAdapter(new MyHttpAdapter());
+ClientOptions options = ClientOptions.builder().httpAdapter(new MyHttpAdapter()).build();
 Client client = new Client(apiKey, options);
 ```
 
@@ -47,16 +46,16 @@ All headers the client wants to send, including:
 | `Content-Type`  | `application/json`                                 |
 | `User-Agent`    | `Recurly/<version>; java <jvm-version>`            |
 
-**Forward every entry without modification.** Do not add, remove, or override headers in the
-adapter. The client owns header construction; the adapter owns transport.
+**Forward every client-supplied entry unmodified.** Do not remove or override a header the client
+set. The client owns header construction; the adapter owns transport. You may add your own
+transport-layer headers (e.g. `Accept-Encoding`) as long as they don't conflict with a header the
+client already set — `DefaultHttpAdapter` does this to negotiate gzip.
 
 ### Body
 
-- `POST` and `PUT` requests: a UTF-8-encoded JSON string.
-- `GET`, `HEAD`, `DELETE` requests: `null`.
-
-When `body` is `null` and the HTTP method requires a body (e.g. `DELETE` with some servers), send
-an empty body (`Content-Length: 0`).
+- `POST` and `PUT` requests: typically a UTF-8-encoded JSON string, but may be `null` (e.g. no
+  request object was passed) — send the request with `Content-Length: 0` in that case.
+- `GET`, `HEAD`, `DELETE` requests: always `null`.
 
 ---
 
@@ -77,6 +76,9 @@ status codes.
 Pass a `Map<String, String>` of all response headers. `HttpResponse` normalises keys to lower-case
 internally, so you do not need to do it yourself — but passing lower-case keys is fine too.
 
+Only one value per header name is supported. When a server sends multiple values for a single
+header name (e.g. `Set-Cookie`), pass just the first value.
+
 The client reads these specific headers:
 
 | Header                  | Purpose                                           |
@@ -159,55 +161,86 @@ public class MyHttpAdapter implements HttpAdapter {
 The Recurly client does not enforce timeouts. Set connect, read, and write timeouts inside your
 adapter and adjust to your SLA requirements.
 
+`DefaultHttpAdapter` sets its connect and read timeouts from its `timeoutMs` constructor argument
+(10 seconds by default). `java.net.HttpURLConnection` has no write-timeout API, so a stalled
+request-body upload is not bounded by `timeoutMs` and can block until the underlying OS-level TCP
+timeout is reached. If your SLA requires a bounded write phase, implement a custom `HttpAdapter`
+(e.g. using OkHttp, which supports `writeTimeout` directly) instead of relying on the default.
+
 ---
 
-## Minimal example
+## OkHttp example
+
+Add the OkHttp dependency to your project:
+
+```xml
+<dependency>
+    <groupId>com.squareup.okhttp3</groupId>
+    <artifactId>okhttp</artifactId>
+    <version>4.12.0</version>
+</dependency>
+```
 
 ```java
 import com.recurly.v3.http.HttpAdapter;
 import com.recurly.v3.http.HttpResponse;
 
 import java.io.IOException;
-import java.net.URI;
-import java.net.http.HttpClient;
-import java.net.http.HttpRequest;
-import java.net.http.HttpRequest.BodyPublishers;
-import java.time.Duration;
 import java.util.HashMap;
 import java.util.Map;
-
-public class JavaNetHttpAdapter implements HttpAdapter {
-
-    private final HttpClient client = HttpClient.newBuilder()
-            .connectTimeout(Duration.ofSeconds(30))
+import java.util.concurrent.TimeUnit;
+import okhttp3.Headers;
+import okhttp3.MediaType;
+import okhttp3.OkHttpClient;
+import okhttp3.Request;
+import okhttp3.RequestBody;
+import okhttp3.Response;
+import okhttp3.ResponseBody;
+
+public class OkHttpAdapter implements HttpAdapter {
+
+    private final OkHttpClient client = new OkHttpClient.Builder()
+            .connectTimeout(60, TimeUnit.SECONDS)
+            .readTimeout(60, TimeUnit.SECONDS)
+            .writeTimeout(60, TimeUnit.SECONDS)
             .build();
 
     @Override
     public HttpResponse execute(String method, String url,
                                 Map<String, String> headers, String body) throws IOException {
-        HttpRequest.Builder builder = HttpRequest.newBuilder()
-                .uri(URI.create(url))
-                .method(method, body != null
-                        ? BodyPublishers.ofString(body)
-                        : BodyPublishers.noBody());
+        Request.Builder builder = new Request.Builder().url(url);
 
-        headers.forEach(builder::header);
+        for (Map.Entry<String, String> header : headers.entrySet()) {
+            builder.header(header.getKey(), header.getValue());
+        }
+
+        RequestBody requestBody = body != null
+                ? RequestBody.create(body, MediaType.parse("application/json; charset=utf-8"))
+                : RequestBody.create(new byte[0], MediaType.parse("application/json; charset=utf-8"));
+
+        switch (method) {
+            case "HEAD":   builder.head();            break;
+            case "GET":    builder.get();             break;
+            case "POST":   builder.post(requestBody); break;
+            case "PUT":    builder.put(requestBody);  break;
+            case "DELETE": builder.delete();          break;
+            default:
+                throw new IllegalArgumentException(method + " is not a valid Recurly HTTP method");
+        }
 
-        try {
-            java.net.http.HttpResponse<byte[]> resp =
-                    client.send(builder.build(), java.net.http.HttpResponse.BodyHandlers.ofByteArray());
+        try (Response response = client.newCall(builder.build()).execute()) {
+            int statusCode = response.code();
 
             Map<String, String> responseHeaders = new HashMap<>();
-            resp.headers().map().forEach((k, vs) -> {
-                if (k != null && !vs.isEmpty()) responseHeaders.put(k, vs.get(0));
-            });
+            Headers okHeaders = response.headers();
+            for (int i = 0; i < okHeaders.size(); i++) {
+                responseHeaders.put(okHeaders.name(i).toLowerCase(), okHeaders.value(i));
+            }
 
-            return new HttpResponse(resp.statusCode(), responseHeaders,
-                    resp.body() != null ? resp.body() : new byte[0]);
+            ResponseBody responseBody = response.body();
+            byte[] responseBodyBytes = responseBody != null ? responseBody.bytes() : new byte[0];
 
-        } catch (InterruptedException e) {
-            Thread.currentThread().interrupt();
-            throw new IOException("HTTP request interrupted", e);
+            return new HttpResponse(statusCode, responseHeaders, responseBodyBytes);
         }
     }
 }
@@ -274,4 +307,4 @@ public class FakeHttpAdapter implements HttpAdapter {
 }
 ```
 
-See `DefaultHttpAdapter` for the complete production reference implementation.
+See `DefaultHttpAdapter` for the `HttpURLConnection`-based reference implementation.

pom.xml

@@ -58,10 +58,9 @@
     </distributionManagement>
 
     <properties>
-        <java.version>1.8</java.version>
+        <java.version>8</java.version>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
-        <okhttp3.version>4.12.0</okhttp3.version>
         <wiremock.version>3.13.2</wiremock.version>
         <surefire.version>3.5.5</surefire.version>
         <jacoco.version>0.8.13</jacoco.version>
@@ -87,8 +86,7 @@
                 <artifactId>maven-compiler-plugin</artifactId>
                 <version>3.15.0</version>
                 <configuration>
-                    <source>${java.version}</source>
-                    <target>${java.version}</target>
+                    <release>${java.version}</release>
                 </configuration>
             </plugin>
             <plugin>
@@ -156,6 +154,7 @@
             <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-jar-plugin</artifactId>
+              <version>3.5.0</version>
               <executions>
                 <execution>
                   <id>test-jar</id>
@@ -234,22 +233,45 @@
         </plugins>
     </build>
 
+    <profiles>
+      <profile>
+        <!--
+          WireMock 3.x ships class files compiled for Java 11 (class file version 55), which
+          javac running on a JDK 8 toolchain cannot read from the classpath at all, regardless of
+          <source>/<target>. HttpAdapterContract and DefaultHttpAdapterGzipTest are already
+          @DisabledOnJre(JRE.JAVA_8) at runtime, but that annotation only skips execution, not
+          compilation, so they must be excluded from testCompile on JDK 8 to keep the build green.
+        -->
+        <id>jdk8-exclude-wiremock-tests</id>
+        <activation>
+          <jdk>1.8</jdk>
+        </activation>
+        <build>
+          <plugins>
+            <plugin>
+              <groupId>org.apache.maven.plugins</groupId>
+              <artifactId>maven-compiler-plugin</artifactId>
+              <configuration>
+                <testExcludes>
+                  <exclude>**/http/HttpAdapterContract.java</exclude>
+                  <exclude>**/http/DefaultHttpAdapterContractTest.java</exclude>
+                  <exclude>**/http/DefaultHttpAdapterGzipTest.java</exclude>
+                  <exclude>**/http/DefaultHttpAdapterTimeoutTest.java</exclude>
+                  <exclude>**/http/WireMockTestSupport.java</exclude>
+                </testExcludes>
+              </configuration>
+            </plugin>
+          </plugins>
+        </build>
+      </profile>
+    </profiles>
+
     <dependencies>
         <dependency>
             <groupId>com.google.code.gson</groupId>
             <artifactId>gson</artifactId>
             <version>2.13.1</version>
         </dependency>
-        <dependency>
-            <groupId>com.squareup.okhttp3</groupId>
-            <artifactId>okhttp</artifactId>
-            <version>${okhttp3.version}</version>
-        </dependency>
-        <dependency>
-            <groupId>com.squareup.okhttp3</groupId>
-            <artifactId>logging-interceptor</artifactId>
-            <version>${okhttp3.version}</version>
-        </dependency>
         <dependency>
             <groupId>org.wiremock</groupId>
             <artifactId>wiremock</artifactId>