KeepAliveGatt EventHandler

keep-alive/README.md

@@ -21,7 +21,7 @@ fun CoroutineScope.keepAliveGatt(
 | `androidContext`          | The Android `Context` for establishing Bluetooth Low-Energy connections.                                                  |
 | `bluetoothDevice`         | `BluetoothDevice` to maintain a connection with.                                                                          |
 | `disconnectTimeoutMillis` | Duration (in milliseconds) to wait for connection to gracefully spin down (after `disconnect`) before forcefully closing. |
-| `onConnectAction`         | Actions to perform upon connection. `Connected` state is propagated _after_ `onConnectAction` completes.                  |
+| `onEvent`                 | Actions to perform on various events within the KeepAliveGatt's lifecycle. (Connected / Disconnected)                     |
 
 For example, to create a `KeepAliveGatt` as a child of Android's `viewModelScope`:
 
@@ -34,10 +34,7 @@ class ExampleViewModel(application: Application) : AndroidViewModel(application)
         application,
         bluetoothAdapter.getRemoteDevice(MAC_ADDRESS),
         disconnectTimeoutMillis = 5_000L // 5 seconds
-    ) {
-        // Actions to perform on initial connect *and* subsequent reconnects:
-        discoverServicesOrThrow()
-    }
+    )
 
     fun connect() {
         gatt.connect()
@@ -73,9 +70,45 @@ Once `Connected`, if the connection drops, then `KeepAliveGatt` will automatical
 _To disconnect an established connection or cancel an in-flight connection attempt, `disconnect` can
 be called (it will suspend until underlying [`BluetoothGatt`] has disconnected)._
 
-### Connection State
+## Status
+
+The status of a `KeepAliveGatt` can be monitored via either `Event`s or `State`s. The major
+distinction between the two is:
+
+> **`State`**: `State`s are propagated over conflated data streams. If states are changing quickly,
+> then some `State`s may be missed (skipped over). For this reason, they're useful for informing a
+> user of the current state of the connection; as missing a state is acceptable since subsequent
+> states will overwrite the currently reflected state anyways. `State`s should **not** be used if a
+> specific condition (e.g. `Connected`) needs to trigger an action (use `Event` instead).
+
+> **`Event`**: `Event`s allow a developer to integrate actions into the connection process. When an
+> `Event` is triggered, the connection process is paused (suspended) until processing of the `Event`
+> is complete.
+
+`State`s and `Event`s occur in the following order:
+
+![State and event flow](artwork/state-and-event-flow.png)
+
+### Events
+
+`Event`s are configured via the `eventHandler` argument of the `keepAliveGatt` extension function,
+for example:
+
+```kotlin
+    private val gatt = viewModelScope.keepAliveGatt(...) { event ->
+        event.onConnected {
+            // Actions to perform on initial connect *and* subsequent reconnects:
+            discoverServicesOrThrow()
+        }
+        event.onDisconnected {
+            // todo: retry strategy (e.g. exponentially increasing delay)
+        }
+    }
+```
+
+### State
 
-The state can be monitored via the `state` [`Flow`] property:
+Connection state can be monitored via the `state` [`Flow`] property:
 
 ```kotlin
 val gatt = scope.keepAliveGatt(...)

keep-alive/api/keep-alive.api

@@ -12,6 +12,50 @@ public final class com/juul/able/keepalive/BuildConfig {
 public final class com/juul/able/keepalive/ConnectionRejected : java/io/IOException {
 }
 
+public abstract class com/juul/able/keepalive/Event {
+}
+
+public final class com/juul/able/keepalive/Event$Connected : com/juul/able/keepalive/Event {
+	public fun <init> (Lcom/juul/able/gatt/GattIo;)V
+	public final fun component1 ()Lcom/juul/able/gatt/GattIo;
+	public final fun copy (Lcom/juul/able/gatt/GattIo;)Lcom/juul/able/keepalive/Event$Connected;
+	public static synthetic fun copy$default (Lcom/juul/able/keepalive/Event$Connected;Lcom/juul/able/gatt/GattIo;ILjava/lang/Object;)Lcom/juul/able/keepalive/Event$Connected;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getGatt ()Lcom/juul/able/gatt/GattIo;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/juul/able/keepalive/Event$Disconnected : com/juul/able/keepalive/Event {
+	public fun <init> (ZI)V
+	public final fun component1 ()Z
+	public final fun component2 ()I
+	public final fun copy (ZI)Lcom/juul/able/keepalive/Event$Disconnected;
+	public static synthetic fun copy$default (Lcom/juul/able/keepalive/Event$Disconnected;ZIILjava/lang/Object;)Lcom/juul/able/keepalive/Event$Disconnected;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getConnectionAttempt ()I
+	public final fun getWasConnected ()Z
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/juul/able/keepalive/Event$Rejected : com/juul/able/keepalive/Event {
+	public fun <init> (Ljava/lang/Throwable;)V
+	public final fun component1 ()Ljava/lang/Throwable;
+	public final fun copy (Ljava/lang/Throwable;)Lcom/juul/able/keepalive/Event$Rejected;
+	public static synthetic fun copy$default (Lcom/juul/able/keepalive/Event$Rejected;Ljava/lang/Throwable;ILjava/lang/Object;)Lcom/juul/able/keepalive/Event$Rejected;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getCause ()Ljava/lang/Throwable;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/juul/able/keepalive/EventKt {
+	public static final fun onConnected (Lcom/juul/able/keepalive/Event;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun onDisconnected (Lcom/juul/able/keepalive/Event;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun onRejected (Lcom/juul/able/keepalive/Event;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+}
+
 public final class com/juul/able/keepalive/KeepAliveGatt : com/juul/able/gatt/GattIo {
 	public final fun connect ()Z
 	public final fun disconnect (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;

keep-alive/src/main/java/Event.kt

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2020 JUUL Labs, Inc.
+ */
+
+package com.juul.able.keepalive
+
+import com.juul.able.gatt.GattIo
+
+sealed class Event {
+
+    /** Triggered upon a connection being successfully established. */
+    data class Connected(val gatt: GattIo) : Event()
+
+    /**
+     * Triggered either immediately after an established connection has dropped or after a failed
+     * connection attempt.
+     *
+     * The [connectionAttempt] property represents which connection attempt iteration over the
+     * lifespan of the [KeepAliveGatt]. The value begins at 1 and increase by 1 for each iteration.
+     *
+     * @param wasConnected is `true` if event follows an established connection, or `false` if previous connection attempt failed.
+     * @param connectionAttempt is the number of connection attempts since creation of [KeepAliveGatt].
+     */
+    data class Disconnected(
+        val wasConnected: Boolean,
+        val connectionAttempt: Int
+    ) : Event()
+
+    /**
+     * Triggered when the connection request was rejected by the operating system (e.g. bluetooth
+     * hardware unavailable). [KeepAliveGatt] will not attempt to reconnect until
+     * [connect][KeepAliveGatt.connect] is called again.
+     */
+    data class Rejected(val cause: Throwable) : Event()
+}
+
+suspend fun Event.onConnected(action: suspend GattIo.() -> Unit) {
+    if (this is Event.Connected) action.invoke(gatt)
+}
+
+suspend fun Event.onDisconnected(action: suspend (Event.Disconnected) -> Unit) {
+    if (this is Event.Disconnected) action.invoke(this)
+}
+
+suspend fun Event.onRejected(action: suspend (Event.Rejected) -> Unit) {
+    if (this is Event.Rejected) action.invoke(this)
+}

keep-alive/src/main/java/KeepAliveGatt.kt

@@ -13,6 +13,7 @@ import com.juul.able.Able
 import com.juul.able.android.connectGatt
 import com.juul.able.device.ConnectGattResult.Failure
 import com.juul.able.device.ConnectGattResult.Success
+import com.juul.able.gatt.Gatt
 import com.juul.able.gatt.GattIo
 import com.juul.able.gatt.GattStatus
 import com.juul.able.gatt.OnCharacteristicChanged
@@ -22,10 +23,6 @@ import com.juul.able.gatt.OnDescriptorWrite
 import com.juul.able.gatt.OnMtuChanged
 import com.juul.able.gatt.OnReadRemoteRssi
 import com.juul.able.gatt.WriteType
-import com.juul.able.keepalive.State.Cancelled
-import com.juul.able.keepalive.State.Connected
-import com.juul.able.keepalive.State.Connecting
-import com.juul.able.keepalive.State.Disconnected
 import java.io.IOException
 import java.util.UUID
 import java.util.concurrent.atomic.AtomicBoolean
@@ -53,51 +50,37 @@ import kotlinx.coroutines.supervisorScope
 import kotlinx.coroutines.withContext
 import kotlinx.coroutines.withTimeoutOrNull
 
-typealias ConnectAction = suspend GattIo.() -> Unit
-
 class NotReady internal constructor(message: String) : IllegalStateException(message)
 class ConnectionRejected internal constructor(cause: Throwable) : IOException(cause)
 
-sealed class State {
-    object Connecting : State()
-    object Connected : State()
-    object Disconnecting : State()
-    data class Disconnected(val cause: Throwable? = null) : State() {
-        override fun toString() = super.toString()
-    }
-    data class Cancelled(val cause: Throwable?) : State() {
-        override fun toString() = super.toString()
-    }
-
-    override fun toString(): String = javaClass.simpleName
-}
+typealias EventHandler = suspend (Event) -> Unit
 
 fun CoroutineScope.keepAliveGatt(
     androidContext: Context,
     bluetoothDevice: BluetoothDevice,
     disconnectTimeoutMillis: Long,
-    onConnectAction: ConnectAction? = null
+    eventHandler: EventHandler? = null
 ) = KeepAliveGatt(
     parentCoroutineContext = coroutineContext,
     androidContext = androidContext,
     bluetoothDevice = bluetoothDevice,
     disconnectTimeoutMillis = disconnectTimeoutMillis,
-    onConnectAction = onConnectAction
+    eventHandler = eventHandler
 )
 
 class KeepAliveGatt internal constructor(
     parentCoroutineContext: CoroutineContext,
     androidContext: Context,
     private val bluetoothDevice: BluetoothDevice,
     private val disconnectTimeoutMillis: Long,
-    private val onConnectAction: ConnectAction? = null
+    private val eventHandler: EventHandler?
 ) : GattIo {
 
     private val applicationContext = androidContext.applicationContext
 
     private val job = SupervisorJob(parentCoroutineContext[Job]).apply {
         invokeOnCompletion { cause ->
-            _state.value = Cancelled(cause)
+            _state.value = State.Cancelled(cause)
             _onCharacteristicChanged.cancel()
         }
     }
@@ -110,13 +93,13 @@ class KeepAliveGatt internal constructor(
     private val gatt: GattIo
         inline get() = _gatt ?: throw NotReady(toString())
 
-    private val _state = MutableStateFlow<State>(Disconnected())
+    private val _state = MutableStateFlow<State>(State.Disconnected())
 
     /**
      * Provides a [Flow] of the [KeepAliveGatt]'s [State].
      *
-     * The initial [state] is [Disconnected] and will typically transition through the following
-     * [State]s after [connect] is called:
+     * The initial [state] is [Disconnected][State.Disconnected] and will typically transition
+     * through the following [State]s after [connect] is called:
      *
      * ```
      *                    connect()
@@ -137,13 +120,22 @@ class KeepAliveGatt internal constructor(
 
     private val _onCharacteristicChanged = BroadcastChannel<OnCharacteristicChanged>(BUFFERED)
 
+    private var connectionAttempt = 0
+
     fun connect(): Boolean {
         check(!job.isCancelled) { "Cannot connect, $this is closed" }
         isRunning.compareAndSet(false, true) || return false
 
         scope.launch(CoroutineName("KeepAliveGatt@$bluetoothDevice")) {
             while (isActive) {
-                spawnConnection()
+                connectionAttempt++
+                try {
+                    val didConnect = establishConnection()
+                    eventHandler?.invoke(Event.Disconnected(didConnect, connectionAttempt))
+                } catch (rejected: ConnectionRejected) {
+                    eventHandler?.invoke(Event.Rejected(cause = rejected))
+                    throw rejected
+                }
             }
         }.invokeOnCompletion { isRunning.set(false) }
         return true
@@ -153,16 +145,23 @@ class KeepAliveGatt internal constructor(
         job.children.forEach { it.cancelAndJoin() }
     }
 
-    private suspend fun spawnConnection() {
+    /**
+     * Establishes a connection, suspending until either the attempt at establishing connection
+     * fails or an established connection drops.
+     *
+     * @return `true` if connection was established (then dropped), or `false` if connection attempt failed.
+     * @throws ConnectionRejected if the operating system rejects the connection request.
+     */
+    private suspend fun establishConnection(): Boolean {
         try {
-            _state.value = Connecting
+            _state.value = State.Connecting
 
-            val gatt = when (val result = bluetoothDevice.connectGatt(applicationContext)) {
+            val gatt: Gatt = when (val result = bluetoothDevice.connectGatt(applicationContext)) {
                 is Success -> result.gatt
                 is Failure.Rejected -> throw ConnectionRejected(result.cause)
                 is Failure.Connection -> {
                     Able.error { "Failed to connect to device $bluetoothDevice due to ${result.cause}" }
-                    return
+                    return false
                 }
             }
 
@@ -174,8 +173,8 @@ class KeepAliveGatt internal constructor(
                                 .onEach(_onCharacteristicChanged::send)
                                 .launchIn(this, start = UNDISPATCHED)
                             _gatt = gatt
-                            onConnectAction?.invoke(gatt)
-                            _state.value = Connected
+                            eventHandler?.invoke(Event.Connected(gatt))
+                            _state.value = State.Connected
                         }
                     } finally {
                         _gatt = null
@@ -191,9 +190,10 @@ class KeepAliveGatt internal constructor(
                     }
                 }
             }
-            _state.value = Disconnected()
+            _state.value = State.Disconnected()
+            return true
         } catch (failure: Exception) {
-            _state.value = Disconnected(failure)
+            _state.value = State.Disconnected(failure)
             throw failure
         }
     }

keep-alive/src/main/java/State.kt

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2020 JUUL Labs, Inc.
+ */
+
+package com.juul.able.keepalive
+
+sealed class State {
+
+    object Connecting : State()
+
+    object Connected : State()
+
+    object Disconnecting : State()
+
+    data class Disconnected(val cause: Throwable? = null) : State() {
+        override fun toString() = super.toString()
+    }
+
+    data class Cancelled(val cause: Throwable?) : State() {
+        override fun toString() = super.toString()
+    }
+
+    override fun toString(): String = javaClass.simpleName
+}