joffrey-bion/krossbow

A Kotlin multiplatform coroutine-based STOMP client over websockets, with built-in conversions.

Krossbow

See the project's website for documentation.

Krossbow is a Kotlin multiplatform STOMP 1.2 client with a coroutine-based API. It provides a bunch of adapters for popular web socket clients (OkHttp, Ktor, Spring, SockJS...), as well as a 0-dependency built-in web socket implementation for some platforms.

License

This project is published under the MIT license.

krossbow's Issues

Make build fail if using Android-incompatible JVM APIs/deps

Based on this slack conversation, there should be a way to define an Android target (making use of the Android toolchain) in the build, so that using incompatible JVM dependencies or APIs fails the build.

An attempt lives here: 5f27a77

But it requires actually installing the android toolchain locally and in the CI, and may not be worth it for now until people upvote this issue.

Support for STOMP frame instead of CONNECT

Add basic connect/send/subscribe features for JS

Consider using ReceiveChannel for subscriptions

This would make code simpler on the consumer side.
Subscriptions could be canceled (unsubscribed from) using ReceiveChannel.cancel(), and iterations could natively be done without calling sub.messages.

Publish krossbow-engine-webstompjs artifact on Jcenter

Allow null payloads in send()

Improve error handling

The web socket listener should never throw an exception, because we don't control who calls it (it's up to the underlying web socket implementation).

Instead, all sorts of errors triggered in the listener should end up in the execution flow of the STOMP session's user. This means failing the subscriptions channels and the pending calls to send().

JavaScript WebSocket adapter doesn't fail the connection with onclose

When calling connect() on the websocket, the server may close the connection instead of using onerror, so we need to handle connection failure through onclose as well.

Publish Maven artifacts on Jcenter

Upgrade Jackson to version 2.10.0

Ambiguous send() overload for no-payload calls

Add JDK11 async WebSocket bridge

https://docs.oracle.com/en/java/javase/13/docs/api/java.net.http/java/net/http/WebSocket.Builder.html

Make connect() function actually non-blocking by avoiding get()

Add support for websocket frame splitting in common code

Currently, only the JDK11 adapter supports it, it should be moved to common code to use it or other web socket impementations that could return frames in multiple parts.

Allow subscriptions for arbitrary/bytes/string payload

Allow null payloads for Unit type subscriptions

Extract Jackson and Kotlinx Serialization as separate artifacts

Users that need only one of them (or none at all) shouldn't be forced to pull the transitive dependencies of Jackson and KxSerialization.

Add support for heart beats

Make autoReceipt and receipt timeout configurable

Allow custom WS client/transports in SpringKrossbowEngine

Change default WebSocket impl on JVM to JDK 11 async client

This is to limit external dependencies on Spring.
On JVM11, this means no dependency at all.

JDK8 users will just have to specify manually the Spring dependency and declare their own default client.

Allow subscriptions for empty payloads

Expose Kotlinx.Serialization dependency

This is required for people to be able to use the kotlinx.serialization message converter.

LostReceiptException thrown on external timeout

Using withTimeout to wrap calls to the StompSession should be supported.

val client = StompClient {
    receiptTimeoutMillis = 10000
}
val stompSession = client.connect("ws://localhost:8000")
withTimeout(600) {
    stompSession.sendText("/dest", "message")
}

This timeout crashes with LostReceiptException while it should be TimeoutCancellationException. This is a user-generated timeout and should behave as a normal timeout with the regular exception.

Fix: use withTimeoutOrNull internally instead of catching the TimeoutCancellationException.

JS version not working

The tests have always been broken in JS but previous versions of the Kotlin plugin didn't show that. Now the tests are properly broken using Kotlin 1.3.60, and they need to be fixed.

autoReceipt and receiptTimeLimit are not editable

Receiving EOL (heart beat) crashes STOMP decoder

EOL is the standard heart beat when no particular data needs to be sent.
It needs to be supported, and it shouldn't be decoded as a STOMP frame.

Inline subscribe() method not properly declared

Mixed extension declaration and standard method declaration.

Rework WebSocket API to use a channel instead of a listener

Broken Dokka generation for JS

This looks like a bug in Dokka, and is tracked here: Kotlin/dokka#537

Artifacts not uploaded to Maven Central

Rename krossbow-websocket-api to krossbow-websocket-core

This module contains basic implementations of the websocket API (in addition to the API itself).
Therefore, it cannot really be designated as "API".

Implement pure Kotlin STOMP protocol in common code

It would be better to completely implement the STOMP protocol in common code, using only the WebSocket engine as platform-dependent dependency.

Add support for ACK/NACK frames

Publish artifacts to Maven Central

ClassCastException in Javascript websocket onclose

Due to the event type not being an actual CloseEvent Kotlin object, we cannot use a regular checked cast with as. We need to use unsafeCast instead.

Heart beats create deadlock

If only one side of the heart-beating is activated, the STOMP session deadlocks.

Receiving EOL (heart beat) crashes STOMP decoder

The Stomp session processes every web socket frame as a STOMP frame.
This crashes the STOMP decoder when using heart beats because they may be simple EOL characters instead of actual STOMP frames:

The sender MUST send new data over the network connection at least every n milliseconds.
If the sender has no real STOMP frame to send, it MUST send an end-of-line (EOL).

https://stomp.github.io/stomp-specification-1.2.html#Heart-beating

Add tests using online server

Add basic connect/send/subscribe features for JVM

Unify automated tests for all Web Socket adapters

We would either need to implement a test server on every platform (unlikely to be possible in the browser environment), or spawn a server next to the build in order to run the tests, but that would be pretty annoying.

Absent payloads API is not public

Add support for transaction frames (BEGIN/COMMIT/ABORT)

Add support for custom headers

Race condition issues with Jdk11 partial frames

Add OkHttp websocket adapter

This will probably allow to target java 6 and thus allow usage on Android.

Make send() function actually suspend until RECEIPT is received

Create test server on-the-fly instead of requiring an internet connexion

Check compiler warnings for Opt-in (Experimental)

These warnings are annoying and don't seem to be removed by giving the compiler flags to Gradle

Upgrade Kotlinx.serialization to version 0.20.0