Change InternalException to InternalError (#801)

kable-core/api/android/kable-core.api

@@ -246,7 +246,7 @@ public final class com/juul/kable/IdentifierKt {
 	public static final fun toIdentifier (Ljava/lang/String;)Ljava/lang/String;
 }
 
-public final class com/juul/kable/InternalException : java/lang/IllegalStateException {
+public final class com/juul/kable/InternalError : java/lang/Error {
 }
 
 public final class com/juul/kable/Kable {

kable-core/api/jvm/kable-core.api

@@ -179,7 +179,7 @@ public final class com/juul/kable/IdentifierKt {
 	public static final fun toIdentifier (Ljava/lang/String;)Ljava/lang/String;
 }
 
-public final class com/juul/kable/InternalException : java/lang/IllegalStateException {
+public final class com/juul/kable/InternalError : java/lang/Error {
 }
 
 public final class com/juul/kable/LazyCharacteristic : com/juul/kable/Characteristic {

kable-core/src/androidMain/kotlin/Connection.kt

@@ -183,7 +183,7 @@ internal class Connection(
         // `guard` should always enforce a 1:1 matching of request-to-response, but if an Android
         // `BluetoothGattCallback` method is called out-of-order then we'll cast to the wrong type.
         return response as? T
-            ?: throw InternalException(
+            ?: throw InternalError(
                 "Expected response type ${type.simpleName} but received ${response::class.simpleName}",
             )
     }

kable-core/src/androidMain/kotlin/bluetooth/CheckBluetoothIsOn.kt

@@ -4,7 +4,7 @@ import android.bluetooth.BluetoothAdapter.STATE_OFF
 import android.bluetooth.BluetoothAdapter.STATE_ON
 import android.bluetooth.BluetoothAdapter.STATE_TURNING_OFF
 import android.bluetooth.BluetoothAdapter.STATE_TURNING_ON
-import com.juul.kable.InternalException
+import com.juul.kable.InternalError
 import com.juul.kable.UnmetRequirementException
 import com.juul.kable.UnmetRequirementReason.BluetoothDisabled
 import com.juul.kable.getBluetoothAdapter
@@ -29,5 +29,5 @@ private fun nameFor(state: Int) = when (state) {
     STATE_ON -> "STATE_ON"
     STATE_TURNING_OFF -> "STATE_TURNING_OFF"
     STATE_TURNING_ON -> "STATE_TURNING_ON"
-    else -> throw InternalException("Unsupported bluetooth state: $state")
+    else -> throw InternalError("Unsupported bluetooth state: $state")
 }

kable-core/src/androidMain/kotlin/scan/ScanError.kt

@@ -6,7 +6,7 @@ import android.bluetooth.le.ScanCallback.SCAN_FAILED_FEATURE_UNSUPPORTED
 import android.bluetooth.le.ScanCallback.SCAN_FAILED_INTERNAL_ERROR
 import android.bluetooth.le.ScanCallback.SCAN_FAILED_OUT_OF_HARDWARE_RESOURCES
 import android.bluetooth.le.ScanCallback.SCAN_FAILED_SCANNING_TOO_FREQUENTLY
-import com.juul.kable.InternalException
+import com.juul.kable.InternalError
 
 @JvmInline
 internal value class ScanError(internal val errorCode: Int) {
@@ -18,7 +18,7 @@ internal value class ScanError(internal val errorCode: Int) {
         SCAN_FAILED_FEATURE_UNSUPPORTED -> "SCAN_FAILED_FEATURE_UNSUPPORTED"
         SCAN_FAILED_OUT_OF_HARDWARE_RESOURCES -> "SCAN_FAILED_OUT_OF_HARDWARE_RESOURCES"
         SCAN_FAILED_SCANNING_TOO_FREQUENTLY -> "SCAN_FAILED_SCANNING_TOO_FREQUENTLY"
-        else -> throw InternalException("Unsupported error code $errorCode")
+        else -> throw InternalError("Unsupported error code $errorCode")
     }.let { name -> "$name($errorCode)" }
 }
 
@@ -43,5 +43,5 @@ internal val ScanError.message: String
         SCAN_FAILED_SCANNING_TOO_FREQUENTLY ->
             "Failed to start scan as application tries to scan too frequently"
 
-        else -> throw InternalException("Unsupported error code $errorCode")
+        else -> throw InternalError("Unsupported error code $errorCode")
     }

kable-core/src/appleMain/kotlin/Connection.kt

@@ -164,7 +164,7 @@ internal class Connection(
         // `guard` should always enforce a 1:1 matching of request-to-response, but if an Android
         // `BluetoothGattCallback` method is called out-of-order then we'll cast to the wrong type.
         return response as? T
-            ?: throw InternalException(
+            ?: throw InternalError(
                 "Expected response type ${type.simpleName} but received ${response::class.simpleName}",
             )
     }

kable-core/src/appleMain/kotlin/bluetooth/CheckBluetoothIsOn.kt

@@ -1,7 +1,7 @@
 package com.juul.kable.bluetooth
 
 import com.juul.kable.CentralManager
-import com.juul.kable.InternalException
+import com.juul.kable.InternalError
 import com.juul.kable.UnmetRequirementException
 import com.juul.kable.UnmetRequirementReason.BluetoothDisabled
 import platform.CoreBluetooth.CBManagerState
@@ -33,5 +33,5 @@ private fun nameFor(state: CBManagerState) = when (state) {
     CBManagerStateUnauthorized -> "Unauthorized"
     CBManagerStateUnknown -> "Unknown"
     CBManagerStateUnsupported -> "Unsupported"
-    else -> throw InternalException("Unsupported bluetooth state: $state")
+    else -> throw InternalError("Unsupported bluetooth state: $state")
 }

kable-core/src/commonMain/kotlin/InternalError.kt

@@ -0,0 +1,25 @@
+package com.juul.kable
+
+/**
+ * An [Error] that signifies that an unexpected condition or state was encountered in the Kable
+ * internals.
+ *
+ * May be thrown under the following (non-exhaustive) list of conditions:
+ * - A new system level feature was added but Kable does not yet properly support it
+ * - A programming error in Kable was encountered (e.g. a state when outside the designed bounds)
+ *
+ * Kable will likely be in an inconsistent state and will unlikely continue to function properly. It
+ * is recommended that the application be restarted (e.g. by not catching this exception and
+ * allowing the application to crash).
+ *
+ * If encountered, please report this exception (and provide logs) to:
+ * https://github.com/JuulLabs/kable/issues
+ */
+@Suppress("ktlint:standard:indent")
+public class InternalError internal constructor(
+    message: String,
+    cause: Throwable? = null,
+) : Error(
+    "$message, please report issue to https://github.com/JuulLabs/kable/issues and provide logs",
+    cause,
+)

kable-core/src/jsMain/kotlin/BluetoothDeviceWebBluetoothPeripheral.kt

@@ -160,7 +160,7 @@ internal class BluetoothDeviceWebBluetoothPeripheral(
                 continuation.resume(rssi)
             } else {
                 continuation.resumeWithException(
-                    InternalException("BluetoothAdvertisingEvent.rssi was null"),
+                    InternalError("BluetoothAdvertisingEvent.rssi was null"),
                 )
             }
         }

kable-core/src/jsMain/kotlin/BluetoothWebBluetoothScanner.kt

@@ -57,7 +57,7 @@ internal class BluetoothWebBluetoothScanner(
             throw IllegalStateException("Scanning not supported", e)
         } catch (e: JsError) {
             ensureActive()
-            throw InternalException("Failed to request scan", e)
+            throw InternalError("Failed to request scan", e)
         }
 
         logger.verbose { message = "Adding scan listener" }
@@ -95,7 +95,7 @@ internal class BluetoothWebBluetoothScanner(
                 detail("options", JSON.stringify(options))
                 message = e.toString()
             }
-            throw InternalException("Failed to start scan", e)
+            throw InternalError("Failed to start scan", e)
         }
 
         awaitClose {

kable-core/src/jsMain/kotlin/Connection.kt

@@ -91,7 +91,7 @@ internal class Connection(
         // we throw `InternalException`, as the Web Bluetooth Permission API spec is not stable, nor
         // is it utilized by Kable.
         // https://webbluetoothcg.github.io/web-bluetooth/#permission-api-integration
-        ?: throw InternalException("GATT server unavailable")
+        ?: throw InternalError("GATT server unavailable")
 
     private fun servicesOrThrow(): List<DiscoveredService> =
         discoveredServices.value ?: error("Services have not been discovered")
@@ -134,7 +134,7 @@ internal class Connection(
                 coroutineContext.ensureActive()
                 throw when (e) {
                     is DOMException -> IOException("Failed to start notification", e)
-                    else -> InternalException("Unexpected start notification failure", e)
+                    else -> InternalError("Unexpected start notification failure", e)
                 }
             }
         }
@@ -163,7 +163,7 @@ internal class Connection(
                         // No-op: System implicitly clears notifications on disconnect.
                     }
 
-                    else -> throw InternalException("Unexpected stop notification failure", e)
+                    else -> throw InternalError("Unexpected stop notification failure", e)
                 }
             } finally {
                 val listener = observationListeners.remove(platformCharacteristic) ?: return

kable-core/src/jsMain/kotlin/RequestPeripheral.kt

@@ -36,7 +36,7 @@ public suspend fun requestPeripheral(
         coroutineContext.ensureActive()
         throw when (e) {
             is TypeError -> IllegalStateException("Requesting a device is not supported", e)
-            else -> InternalException("Failed to invoke device request", e)
+            else -> InternalError("Failed to invoke device request", e)
         }
     }
 
@@ -70,10 +70,10 @@ public suspend fun requestPeripheral(
                     detail("processed", JSON.stringify(requestDeviceOptions))
                     message = e.toString()
                 }
-                throw InternalException("Type error when requesting device", e)
+                throw InternalError("Type error when requesting device", e)
             }
 
-            else -> throw InternalException("Failed to request device", e)
+            else -> throw InternalError("Failed to request device", e)
         }
     }?.let(builder::build)
 }

kable-core/src/jsMain/kotlin/bluetooth/IsSupported.kt

@@ -1,6 +1,6 @@
 package com.juul.kable.bluetooth
 
-import com.juul.kable.InternalException
+import com.juul.kable.InternalError
 import com.juul.kable.bluetoothOrNull
 import js.errors.JsError
 import js.errors.TypeError
@@ -17,6 +17,6 @@ internal actual suspend fun isSupported(): Boolean {
     return try {
         promise.await()
     } catch (e: JsError) {
-        throw InternalException("Failed to get bluetooth availability", e)
+        throw InternalError("Failed to get bluetooth availability", e)
     }
 }