Exception handling

[simplatek]

Hi, would you be able to provide sample code of how to go about handling exceptions from the stomp client such as MissingHeartBeatException or StompErrorFrameReceived ? Currently, these errors end up as Uncaught exceptions in my testing. I have not been able to catch them even if I use try catch within the launch coroutine. I need to be able to gracefully handle those errors if possible

launch { 
  try {
    stompClient.connect(url)
    // Any other stompClient suspend functions...
  } 
  catch(ex: Exception) {
    // Never see this being called upon exceptions such as MissingHeartBeatException or StompErrorFrameReceived 
  }
}

For instance, when the StompErrorFrameReceived is thrown during the consuming of the webSocketConnection.incomingFrames flow, I see the catch is being called, but then it calls close(), which is where the exception is being propagated and not caught.

suspend fun close(cause: Throwable? = null) {
        // If we are shutting down because of WebSocketClosedUnexpectedly, then we shouldn't try to close the web
        // socket again.
        // In case of STOMP ERROR frame, the server must close the connection.
        // However, the web socket did not error and we may need to close the output, so we don't discriminate
        // against StompErrorFrameReceived, and close anyway even in this case.
        if (cause !is WebSocketClosedUnexpectedly) {
            webSocketConnection.close(
                code = closeCodeFor(cause),
                reason = cause?.message?.truncateToCloseFrameReasonLength(),
            )
        }
        // this is reported even if the websocket was closed unexpectedly (it doesn't have to be us closing it)
        config.instrumentation?.onWebSocketClosed(cause)

        // Required to stop the subscribers of the frames, and propagate the exception if present.
        // We close this channel after the web socket, so that consumers can see they can't send UNSUBSCRIBE.
        stompFramesChannel.close(cause)

        // Cancels the collection of web socket frames.
        // Maybe this will happen before the web socket server's close frame is received, but it's OK because we
        // closed the stompFramesChannel already.
        scope.cancel(CancellationException(cause?.message, cause))
    }

[joffrey-bion]

Hi @simplatek, thanks a lot for asking.

All session-wide exceptions like this are propagated through subscription flows, so you can catch them in these flows using catch operator or a try/catch around the collect:

val client = StompClient()

launch {
    val session = client.connect()
    session.subscribeText("/destination")
        .catch { e -> TODO("handle exceptions here") }
        .collect { frameText -> 
            // do regular code with received frames here
        }
}

This is so that subscription sites can properly know about any hard failures that will stop the subscription abruptly.

If you want to handle these independently of subscriptions as well, there is no dedicated mechanism at the moment, but you can use the general instrumentation callbacks to do that:

val client = StompClient {
    instrumentation = object : KrossbowInstrumentation {
        override fun onWebSocketClosed(cause: Throwable?) {
            when(cause) {
                is MissingHeartBeatException -> TODO("handle connection drop")
                is StompErrorFrameReceived -> TODO("handle protocol error")
                null -> Unit // normal closure
                else -> Unit // no special handling for other exceptions (maybe log?)
            }
        }
    }
}

Note that the exceptions will be thrown nonetheless in the subscriptions (they will not be "caught" here).

What is the problem exactly? Would you want that the exceptions are not thrown on subscription collections?

In the context of automatic reconnection (see #102), subscriptions would not crash in case of MissingHeartBeatException because we instead want to reconnect when possible - and transparently for subscriptions.
Will that solve your problem?