From 3535d8397410cf2ee09b6a27300b8bbbdd4e1cb5 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Mon, 21 Jul 2025 16:29:32 +0200 Subject: [PATCH] Kotlin: Document websocket transport mode --- .../kotlin-multiplatform.mdx | 49 ++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/client-sdk-references/kotlin-multiplatform.mdx b/client-sdk-references/kotlin-multiplatform.mdx index d6a7beed..33453fe5 100644 --- a/client-sdk-references/kotlin-multiplatform.mdx +++ b/client-sdk-references/kotlin-multiplatform.mdx @@ -339,9 +339,56 @@ Logger.e("Some error"); See [Usage Examples](/client-sdk-references/kotlin-multiplatform/usage-examples) for further examples of the SDK. +## Developer Notes + +### Client implementation + +The PowerSync service sends encoded instructions about data to sync to connected clients. +These instructions are decoded by our SDKs, and on Kotlin there are two implementations available for this: + +1. **Kotlin (default)** + - This is the original implementation method, mostly implemented in Kotlin. + - Most upcoming features will not be ported to this implementation, and we intend to remove it eventually. +2. **Rust (currently experimental)** + - This is a newer implementation, mostly implemented in Rust but still using Kotlin for networking. + - Apart from newer features, this implementation is also more performant. + - We [encourage interested users to try it out](https://releases.powersync.com/announcements/improved-sync-performance-in-our-client-sdks) + and report feedback, as we intend to make it the default after a stabilization period. + +To enable the Rust client, pass `SyncOptions(newClientImplementation = true)` as a second parameter when +[connecting](https://powersync-ja.github.io/powersync-kotlin/core/com.powersync/-power-sync-database/connect.html). + +### Connection Methods + +This SDK supports two methods for streaming sync commands: + +1. **WebSocket (currently experimental)** + - The implementation leverages RSocket for handling reactive socket streams. + - Back-pressure is effectively managed through client-controlled command requests. + - Sync commands are transmitted efficiently as BSON (binary) documents. + - Enabling websocket support requires the new client implementation. +2. **HTTP Streaming (default)** + - This is the original implementation method. + - This method sends data as text (JSON) instead of BSON. + +By default, the `PowerSyncDatabase.connect()` method uses HTTP streams. +You can optionally specify the `connectionMethod` to override this: + +```Kotlin +// HTTP streaming (default) +powerSync.connect(connector) + +// WebSockets (experimental) +powerSync.connect(connector, SyncOptions( + newClientImplementation = true, + method = ConnectionMethod.WebSocket(), +)) +``` + ## ORM Support -ORM support is not yet available, we are still investigating options. Please [let us know](/resources/contact-us) what your needs around ORMs are. +ORM support is not yet available, we are still investigating options to integrate the SDK with Room and SQLDelight. +Please [let us know](/resources/contact-us) what your needs around ORMs are. ## Troubleshooting