[ECO-5099] Update RoomStatus and ConnectionStatus interfaces

chat-android/src/main/java/com/ably/chat/Connection.kt

@@ -1,5 +1,73 @@
 package com.ably.chat
 
+import io.ably.lib.types.ErrorInfo
+
+/**
+ * Default timeout for transient states before we attempt handle them as a state change.
+ */
+const val TRANSIENT_TIMEOUT = 5000
+
+/**
+ * The different states that the connection can be in through its lifecycle.
+ */
+enum class ConnectionStatus(val stateName: String) {
+    /**
+     * A temporary state for when the library is first initialized.
+     */
+    Initialized("initialized"),
+
+    /**
+     * The library is currently connecting to Ably.
+     */
+    Connecting("connecting"),
+
+    /**
+     * The library is currently connected to Ably.
+     */
+    Connected("connected"),
+
+    /**
+     * The library is currently disconnected from Ably, but will attempt to reconnect.
+     */
+    Disconnected("disconnected"),
+
+    /**
+     * The library is in an extended state of disconnection, but will attempt to reconnect.
+     */
+    Suspended("suspended"),
+
+    /**
+     * The library is currently disconnected from Ably and will not attempt to reconnect.
+     */
+    Failed("failed"),
+}
+
+/**
+ * Represents a change in the status of the connection.
+ */
+data class ConnectionStatusChange(
+    /**
+     * The new status of the connection.
+     */
+    val current: ConnectionStatus,
+
+    /**
+     * The previous status of the connection.
+     */
+    val previous: ConnectionStatus,
+
+    /**
+     * An error that provides a reason why the connection has
+     * entered the new status, if applicable.
+     */
+    val error: ErrorInfo?,
+
+    /**
+     * The time in milliseconds that the client will wait before attempting to reconnect.
+     */
+    val retryIn: Long?,
+)
+
 /**
  * Represents a connection to Ably.
  */
@@ -8,4 +76,32 @@ interface Connection {
      * The current status of the connection.
      */
     val status: ConnectionStatus
+
+    /**
+     * The current error, if any, that caused the connection to enter the current status.
+     */
+    val error: ErrorInfo?
+
+    /**
+     * Registers a listener that will be called whenever the connection status changes.
+     * @param listener The function to call when the status changes.
+     * @returns An object that can be used to unregister the listener.
+     */
+    fun onStatusChange(listener: Listener): Subscription
+
+    /**
+     * An interface for listening to changes for the connection status
+     */
+    fun interface Listener {
+        /**
+         * A function that can be called when the connection status changes.
+         * @param change The change in status.
+         */
+        fun connectionStatusChanged(change: ConnectionStatusChange)
+    }
+
+    /**
+     * Removes all listeners that were added by the `onStatusChange` method.
+     */
+    fun offAllStatusChange()
 }

chat-android/src/main/java/com/ably/chat/Room.kt

@@ -2,6 +2,7 @@
 
 package com.ably.chat
 
+import io.ably.lib.types.ErrorInfo
 import io.ably.lib.util.Log.LogHandler
 import kotlinx.coroutines.CoroutineName
 import kotlinx.coroutines.CoroutineScope
@@ -56,20 +57,37 @@ interface Room {
      */
     val occupancy: Occupancy
 
+    /**
+     * Returns the room options.
+     *
+     * @returns A copy of the options used to create the room.
+     */
+    val options: RoomOptions
+
     /**
      * (CHA-RS2)
-     * Returns an object that can be used to observe the status of the room.
+     * The current status of the room.
      *
-     * @returns The status observable.
+     * @returns The current status.
      */
     val status: RoomStatus
 
     /**
-     * Returns the room options.
-     *
-     * @returns A copy of the options used to create the room.
+     * The current error, if any, that caused the room to enter the current status.
      */
-    val options: RoomOptions
+    val error: ErrorInfo?
+
+    /**
+     * Registers a listener that will be called whenever the room status changes.
+     * @param listener The function to call when the status changes.
+     * @returns An object that can be used to unregister the listener.
+     */
+    fun onStatusChange(listener: RoomLifecycle.Listener): Subscription
+
+    /**
+     * Removes all listeners that were added by the `onStatusChange` method.
+     */
+    fun offAllStatusChange()
 
     /**
      * Attaches to the room to receive events in realtime.
@@ -98,7 +116,6 @@ internal class DefaultRoom(
 ) : Room {
 
     private val _logger = logger
-    override val status = DefaultStatus(logger)
 
     /**
      * RoomScope is a crucial part of the Room lifecycle. It manages sequential and atomic operations.
@@ -132,9 +149,18 @@ internal class DefaultRoom(
     override val occupancy = DefaultOccupancy(
         messages = messages,
     )
-
     private var _lifecycleManager: RoomLifecycleManager? = null
 
+    private val _statusLifecycle = DefaultRoomLifecycle(logger)
+    internal val statusLifecycle: DefaultRoomLifecycle
+        get() = _statusLifecycle
+
+    override val status: RoomStatus
+        get() = _statusLifecycle.status
+
+    override val error: ErrorInfo?
+        get() = _statusLifecycle.error
+
     init {
         /**
          * TODO
@@ -143,15 +169,21 @@ internal class DefaultRoom(
          * Currently, all features are initialized by default.
          */
         val features = listOf(messages, presence, typing, reactions, occupancy)
-        _lifecycleManager = RoomLifecycleManager(roomScope, status, features, _logger)
+        _lifecycleManager = RoomLifecycleManager(roomScope, _statusLifecycle, features, _logger)
         /**
          * TODO
          * Make sure previous release op. for same was a success.
          * Make sure channels were removed using realtime.channels.release(contributor.channel.name);
          * Once this is a success, set room to initialized, if not set it to failed and throw error.
          * Note that impl. can change based on recent proposed changes to chat-room-lifecycle DR.
          */
-        this.status.setStatus(RoomLifecycle.Initialized)
+        this._statusLifecycle.setStatus(RoomStatus.Initialized)
+    }
+
+    override fun onStatusChange(listener: RoomLifecycle.Listener): Subscription = _statusLifecycle.onChange(listener)
+
+    override fun offAllStatusChange() {
+        _statusLifecycle.offAll()
     }
 
     override suspend fun attach() {