uts: introduce Clock abstraction for time operations and testability

- Added `Clock` interface and concrete implementations (`SystemClock` and `FakeClock`) for unified time management.
- Refactored classes (`Auth`, `Presence`, `Hosts`, `WebSocketTransport`, etc.) to use `Clock` instead of direct system calls.
- Enabled mockable time-based operations for improved testability.
- Updated `DebugOptions` to support custom clocks in debug mode.

Author: ttypic

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

@@ -11,6 +11,7 @@
 import io.ably.lib.types.AblyException;
 import io.ably.lib.types.ClientOptions;
 import io.ably.lib.types.ProtocolMessage;
+import io.ably.lib.util.Clock;
 
 public class DebugOptions extends ClientOptions {
     public interface RawProtocolListener {
@@ -35,6 +36,7 @@ public interface RawHttpListener {
     public ITransport.Factory transportFactory;
     public HttpEngine httpEngine;
     public WebSocketEngineFactory webSocketEngineFactory;
+    public Clock clock;
 
     public DebugOptions copy() {
         DebugOptions copied = new DebugOptions();
@@ -43,6 +45,7 @@ public DebugOptions copy() {
         copied.transportFactory = transportFactory;
         copied.httpEngine = httpEngine;
         copied.webSocketEngineFactory = webSocketEngineFactory;
+        copied.clock = clock;
         copied.clientId = clientId;
         copied.logLevel = logLevel;
         copied.logHandler = logHandler;

lib/src/main/java/io/ably/lib/http/HttpScheduler.java

@@ -13,7 +13,9 @@
 import io.ably.lib.types.Callback;
 import io.ably.lib.types.ErrorInfo;
 import io.ably.lib.types.Param;
+import io.ably.lib.util.Clock;
 import io.ably.lib.util.Log;
+import io.ably.lib.util.SystemClock;
 
 /**
  * HttpScheduler schedules HttpCore operations to an Executor, exposing a generic async API.
@@ -286,12 +288,12 @@ public T get() throws InterruptedException, ExecutionException {
         }
         @Override
         public T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException {
-            long remaining = unit.toMillis(timeout), deadline = System.currentTimeMillis() + remaining;
+            long remaining = unit.toMillis(timeout), deadline = clock.currentTimeMillis() + remaining;
             synchronized(this) {
                 while(remaining > 0) {
                     wait(remaining);
                     if(isDone) { break; }
-                    remaining = deadline - System.currentTimeMillis();
+                    remaining = deadline - clock.currentTimeMillis();
                 }
                 if(!isDone) {
                     throw new TimeoutException();
@@ -360,6 +362,7 @@ protected synchronized boolean disposeConnection() {
     protected HttpScheduler(HttpCore httpCore, CloseableExecutor executor) {
         this.httpCore = httpCore;
         this.executor = executor;
+        this.clock = SystemClock.clockFrom(httpCore.options);
     }
 
     @Override
@@ -446,6 +449,7 @@ public <T> Future<T> ablyHttpExecuteWithRetry(
 
     protected final CloseableExecutor executor;
     private final HttpCore httpCore;
+    private final Clock clock;
 
     protected static final String TAG = HttpScheduler.class.getName();
 

lib/src/main/java/io/ably/lib/realtime/ChannelBase.java

@@ -6,7 +6,6 @@
 import java.util.Locale;
 import java.util.Map;
 import java.util.Set;
-import java.util.Timer;
 import java.util.TimerTask;
 import java.util.concurrent.atomic.AtomicBoolean;
 
@@ -46,12 +45,15 @@
 import io.ably.lib.types.PublishResult;
 import io.ably.lib.types.Summary;
 import io.ably.lib.types.UpdateDeleteResult;
+import io.ably.lib.util.Clock;
 import io.ably.lib.util.CollectionUtils;
 import io.ably.lib.util.EventEmitter;
 import io.ably.lib.util.Listeners;
 import io.ably.lib.util.Log;
+import io.ably.lib.util.NamedTimer;
 import io.ably.lib.util.ReconnectionStrategy;
 import io.ably.lib.util.StringUtils;
+import io.ably.lib.util.SystemClock;
 import org.jetbrains.annotations.Blocking;
 import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.Nullable;
@@ -508,21 +510,20 @@ private void setFailed(ErrorInfo reason) {
     }
 
     /* Timer for attach operation */
-    private Timer attachTimer;
+    private NamedTimer attachTimer;
 
     /* Timer for reattaching if attach failed */
-    private Timer reattachTimer;
+    private NamedTimer reattachTimer;
 
     /**
      * Cancel attach/reattach timers
      */
     synchronized private void clearAttachTimers() {
-        Timer[] timers = new Timer[]{attachTimer, reattachTimer};
+        NamedTimer[] timers = new NamedTimer[]{attachTimer, reattachTimer};
         attachTimer = reattachTimer = null;
-        for (Timer t: timers) {
+        for (NamedTimer t: timers) {
             if (t != null) {
                 t.cancel();
-                t.purge();
             }
         }
     }
@@ -537,9 +538,9 @@ private void attachWithTimeout(final CompletionListener listener) throws AblyExc
      */
     synchronized private void attachWithTimeout(final boolean forceReattach, final CompletionListener listener, ErrorInfo reattachmentReason) {
         checkChannelIsNotReleased();
-        Timer currentAttachTimer;
+        NamedTimer currentAttachTimer;
         try {
-            currentAttachTimer = new Timer();
+            currentAttachTimer = clock.newTimer("attach-timer");
         } catch(Throwable t) {
             /* an exception instancing the timer can arise because the runtime is exiting */
             callCompletionListenerError(listener, ErrorInfo.fromThrowable(t));
@@ -571,7 +572,7 @@ public void onError(ErrorInfo reason) {
             return;
         }
 
-        final Timer inProgressTimer = currentAttachTimer;
+        final NamedTimer inProgressTimer = currentAttachTimer;
         attachTimer.schedule(
                 new TimerTask() {
                     @Override
@@ -601,9 +602,9 @@ private void checkChannelIsNotReleased() {
      * try to attach the channel
      */
     synchronized private void reattachAfterTimeout() {
-        Timer currentReattachTimer;
+        NamedTimer currentReattachTimer;
         try {
-            currentReattachTimer = new Timer();
+            currentReattachTimer = clock.newTimer("reattach-timer");
         } catch(Throwable t) {
             /* an exception instancing the timer can arise because the runtime is exiting */
             return;
@@ -613,7 +614,7 @@ synchronized private void reattachAfterTimeout() {
         this.retryAttempt++;
         int retryDelay = ReconnectionStrategy.getRetryTime(ably.options.channelRetryTimeout, retryAttempt);
 
-        final Timer inProgressTimer = currentReattachTimer;
+        final NamedTimer inProgressTimer = currentReattachTimer;
         reattachTimer.schedule(new TimerTask() {
             @Override
             public void run() {
@@ -640,9 +641,9 @@ public void run() {
      */
     synchronized private void detachWithTimeout(final CompletionListener listener) {
         final ChannelState originalState = state;
-        Timer currentDetachTimer;
+        NamedTimer currentDetachTimer;
         try {
-            currentDetachTimer = released.get() ? null : new Timer();
+            currentDetachTimer = released.get() ? null : clock.newTimer("detach-timer");
         } catch(Throwable t) {
             /* an exception instancing the timer can arise because the runtime is exiting */
             callCompletionListenerError(listener, ErrorInfo.fromThrowable(t));
@@ -676,7 +677,7 @@ public void onError(ErrorInfo reason) {
             return;
         }
 
-        final Timer inProgressTimer = currentDetachTimer;
+        final NamedTimer inProgressTimer = currentDetachTimer;
         attachTimer.schedule(new TimerTask() {
             @Override
             public void run() {
@@ -1684,6 +1685,7 @@ else if(stateChange.current.equals(failureState)) {
     ChannelBase(AblyRealtime ably, String name, ChannelOptions options, @Nullable LiveObjectsPlugin liveObjectsPlugin) throws AblyException {
         Log.v(TAG, "RealtimeChannel(); channel = " + name);
         this.ably = ably;
+        this.clock = SystemClock.clockFrom(ably.options);
         this.name = name;
         this.basePath = "/channels/" + HttpUtils.encodeURIComponent(name);
         this.setOptions(options);
@@ -1808,6 +1810,7 @@ public void sendProtocolMessage(ProtocolMessage protocolMessage, CompletionListe
 
     private static final String TAG = Channel.class.getName();
     final AblyRealtime ably;
+    final Clock clock;
     final String basePath;
     ChannelOptions options;
     /**

lib/src/main/java/io/ably/lib/realtime/Presence.java

@@ -331,7 +331,7 @@ private void endSync() {
         for (PresenceMessage member: residualMembers) {         // RTP19
             member.action = PresenceMessage.Action.leave;
             member.id = null;
-            member.timestamp = System.currentTimeMillis();
+            member.timestamp = channel.clock.currentTimeMillis();
         }
         broadcastPresence(residualMembers);
     }

lib/src/main/java/io/ably/lib/rest/Auth.java

@@ -27,8 +27,10 @@
 import io.ably.lib.types.NonRetriableTokenException;
 import io.ably.lib.types.Param;
 import io.ably.lib.util.Base64Coder;
+import io.ably.lib.util.Clock;
 import io.ably.lib.util.Log;
 import io.ably.lib.util.Serialisation;
+import io.ably.lib.util.SystemClock;
 
 /**
  * Token-generation and authentication operations for the Ably API.
@@ -921,7 +923,7 @@ else if(!request.keyName.equals(keyName))
         if(request.timestamp == 0) {
             if(options.queryTime) {
                 long oldNanoTimeDelta = nanoTimeDelta;
-                long currentNanoTimeDelta = System.currentTimeMillis() - System.nanoTime()/(1000*1000);
+                long currentNanoTimeDelta = clock.currentTimeMillis() - System.nanoTime()/(1000*1000);
 
                 if (timeDelta != Long.MAX_VALUE) {
                     /* system time changed by more than 500ms since last time? */
@@ -1036,7 +1038,7 @@ public void onAuthError(ErrorInfo err) {
             clearTokenDetails();
     }
 
-    public static long timestamp() { return System.currentTimeMillis(); }
+    public long timestamp() { return clock.currentTimeMillis(); }
 
     /********************
      * internal
@@ -1050,6 +1052,8 @@ public void onAuthError(ErrorInfo err) {
      */
     Auth(AblyBase ably, ClientOptions options) throws AblyException {
         this.ably = ably;
+        this.clock = SystemClock.clockFrom(options);
+        this.nanoTimeDelta = clock.currentTimeMillis() - System.nanoTime()/(1000*1000);
         authOptions = options;
         tokenParams = options.defaultTokenParams != null ?
                 options.defaultTokenParams : new TokenParams();
@@ -1304,6 +1308,7 @@ public long serverTimestamp() {
 
     private static final String TAG = Auth.class.getName();
     private final AblyBase ably;
+    private final Clock clock;
     private final AuthMethod method;
     private AuthOptions authOptions;
     private TokenParams tokenParams;
@@ -1320,7 +1325,7 @@ public long serverTimestamp() {
      * Time delta between System.nanoTime() and System.currentTimeMillis. If it changes significantly it
      * suggests device time/date has changed
      */
-    private long nanoTimeDelta = System.currentTimeMillis() - System.nanoTime()/(1000*1000);
+    private long nanoTimeDelta;
 
     public static final String WILDCARD_CLIENTID = "*";
     /**

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

@@ -36,9 +36,11 @@
 import io.ably.lib.types.ProtocolMessage;
 import io.ably.lib.types.ProtocolSerializer;
 import io.ably.lib.types.PublishResult;
+import io.ably.lib.util.Clock;
 import io.ably.lib.util.Log;
 import io.ably.lib.util.PlatformAgentProvider;
 import io.ably.lib.util.ReconnectionStrategy;
+import io.ably.lib.util.SystemClock;
 import org.jetbrains.annotations.Nullable;
 
 public class ConnectionManager implements ConnectListener {
@@ -782,6 +784,7 @@ public void run() {
 
     public ConnectionManager(final AblyRealtime ably, final Connection connection, final Channels channels, final PlatformAgentProvider platformAgentProvider, LiveObjectsPlugin liveObjectsPlugin) throws AblyException {
         this.ably = ably;
+        this.clock = SystemClock.clockFrom(ably.options);
         this.connection = connection;
         this.channels = channels;
         this.platformAgentProvider = platformAgentProvider;
@@ -1447,7 +1450,7 @@ private boolean checkConnectionStale() {
         if(lastActivity == 0) {
             return false;
         }
-        long now = System.currentTimeMillis();
+        long now = clock.currentTimeMillis();
         long intervalSinceLastActivity = now - lastActivity;
         if(intervalSinceLastActivity > (maxIdleInterval + connectionStateTtl)) {
             /* RTN15g1, RTN15g2 Force a new connection if the previous one is stale;
@@ -1465,7 +1468,7 @@ private boolean checkConnectionStale() {
     }
 
     private synchronized void setSuspendTime() {
-        suspendTime = (System.currentTimeMillis() + connectionStateTtl);
+        suspendTime = (clock.currentTimeMillis() + connectionStateTtl);
     }
 
     /**
@@ -1490,7 +1493,7 @@ private StateIndication checkFallback(ErrorInfo reason) {
     }
 
     private synchronized StateIndication checkSuspended(ErrorInfo reason) {
-        long currentTime = System.currentTimeMillis();
+        long currentTime = clock.currentTimeMillis();
         long timeToSuspend = suspendTime - currentTime;
         boolean suspendMode = timeToSuspend <= 0;
         Log.v(TAG, "checkSuspended: timeToSuspend = " + timeToSuspend + "ms; suspendMode = " + suspendMode);
@@ -2015,6 +2018,7 @@ private boolean isFatalError(ErrorInfo err) {
      ******************/
 
     final AblyRealtime ably;
+    private final Clock clock;
     private final Channels channels;
     private final Connection connection;
     private final ITransport.Factory transportFactory;

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

@@ -3,6 +3,8 @@
 import io.ably.lib.types.AblyException;
 import io.ably.lib.types.ClientOptions;
 import io.ably.lib.types.ErrorInfo;
+import io.ably.lib.util.Clock;
+import io.ably.lib.util.SystemClock;
 
 import java.util.Arrays;
 import java.util.Collections;
@@ -23,6 +25,7 @@ public class Hosts {
     private final long fallbackRetryTimeout;
 
     private final Preferred preferred = new Preferred();
+    private final Clock clock;
 
     /**
      * Create Hosts object
@@ -77,6 +80,7 @@ public Hosts(final String primaryHost, final String defaultHost, final ClientOpt
         /* RSC15a: shuffle the fallback hosts. */
         Collections.shuffle(Arrays.asList(fallbackHosts));
         fallbackRetryTimeout = options.fallbackRetryTimeout;
+        this.clock = SystemClock.clockFrom(options);
     }
 
     /**
@@ -91,7 +95,7 @@ public synchronized void setPreferredHost(final String prefHost, final boolean t
             /* a successful request against the primary host; reset */
             preferred.clear();
         } else {
-            preferred.setHost(prefHost, temporary ? System.currentTimeMillis() + fallbackRetryTimeout : 0);
+            preferred.setHost(prefHost, temporary ? clock.currentTimeMillis() + fallbackRetryTimeout : 0);
         }
     }
 
@@ -106,7 +110,7 @@ public String getPrimaryHost() {
      * Get preferred host name (taking into account any affinity to a fallback: see RSC15f)
      */
     public synchronized String getPreferredHost() {
-        final String host = preferred.getHostOrClearIfExpired();
+        final String host = preferred.getHostOrClearIfExpired(clock);
         return (host == null) ? primaryHost : host;
     }
 
@@ -128,7 +132,7 @@ public synchronized String getFallback(String lastHost) {
             if (!primaryHostIsDefault && !fallbackHostsUseDefault && fallbackHostsIsDefault)
                 return null;
             idx = 0;
-        } else if(lastHost.equals(preferred.getHostOrClearIfExpired())) {
+        } else if(lastHost.equals(preferred.getHostOrClearIfExpired(clock))) {
             /* RSC15f: there was a failure on an unexpired, cached fallback; so try again using the primary */
             preferred.clear();
             return primaryHost;
@@ -174,8 +178,8 @@ public void setHost(final String host, final long expiry) {
             this.expiry = expiry;
         }
 
-        public String getHostOrClearIfExpired() {
-            if(expiry > 0 && expiry <= System.currentTimeMillis()) {
+        public String getHostOrClearIfExpired(Clock clock) {
+            if(expiry > 0 && expiry <= clock.currentTimeMillis()) {
                 clear(); // expired, so reset
             }
             return host;