Restructure exception hierarchy

[twyatt]

You should design your own general-purpose Kotlin APIs in the same way: use exceptions for logic errors, type-safe results for everything else. Don’t use exceptions as a work-around to sneak a result value out of a function.¹

• IllegalStateException
• IOException [common]
  • GattException [common]
    • GattRequestRejectedException [android]
    • GattStatusException(status: GattStatus) [android]
    • GattWriteException(result: WriteResult) [android]
  • NotConnectedException [common]
  • UnmetRequirementException(reason: UnmetRequirementReason) [common]
    • BluetoothDisabled [common]
    • LocationManagerUnavailable [android]
    • ..
• InternalException [common]
  • OutOfOrderGattCallbackException [internal, android]

Exception	Purpose
IllegalStateException	(and sub-classes of) shall be thrown when an application state is statically not as expected (failure state won't exhibit a race condition). For example: "bluetooth not supported" (this state will not change), "missing required bluetooth permissions" (Android and iOS both kill app when de-escalating permissions — a developer can check permissions). When these exceptions are thrown, they are intended to crash the consuming app so that consumers are alerted of the logic error(s) and can address them accordingly.
IOException	"[..] not logic errors in code. They typically represent external conditions that the code has no control over but must deal with."2 IOExceptions are expected to be caught and handled accordingly (e.g. retried or inform user of steps to resolve the issue, such as enabling bluetooth).

Inspiration

kotlinx.serialization

• IllegalArgumentException
  • public open SerializationException
    • internal CborDecodingException
    • internal open JsonException
      • internal JsonDecodingException
      • internal JsonEncodingException
    • internal ProtobufDecodingException
    • internal UnknownFieldException
    • public MissingFieldException

kotlinx.coroutines

• IllegalStateException
  • public open CancellationException
    • internal AbortFlowException
    • internal ChildCancelledException
    • internal JobCancellationException
    • public TimeoutCancellationException
  • public ClosedSendChannelException
• NoSuchElementException
  • public ClosedReceiveChannelException
• RuntimeException
  • public CompletionHandlerException

Footnotes

1. https://elizarov.medium.com/kotlin-and-exceptions-8062f589d07#2273 ↩

2. https://elizarov.medium.com/kotlin-and-exceptions-8062f589d07#ef58 ↩