Merge pull request #1032 from ably/ECO-4208/proxy-support

refactor: decouple HTTP and WebSocket engines

.gitignore

@@ -8,3 +8,5 @@ bin/
 .project
 
 local.properties
+
+lombok.config

CONTRIBUTING.md

@@ -35,6 +35,34 @@ The Android-specific library AAR is built with:
 
 (The `ANDROID_HOME` environment variable must be set appropriately.)
 
+## Adding a New Network Engine Implementation
+
+Currently, `ably-java` supports two different engines for network operations (HTTP calls and WebSocket connections):
+
+- **Default Engine**: Utilizes the built-in `HttpUrlConnection` for HTTP calls and the TooTallNate/Java-WebSocket library for WebSocket connections.
+- **OkHttp Engine**: Utilizes the OkHttp library for both HTTP and WebSocket connections.
+
+These engines are designed to be swappable. By default, the library comes with the default engine, but you can easily replace it with the OkHttp engine:
+
+```kotlin
+implementation("io.ably:ably-java:$ABLY_VERSION") {
+    exclude(group = "io.ably", module = "network-client-default")
+}
+runtimeOnly("io.ably:network-client-okhttp:$ABLY_VERSION")
+```
+
+### How to Add a New Network Engine
+
+To add a new network engine, follow these steps:
+
+1. **Implement the interfaces**:
+  - Implement the `HttpEngineFactory` and `WebSocketEngineFactory` interfaces for your custom engine.
+
+2. **Register the engine**:
+  - Modify the `getFirstAvailable()` methods in these interfaces to include your new implementation.
+
+Once done, your custom network engine will be available for use within `ably-java`.
+
 ### Code Standard
 
 #### Checkstyle

android/build.gradle.kts

@@ -52,6 +52,8 @@ dependencies {
     api(libs.gson)
     implementation(libs.bundles.common)
     testImplementation(libs.bundles.tests)
+    implementation(project(":network-client-core"))
+    runtimeOnly(project(":network-client-default"))
     implementation(libs.firebase.messaging)
     androidTestImplementation(libs.bundles.instrumental.android)
 }

build.gradle.kts

@@ -6,6 +6,7 @@ import com.vanniktech.maven.publish.SonatypeHost
 plugins {
     alias(libs.plugins.android.library) apply false
     alias(libs.plugins.maven.publish) apply false
+    alias(libs.plugins.lombok) apply false
 }
 
 subprojects {

gradle/libs.versions.toml

@@ -16,6 +16,7 @@ android-test = "0.5"
 dexmaker = "1.4"
 android-retrostreams = "1.7.4"
 maven-publish = "0.29.0"
+lombok = "8.10"
 
 [libraries]
 gson = { group = "com.google.code.gson", name = "gson", version.ref = "gson" }
@@ -39,11 +40,12 @@ dexmaker-mockito = { group = "com.crittercism.dexmaker", name = "dexmaker-mockit
 android-retrostreams = { group = "net.sourceforge.streamsupport", name = "android-retrostreams", version.ref = "android-retrostreams" }
 
 [bundles]
-common = ["msgpack", "java-websocket", "vcdiff-core"]
+common = ["msgpack", "vcdiff-core"]
 tests = ["junit","hamcrest-all", "nanohttpd", "nanohttpd-nanolets", "nanohttpd-websocket", "mockito-core", "concurrentunit", "slf4j-simple"]
 instrumental-android = ["android-test-runner", "android-test-rules", "dexmaker", "dexmaker-dx", "dexmaker-mockito", "android-retrostreams"]
 
 [plugins]
 android-library = { id = "com.android.library", version.ref = "agp" }
 build-config = { id = "com.github.gmazzo.buildconfig", version.ref = "build-config" }
 maven-publish = { id = "com.vanniktech.maven.publish", version.ref = "maven-publish" }
+lombok = { id = "io.freefair.lombok", version.ref = "lombok" }

java/build.gradle.kts

@@ -19,6 +19,8 @@ tasks.withType<Jar> {
 dependencies {
     api(libs.gson)
     implementation(libs.bundles.common)
+    implementation(project(":network-client-core"))
+    runtimeOnly(project(":network-client-default"))
     testImplementation(libs.bundles.tests)
 }
 

lib/src/main/java/io/ably/lib/debug/DebugOptions.java

@@ -1,10 +1,10 @@
 package io.ably.lib.debug;
 
-import java.net.HttpURLConnection;
 import java.util.List;
 import java.util.Map;
 
 import io.ably.lib.http.HttpCore;
+import io.ably.lib.network.HttpRequest;
 import io.ably.lib.transport.ITransport;
 import io.ably.lib.types.AblyException;
 import io.ably.lib.types.ClientOptions;
@@ -19,7 +19,7 @@ public interface RawProtocolListener {
     }
 
     public interface RawHttpListener {
-        HttpCore.Response onRawHttpRequest(String id, HttpURLConnection conn, String method, String authHeader, Map<String, List<String>> requestHeaders, HttpCore.RequestBody requestBody);
+        HttpCore.Response onRawHttpRequest(String id, HttpRequest request, String authHeader, Map<String, List<String>> requestHeaders, HttpCore.RequestBody requestBody);
         void onRawHttpResponse(String id, String method, HttpCore.Response response);
         void onRawHttpException(String id, String method, Throwable t);
     }