feat: OkHttp implementation for making HTTP calls and WebSocket connections

.github/workflows/integration-test.yml

@@ -49,3 +49,32 @@ jobs:
  with:
  name: java-build-reports-realtime
  path: java/build/reports/
+ check-rest-okhttp:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ with:
+ submodules: 'recursive'
+
+ - name: Set up the JDK
+ uses: actions/setup-java@v3
+ with:
+ java-version: '17'
+ distribution: 'temurin'
+
+ - run: ./gradlew :java:testRestSuite -Pokhttp
+
+ check-realtime-okhttp:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ with:
+ submodules: 'recursive'
+
+ - name: Set up the JDK
+ uses: actions/setup-java@v3
+ with:
+ java-version: '17'
+ distribution: 'temurin'
+
+ - run: ./gradlew :java:testRealtimeSuite -Pokhttp

README.md

@@ -500,6 +500,67 @@ realtime.setAndroidContext(context);
 realtime.push.activate();
 ```
 
+## Using Ably SDK Under a Proxy
+
+When working in environments where outbound internet access is restricted, such as behind a corporate proxy, the Ably SDK allows you to configure a proxy server for HTTP and WebSocket connections.
+
+### Add the Required Dependency
+
+You need to use **OkHttp** library for making HTTP calls and WebSocket connections in the Ably SDK to get proxy support both for your Rest and Realtime clients.
+
+Add the following dependency to your `build.gradle` file:
+
+```groovy
+dependencies {
+ runtimeOnly("io.ably:network-client-okhttp:1.2.43")
+}
+```
+
+### Configure Proxy Settings
+
+After adding the required OkHttp dependency, you need to configure the proxy settings for your Ably client. This can be done by setting the proxy options in the `ClientOptions` object when you instantiate the Ably SDK.
+
+Here’s an example of how to configure and use a proxy:
+
+#### Java Example
+
+```java
+import io.ably.lib.realtime.AblyRealtime;
+import io.ably.lib.rest.AblyRest;
+import io.ably.lib.transport.Defaults;
+import io.ably.lib.types.ClientOptions;
+import io.ably.lib.types.ProxyOptions;
+import io.ably.lib.http.HttpAuth;
+
+public class AblyWithProxy {
+ public static void main(String[] args) throws Exception {
+ // Configure Ably Client options
+ ClientOptions options = new ClientOptions();
+
+ // Setup proxy settings
+ ProxyOptions proxy = new ProxyOptions();
+ proxy.host = "your-proxy-host"; // Replace with your proxy host
+ proxy.port = 8080; // Replace with your proxy port
+
+ // Optional: If the proxy requires authentication
+ proxy.username = "your-username"; // Replace with proxy username
+ proxy.password = "your-password"; // Replace with proxy password
+ proxy.prefAuthType = HttpAuth.Type.BASIC; // Choose your preferred authentication type (e.g., BASIC or DIGEST)
+
+ // Attach the proxy settings to the client options
+ options.proxy = proxy;
+
+ // Create an instance of Ably using the configured options
+ AblyRest ably = new AblyRest(options);
+
+ // Alternatively, for real-time connections
+ AblyRealtime ablyRealtime = new AblyRealtime(options);
+
+ // Use the Ably client as usual
+ }
+}
+```
+
 ## Resources
 
 Visit https://www.ably.com/docs for a complete API reference and more examples.

build.gradle.kts

@@ -7,6 +7,7 @@ plugins {
  alias(libs.plugins.android.library) apply false
  alias(libs.plugins.maven.publish) apply false
  alias(libs.plugins.lombok) apply false
+ alias(libs.plugins.test.retry) apply false
 }
 
 subprojects {

gradle/libs.versions.toml

@@ -17,6 +17,8 @@ dexmaker = "1.4"
 android-retrostreams = "1.7.4"
 maven-publish = "0.29.0"
 lombok = "8.10"
+okhttp = "4.12.0"
+test-retry = "1.6.0"
 
 [libraries]
 gson = { group = "com.google.code.gson", name = "gson", version.ref = "gson" }
@@ -38,6 +40,7 @@ dexmaker = { group = "com.crittercism.dexmaker", name = "dexmaker", version.ref
 dexmaker-dx = { group = "com.crittercism.dexmaker", name = "dexmaker-dx", version.ref = "dexmaker" }
 dexmaker-mockito = { group = "com.crittercism.dexmaker", name = "dexmaker-mockito", version.ref = "dexmaker" }
 android-retrostreams = { group = "net.sourceforge.streamsupport", name = "android-retrostreams", version.ref = "android-retrostreams" }
+okhttp = { group ="com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
 
 [bundles]
 common = ["msgpack", "vcdiff-core"]
@@ -49,3 +52,4 @@ 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" }
+test-retry = { id = "org.gradle.test-retry", version.ref = "test-retry" }

java/build.gradle.kts

@@ -3,6 +3,7 @@ import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 plugins {
  alias(libs.plugins.build.config)
  alias(libs.plugins.maven.publish)
+ alias(libs.plugins.test.retry)
  checkstyle
  `java-library`
 }
@@ -20,7 +21,11 @@ dependencies {
  api(libs.gson)
  implementation(libs.bundles.common)
  implementation(project(":network-client-core"))
- runtimeOnly(project(":network-client-default"))
+ if (findProperty("okhttp") == null) {
+ runtimeOnly(project(":network-client-default"))
+ } else {
+ runtimeOnly(project(":network-client-okhttp"))
+ }
  testImplementation(libs.bundles.tests)
 }
 
@@ -59,6 +64,12 @@ tasks.register<Test>("testRealtimeSuite") {
  testLogging {
  exceptionFormat = TestExceptionFormat.FULL
  }
+ retry {
+ maxRetries.set(3)
+ maxFailures.set(8)
+ failOnPassedAfterRetry.set(false)
+ failOnSkippedAfterRetry.set(false)
+ }
 }
 
 tasks.register<Test>("testRestSuite") {
@@ -72,6 +83,12 @@ tasks.register<Test>("testRestSuite") {
  testLogging {
  exceptionFormat = TestExceptionFormat.FULL
  }
+ retry {
+ maxRetries.set(3)
+ maxFailures.set(8)
+ failOnPassedAfterRetry.set(false)
+ failOnSkippedAfterRetry.set(false)
+ }
 }
 
 /*

lib/src/main/java/io/ably/lib/transport/WebSocketTransport.java

@@ -1,12 +1,13 @@
 package io.ably.lib.transport;
 
 import io.ably.lib.http.HttpUtils;
+import io.ably.lib.network.EngineType;
+import io.ably.lib.network.NotConnectedException;
 import io.ably.lib.network.WebSocketClient;
 import io.ably.lib.network.WebSocketEngine;
 import io.ably.lib.network.WebSocketEngineConfig;
 import io.ably.lib.network.WebSocketEngineFactory;
 import io.ably.lib.network.WebSocketListener;
-import io.ably.lib.network.NotConnectedException;
 import io.ably.lib.types.AblyException;
 import io.ably.lib.types.ErrorInfo;
 import io.ably.lib.types.Param;
@@ -17,6 +18,8 @@
 
 import javax.net.ssl.SSLContext;
 import java.nio.ByteBuffer;
+import java.security.KeyManagementException;
+import java.security.NoSuchAlgorithmException;
 import java.util.Timer;
 import java.util.TimerTask;
 
@@ -48,16 +51,43 @@ public class WebSocketTransport implements ITransport {
  private String wsUri;
  private ConnectListener connectListener;
  private WebSocketClient webSocketClient;
+ private final WebSocketEngine webSocketEngine;
+ private boolean activityCheckTurnedOff = false;
+
  /******************
  * protected constructor
  ******************/
-
  protected WebSocketTransport(TransportParams params, ConnectionManager connectionManager) {
  this.params = params;
  this.connectionManager = connectionManager;
  this.channelBinaryMode = params.options.useBinaryProtocol;
- /* We do not require Ably heartbeats, as we can use WebSocket pings instead. */
- params.heartbeats = false;
+ this.webSocketEngine = createWebSocketEngine(params);
+ params.heartbeats = !this.webSocketEngine.isPingListenerSupported();
+
+ }
+
+ private static WebSocketEngine createWebSocketEngine(TransportParams params) {
+ WebSocketEngineFactory engineFactory = WebSocketEngineFactory.getFirstAvailable();
+ Log.v(TAG, String.format("Using %s WebSocket Engine", engineFactory.getEngineType().name()));
+ WebSocketEngineConfig.WebSocketEngineConfigBuilder configBuilder = WebSocketEngineConfig.builder();
+ configBuilder
+ .tls(params.options.tls)
+ .host(params.host)
+ .proxy(ClientOptionsUtils.convertToProxyConfig(params.getClientOptions()));
+
+ // OkHttp supports modern TLS algorithms by default
+ if (params.options.tls && engineFactory.getEngineType() != EngineType.OKHTTP) {
+ try {
+ SSLContext sslContext = SSLContext.getInstance("TLS");
+ sslContext.init(null, null, null);
+ SafeSSLSocketFactory factory = new SafeSSLSocketFactory(sslContext.getSocketFactory());
+ configBuilder.sslSocketFactory(factory);
+ } catch (NoSuchAlgorithmException | KeyManagementException e) {
+ throw new IllegalStateException("Can't get safe tls algorithms", e);
+ }
+ }
+
+ return engineFactory.create(configBuilder.build());
  }
 
  /******************
@@ -78,24 +108,7 @@ public void connect(ConnectListener connectListener) {
 
  Log.d(TAG, "connect(); wsUri = " + wsUri);
  synchronized (this) {
- WebSocketEngineFactory engineFactory = WebSocketEngineFactory.getFirstAvailable();
- Log.v(TAG, String.format("Using %s WebSocket Engine", engineFactory.getEngineType().name()));
-
- WebSocketEngineConfig.WebSocketEngineConfigBuilder configBuilder = WebSocketEngineConfig.builder();
- configBuilder
- .tls(isTls)
- .host(params.host)
- .proxy(ClientOptionsUtils.convertToProxyConfig(params.getClientOptions()));
-
- if (isTls) {
- SSLContext sslContext = SSLContext.getInstance("TLS");
- sslContext.init(null, null, null);
- SafeSSLSocketFactory factory = new SafeSSLSocketFactory(sslContext.getSocketFactory());
- configBuilder.sslSocketFactory(factory);
- }
-
- WebSocketEngine engine = engineFactory.create(configBuilder.build());
- webSocketClient = engine.create(wsUri, new WebSocketHandler(this::receive));
+ webSocketClient = this.webSocketEngine.create(wsUri, new WebSocketHandler(this::receive));
  }
  webSocketClient.connect();
  } catch (AblyException e) {
@@ -161,6 +174,16 @@ protected void preProcessReceivedMessage(ProtocolMessage message) {
  //Gives the chance to child classes to do message pre-processing
  }
 
+ /**
+ * Visible For Testing
+ * </p>
+ * We need to turn off activity check for some tests (e.g. io.ably.lib.test.realtime.RealtimeConnectFailTest.disconnect_retry_channel_timeout_jitter_after_consistent_detach[binary_protocol])
+ * Those tests expects that activity checks are passing, but protocol messages are not coming
+ */
+ protected void turnOffActivityCheckIfPingListenerIsNotSupported() {
+ if (!webSocketEngine.isPingListenerSupported()) activityCheckTurnedOff = true;
+ }
+
  public String toString() {
  return WebSocketTransport.class.getName() + " {" + getURL() + "}";
  }
@@ -307,7 +330,7 @@ private synchronized void dispose() {
  private synchronized void flagActivity() {
  lastActivityTime = System.currentTimeMillis();
  connectionManager.setLastActivity(lastActivityTime);
- if (activityTimerTask == null && connectionManager.maxIdleInterval != 0) {
+ if (activityTimerTask == null && connectionManager.maxIdleInterval != 0 && !activityCheckTurnedOff) {
  /* No timer currently running because previously there was no
  * maxIdleInterval configured, but now there is a
  * maxIdleInterval configured. Call checkActivity so a timer

lib/src/test/java/io/ably/lib/test/util/MockWebsocketFactory.java

@@ -155,6 +155,7 @@ private MockWebsocketTransport(TransportParams givenTransportParams, TransportPa
  super(transformedTransportParams, connectionManager);
  this.givenTransportParams = givenTransportParams;
  this.transformedTransportParams = transformedTransportParams;
+ turnOffActivityCheckIfPingListenerIsNotSupported();
  }
 
  public List<ProtocolMessage> getSentMessages() {

network-client-core/build.gradle.kts

@@ -1,6 +1,7 @@
 plugins {
  `java-library`
  alias(libs.plugins.lombok)
+ alias(libs.plugins.maven.publish)
 }
 
 java {

network-client-core/gradle.properties

@@ -0,0 +1,4 @@
+POM_ARTIFACT_ID=network-client-core
+POM_NAME=Core HTTP client abstraction
+POM_DESCRIPTION=Core HTTP client abstraction
+POM_PACKAGING=jar

network-client-core/src/main/java/io/ably/lib/network/WebSocketEngine.java

@@ -2,4 +2,5 @@
 
 public interface WebSocketEngine {
  WebSocketClient create(String url, WebSocketListener listener);
+ boolean isPingListenerSupported();
 }

network-client-core/src/main/java/io/ably/lib/network/WebSocketEngineFactory.java

@@ -16,7 +16,7 @@ static WebSocketEngineFactory getFirstAvailable() {
 
  static WebSocketEngineFactory tryGetOkWebSocketFactory() {
  try {
- Class<?> okWebSocketFactoryClass = Class.forName("io.ably.lib.network.OkWebSocketEngineFactory");
+ Class<?> okWebSocketFactoryClass = Class.forName("io.ably.lib.network.OkHttpWebSocketEngineFactory");
  return (WebSocketEngineFactory) okWebSocketFactoryClass.getDeclaredConstructor().newInstance();
  } catch (ClassNotFoundException | InstantiationException | IllegalAccessException | NoSuchMethodException |
  InvocationTargetException e) {

network-client-default/build.gradle.kts

@@ -10,6 +10,6 @@ java {
 }
 
 dependencies {
-api(project(":network-client-core"))
+implementation(project(":network-client-core"))
  implementation(libs.java.websocket)
 }

network-client-default/src/main/java/io/ably/lib/network/DefaultWebSocketEngine.java

@@ -17,4 +17,9 @@ public WebSocketClient create(String url, WebSocketListener listener) {
  }
  return client;
  }
+
+ @Override
+ public boolean isPingListenerSupported() {
+ return true;
+ }
 }

network-client-okhttp/build.gradle.kts

@@ -0,0 +1,15 @@
+plugins {
+ `java-library`
+ alias(libs.plugins.lombok)
+ alias(libs.plugins.maven.publish)
+}
+
+java {
+ sourceCompatibility = JavaVersion.VERSION_1_8
+ targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+dependencies {
+ implementation(project(":network-client-core"))
+ implementation(libs.okhttp)
+}

network-client-okhttp/gradle.properties

@@ -0,0 +1,4 @@
+POM_ARTIFACT_ID=network-client-okhttp
+POM_NAME=Default HTTP client
+POM_DESCRIPTION=Default implementation for HTTP client
+POM_PACKAGING=jar