Add multiplexing and sync timeout options

examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/AppClientTest.kt

@@ -15,6 +15,10 @@ import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertFailsWith
 import kotlin.test.assertTrue
+import kotlin.time.Duration.Companion.minutes
+import kotlin.time.Duration.Companion.seconds
+
+
 
 class AppClientTest: RealmTest() {
     @Test
@@ -34,18 +38,61 @@ class AppClientTest: RealmTest() {
         val config =
         // :snippet-start: configure-app-client
             // Creates an App with custom configuration values
-            AppConfiguration.Builder(YOUR_APP_ID) // Replace with your App ID
+            AppConfiguration.Builder(YOUR_APP_ID)
                 // Specify your custom configuration values
                 .appName("my-app-name")
                 .appVersion("1.0.0")
                 .baseUrl("http://localhost:9090")
                 .build()
         // :snippet-end:
+        println(config.enableSessionMultiplexing)
         assertEquals(config.appName, "my-app-name")
         assertEquals(config.baseUrl, "http://localhost:9090")
         assertEquals(config.appVersion, "1.0.0")
     }
 
+    @Test
+    fun multiplexingTest() {
+        // :snippet-start: enable-multiplexing
+        val config = AppConfiguration.Builder(YOUR_APP_ID)
+            .enableSessionMultiplexing(true)
+            .build()
+        // :snippet-end:
+        assertTrue(config.enableSessionMultiplexing)
+        // :snippet-start: enable-multiplexing-with-timeout
+        val configCustomLingerTime = AppConfiguration.Builder(YOUR_APP_ID)
+            .enableSessionMultiplexing(true)
+            .syncTimeouts {
+                connectionLingerTime = 10.seconds // Overrides default 30 secs
+            }
+            .build()
+        // :snippet-end:
+        assertTrue(configCustomLingerTime.enableSessionMultiplexing)
+        assertEquals(configCustomLingerTime.syncTimeoutOptions.connectionLingerTime.inWholeSeconds, 30)
+    }
+
+    @Test
+    fun syncTimeoutTest() {
+        // :snippet-start: sync-timeout-configuration
+        val config = AppConfiguration.Builder(YOUR_APP_ID)
+            .syncTimeouts {
+                connectTimeout = 1.minutes
+                connectionLingerTime = 15.seconds
+                pingKeepalivePeriod = 30.seconds
+                pongKeepalivePeriod = 1.minutes
+                fastReconnectLimit = 30.seconds
+            }
+            .build()
+        // :snippet-end:
+        with(config.syncTimeoutOptions) {
+            assertEquals(1.minutes, connectTimeout)
+            assertEquals(15.seconds, connectionLingerTime)
+            assertEquals(30.seconds, pingKeepalivePeriod)
+            assertEquals(1.minutes, pongKeepalivePeriod)
+            assertEquals(30.seconds, fastReconnectLimit)
+        }
+    }
+
     @Test
     fun encryptAppMetadata() {
         val myEncryptionKey = getEncryptionKey()

source/examples/generated/kotlin/AppClientTest.snippet.configure-app-client.kt

@@ -1,5 +1,5 @@
 // Creates an App with custom configuration values
-AppConfiguration.Builder(YOUR_APP_ID) // Replace with your App ID
+AppConfiguration.Builder(YOUR_APP_ID)
     // Specify your custom configuration values
     .appName("my-app-name")
     .appVersion("1.0.0")

source/examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing-with-timeout.kt

@@ -0,0 +1,6 @@
+val configCustomLingerTime = AppConfiguration.Builder(YOUR_APP_ID)
+    .enableSessionMultiplexing(true)
+    .syncTimeouts {
+        connectionLingerTime = 10.seconds // Overrides default 30 secs
+    }
+    .build()

source/examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing.kt

@@ -0,0 +1,3 @@
+val config = AppConfiguration.Builder(YOUR_APP_ID)
+    .enableSessionMultiplexing(true)
+    .build()

source/examples/generated/kotlin/AppClientTest.snippet.sync-timeout-configuration.kt

@@ -0,0 +1,9 @@
+val config = AppConfiguration.Builder(YOUR_APP_ID)
+    .syncTimeouts {
+        connectTimeout = 1.minutes
+        connectionLingerTime = 15.seconds
+        pingKeepalivePeriod = 30.seconds
+        pongKeepalivePeriod = 1.minutes
+        fastReconnectLimit = 30.seconds
+    }
+    .build()

source/examples/generated/kotlin/Serialization.snippet.call-function-experimental-serializer.kt

@@ -2,5 +2,3 @@
 val address = user.functions.call<Address>("getMailingAddressForPerson"){
     add(Person("Bob", "Smith"))
 }
-
-assertEquals(address.street, "123 Any Street")

source/examples/generated/kotlin/Serialization.snippet.call-function-stable-serializer.kt

@@ -1,4 +1,2 @@
 // The `getMailingAddress` function takes a first name and last name and returns an address as a BsonDocument
 val address = user.functions.call<BsonDocument>("getMailingAddress", "Bob", "Smith")
-
-assertEquals(address["street"], BsonString("123 Any Street"))

source/examples/generated/kotlin/Serialization.snippet.define-serializable-class.kt

@@ -1,6 +1,8 @@
 @Serializable
 class Address(
-    val street: String,
+    // The `street` field in the Atlas document is a string,
+    // but is coming back as an `Int` since upgrading to realm-kotlin 1.13.0
+    val street: Int,
     val city: String,
     val state: String,
     val country: String,

source/sdk/kotlin/app-services/connect-to-app-services-backend.txt

@@ -4,6 +4,14 @@
 Connect to Atlas App Services - Kotlin SDK
 ==========================================
 
+.. meta::
+   :keywords: code example
+   :description: Initialize your app client and connect to the Atlas App Services backend using the Kotlin SDK. 
+
+.. facet::
+  :name: genre
+  :values: tutorial
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -72,6 +80,76 @@ and call the ``.build()`` method to pass a configuration object:
 
 .. include:: /includes/multiple-app-client-details-and-app-config-cache.rst
 
+Share Sync Connections
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: Applies to Atlas Device Sync
+
+   This configuration option applies to apps using Device Sync. 
+   For more information on using Device Sync with 
+   the Kotlin SDK, refer to :ref:`<kotlin-sync>`.
+
+.. versionadded:: 1.13.0
+
+By default, the SDK opens a separate connection to the server for 
+each synced realm. In Kotlin v1.13.0 and later, you can enable
+**session multiplexing**. When enabled, the SDK 
+shares a connection to the server for all synced realms opened with 
+a single App Services user. Sharing a connection across multiple 
+sessions reduces resources and can improve performance. 
+
+Multiplexing is disabled by default. You can enable it on the 
+``AppConfiguration`` using the `.enableSessionMultiplexing() 
+<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb/-app-configuration/-builder/index.html#-839865185%2FFunctions%2F380376748>`__ 
+method, which accepts a Boolean value. 
+
+.. literalinclude:: /examples/generated/kotlin/AppClientTest.snippet.enable-session-multiplexing.kt
+   :language: kotlin
+
+When all sessions are closed, the shared connection does not immediately close.
+Instead, it remains open for the ``connectionLingerTime``, which defaults to 
+30 seconds. You can override this duration by passing a new value to 
+`SyncTimeoutOptions.connectionLingerTime() 
+<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.sync/-sync-timeout-options/connection-linger-time.html>`__ 
+on the ``AppConfiguration``. 
+
+.. literalinclude:: /examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing-with-timeout.kt
+   :language: kotlin
+
+For more information, refer to the 
+:ref:`kotlin-configure-sync-timeouts` section on this page.
+
+.. _kotlin-configure-sync-timeouts:
+
+Configure Sync Timeouts
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: Applies to Atlas Device Sync
+
+   This configuration option applies to apps using Device Sync. 
+   For more information on using Device Sync with 
+   the Kotlin SDK, refer to :ref:`<kotlin-sync>`.
+
+.. versionadded:: 1.13.0
+
+In Kotlin v1.13.0 and later, you can override the default 
+timeout settings used when syncing data between the Atlas backend 
+and the client app.
+
+You can set various sync timeout settings on the 
+``AppConfiguration`` using the `.syncTimeouts()
+<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb/-app-configuration/-builder/index.html#90306255%2FFunctions%2F380376748>`__ 
+method. Pass specific timeout property values you want to override. The 
+configured timeouts apply to all sync sessions in the app.
+
+.. literalinclude:: /examples/generated/kotlin/AppClientTest.snippet.sync-timeout-configuration.kt
+   :language: kotlin
+
+For a complete list of the available timeout properties and their 
+definitions, refer to the
+`SyncTimeoutOptionsBuilder <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.sync/-sync-timeout-options-builder/index.html>`__ 
+API reference.
+
 .. _kotlin-encrypt-app-metadata:
 
 Encrypt App Metadata 

source/sdk/kotlin/sync/open-a-synced-realm.txt

@@ -4,12 +4,24 @@
 Configure & Open a Synced Realm - Kotlin SDK
 ============================================
 
+.. meta::
+   :keywords: code example
+   :description: Configure and open a synced database for apps using Atlas Device Sync. 
+
+.. facet::
+  :name: genre
+  :values: tutorial
+
 .. contents:: On this page
    :local:
    :backlinks: none
    :depth: 2
    :class: singlecol
 
+This page describes how to open a synced database--and the various 
+configuration options available-- your App client and connect to the Atlas 
+App Services backend using the Kotlin SDK.
+
 Prerequisites
 -------------
 
@@ -39,7 +51,6 @@ an instance of the realm:
 
 .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.open-a-flexible-sync-realm.kt
    :language: kotlin
-   :copyable: false
 
 For more information on bootstrapping the realm with initial subscriptions
 and managing your synced realm subscriptions, 
@@ -56,7 +67,14 @@ To adjust specific configuration settings, use the options provided by
 
 .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.configure-a-flexible-sync-realm.kt
    :language: kotlin
-   :copyable: false
+
+.. versionadded:: 1.13.0
+   Sync timeout configuration options added
+
+In Kotlin v1.13.0, you can override various default timeouts used for sync 
+operations. You can set these timeouts in the ``App`` client 
+configuration, and they apply to all sync sessions in the app. 
+To learn how, refer to :ref:`<kotlin-configure-sync-timeouts>`.
 
 .. _kotlin-download-changes-before-open: