[RKOTLIN-612] MongoClient API

.github/actions/run-android-device-farm-test/action.yml

@@ -41,6 +41,7 @@ runs:
         test_spec_file: test_spec-${{ inputs.app-id }}.yaml
         test_spec_type: APPIUM_PYTHON_TEST_SPEC
         remote_src: true
+        timeout: 3600
         test_spec: |
           version: 0.1
           phases:

CHANGELOG.md

@@ -16,7 +16,8 @@ This release will bump the Realm file format from version 23 to 24. Opening a fi
 * Index on list of strings property now supported (Core issue [realm/realm-core#7142](https://github.com/realm/realm-core/pull/7142))
 * Improved performance of RQL (parsed) queries on a non-linked string property using: >, >=, <, <=, operators and fixed behaviour that a null string should be evaulated as less than everything, previously nulls were not matched. (Core issue [realm/realm-core#3939](https://github.com/realm/realm-core/issues/3939).
 * Updated bundled OpenSSL version to 3.2.0 (Core issue [realm/realm-core#7303](https://github.com/realm/realm-core/pull/7303))
-* The default base url in `AppConfiguration` has been updated to point to `services.cloud.mongodb.com`. See https://www.mongodb.com/docs/atlas/app-services/domain-migration/ for more information. (Issue [#1685](https://github.com/realm/realm-kotlin/issues/1685))
+* [Sync] The default base url in `AppConfiguration` has been updated to point to `services.cloud.mongodb.com`. See https://www.mongodb.com/docs/atlas/app-services/domain-migration/ for more information. (Issue [#1685](https://github.com/realm/realm-kotlin/issues/1685))
+* [Sync] Add Mongo Client API to access Atlas App Service collections. It can be accessed through `User.mongoClient`. (Issue [#972](https://github.com/realm/realm-kotlin/issues/972))
 
 ### Fixed
 * Sorting order of strings has changed to use standard unicode codepoint order instead of grouping similar english letters together. A noticeable change will be from "aAbBzZ" to "ABZabz". (Core issue [realm/realm-core#2573](https://github.com/realm/realm-core/issues/2573))
@@ -121,9 +122,9 @@ This release will bump the Realm file format from version 23 to 24. Opening a fi
 * None.
 
 ### Enhancements
-* [Sync] Added option to use managed WebSockets via OkHttp instead of Realm's built-in WebSocket client for Sync traffic (Only Android and JVM targets for now). Managed WebSockets offer improved support for proxies and firewalls that require authentication. This feature is currently opt-in and can be enabled by using `AppConfiguration.usePlatformNetworking()`. Managed WebSockets will become the default in a future version. (PR [#1528](https://github.com/realm/realm-kotlin/pull/1528)).
-* `AutoClientResetFailed` exception now reports as the throwable cause any user exceptions that might occur during a client reset. (Issue [#1580](https://github.com/realm/realm-kotlin/issues/1580))
 * The Unpacking of JVM native library will use the current library version instead of a calculated hash for the path. (Issue [#1617](https://github.com/realm/realm-kotlin/issues/1617)).
+* [Sync] Added option to use managed WebSockets via OkHttp instead of Realm's built-in WebSocket client for Sync traffic (Only Android and JVM targets for now). Managed WebSockets offer improved support for proxies and firewalls that require authentication. This feature is currently opt-in and can be enabled by using `AppConfiguration.usePlatformNetworking()`. Managed WebSockets will become the default in a future version. (PR [#1528](https://github.com/realm/realm-kotlin/pull/1528)).
+* [Sync] `AutoClientResetFailed` exception now reports as the throwable cause any user exceptions that might occur during a client reset. (Issue [#1580](https://github.com/realm/realm-kotlin/issues/1580))
 
 ### Fixed
 * Cache notification callback JNI references at startup to ensure that symbols can be resolved in core callbacks. (Issue [#1577](https://github.com/realm/realm-kotlin/issues/1577))

buildSrc/src/main/kotlin/Config.kt

@@ -121,7 +121,7 @@ object Versions {
     const val jmh = "1.34" // https://github.com/openjdk/jmh
     const val jmhPlugin = "0.6.6" // https://github.com/melix/jmh-gradle-plugin
     const val junit = "4.13.2" // https://mvnrepository.com/artifact/junit/junit
-    const val kbson = "0.3.0" // https://github.com/mongodb/kbson
+    const val kbson = "0.4.0" // https://github.com/mongodb/kbson
     // When updating the Kotlin version, also remember to update /examples/min-android-sample/build.gradle.kts
     const val kotlin = "1.9.0" // https://github.com/JetBrains/kotlin and https://kotlinlang.org/docs/releases.html#release-details
     const val kotlinJvmTarget = "1.8" // Which JVM bytecode version is kotlin compiled to.

packages/cinterop/src/commonMain/kotlin/io/realm/kotlin/internal/interop/RealmInterop.kt

@@ -732,6 +732,7 @@ expect object RealmInterop {
         app: RealmAppPointer,
         user: RealmUserPointer,
         name: String,
+        serviceName: String? = null,
         serializedEjsonArgs: String, // as ejson
         callback: AppCallback<String>
     )

packages/cinterop/src/jvm/kotlin/io/realm/kotlin/internal/interop/RealmInterop.kt

@@ -1628,14 +1628,16 @@ actual object RealmInterop {
         )
     }
 
+    @Suppress("LongParameterList")
     actual fun realm_app_call_function(
         app: RealmAppPointer,
         user: RealmUserPointer,
         name: String,
+        serviceName: String?,
         serializedEjsonArgs: String,
         callback: AppCallback<String>
     ) {
-        realmc.realm_app_call_function(app.cptr(), user.cptr(), name, serializedEjsonArgs, null, callback)
+        realmc.realm_app_call_function(app.cptr(), user.cptr(), name, serializedEjsonArgs, serviceName, callback)
     }
 
     actual fun realm_app_call_reset_password_function(

packages/cinterop/src/nativeDarwin/kotlin/io/realm/kotlin/internal/interop/RealmInterop.kt

@@ -3151,6 +3151,7 @@ actual object RealmInterop {
         app: RealmAppPointer,
         user: RealmUserPointer,
         name: String,
+        serviceName: String?,
         serializedEjsonArgs: String,
         callback: AppCallback<String>
     ) {
@@ -3159,7 +3160,7 @@ actual object RealmInterop {
             user.cptr(),
             name,
             serializedEjsonArgs,
-            null,
+            serviceName,
             staticCFunction { userData: CPointer<out CPointed>?, data: CPointer<ByteVarOf<Byte>>?, error: CPointer<realm_app_error_t>? ->
                 handleAppCallback(userData, error) {
                     data.safeKString()

packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/RealmInstantImpl.kt

@@ -36,7 +36,7 @@ public fun RealmInstant.toDuration(): Duration {
     return epochSeconds.seconds + nanosecondsOfSecond.nanoseconds
 }
 
-internal fun Duration.toRealmInstant(): RealmInstant {
+public fun Duration.toRealmInstant(): RealmInstant {
     val seconds: Long = this.inWholeSeconds
     val nanos: Duration = (this - seconds.seconds)
     return RealmInstant.from(seconds, nanos.inWholeNanoseconds.toInt())
@@ -45,4 +45,5 @@ internal fun Duration.toRealmInstant(): RealmInstant {
 internal fun RealmInstant.restrictToMillisPrecision() =
     toDuration().inWholeMilliseconds.milliseconds.toRealmInstant()
 
-internal fun RealmInstant.asBsonDateTime() = BsonDateTime(toDuration().inWholeMilliseconds)
+public inline fun RealmInstant.asBsonDateTime(): BsonDateTime = BsonDateTime(toDuration().inWholeMilliseconds)
+public inline fun BsonDateTime.asRealmInstant(): RealmInstant = value.milliseconds.toRealmInstant()

packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/RealmObjectCompanion.kt

@@ -30,7 +30,7 @@ import kotlin.reflect.KProperty1
 public interface RealmObjectCompanion {
     public val `io_realm_kotlin_class`: KClass<out TypedRealmObject>
     public val `io_realm_kotlin_className`: String
-    public val `io_realm_kotlin_fields`: Map<String, KProperty1<BaseRealmObject, Any?>>
+    public val `io_realm_kotlin_fields`: Map<String, Pair<KClass<*>, KProperty1<BaseRealmObject, Any?>>>
     public val `io_realm_kotlin_primaryKey`: KMutableProperty1<*, *>?
     public val `io_realm_kotlin_classKind`: RealmClassKind
     public fun `io_realm_kotlin_schema`(): RealmClassImpl

packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/RealmObjectUtil.kt

@@ -106,14 +106,14 @@ internal fun <T : BaseRealmObject> RealmObjectReference<T>.toRealmObject(): T =
 /**
  * Returns the [RealmObjectCompanion] associated with a given [BaseRealmObject]'s [KClass].
  */
-internal inline fun KClass<*>.realmObjectCompanionOrNull(): RealmObjectCompanion? {
+public inline fun KClass<*>.realmObjectCompanionOrNull(): RealmObjectCompanion? {
     return realmObjectCompanionOrNull(this)
 }
 
 /**
  * Returns the [RealmObjectCompanion] associated with a given [BaseRealmObject]'s [KClass].
  */
-internal inline fun <reified T : BaseRealmObject> KClass<T>.realmObjectCompanionOrThrow(): RealmObjectCompanion {
+public inline fun <reified T : BaseRealmObject> KClass<T>.realmObjectCompanionOrThrow(): RealmObjectCompanion {
     return realmObjectCompanionOrThrow(this)
 }
 

packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/RealmUUIDImpl.kt

@@ -21,6 +21,8 @@ import io.realm.kotlin.internal.util.HEX_PATTERN
 import io.realm.kotlin.internal.util.parseHex
 import io.realm.kotlin.internal.util.toHexString
 import io.realm.kotlin.types.RealmUUID
+import org.mongodb.kbson.BsonBinary
+import org.mongodb.kbson.BsonBinarySubType
 import kotlin.experimental.and
 import kotlin.experimental.or
 
@@ -101,3 +103,6 @@ public class RealmUUIDImpl : RealmUUID {
         }
     }
 }
+
+public inline fun RealmUUID.asBsonBinary(): BsonBinary = BsonBinary(BsonBinarySubType.UUID_STANDARD, bytes)
+public inline fun BsonBinary.asRealmUUID(): RealmUUID = RealmUUID.from(data)

packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/platform/RealmObject.kt

@@ -25,9 +25,9 @@ import kotlin.reflect.KClass
  * associated [RealmObjectCompanion], in which case the `clazz` wasn't a user defined class
  * implementing [BaseRealmObject] augmented by our compiler plugin.
  */
-internal expect fun <T : Any> realmObjectCompanionOrNull(clazz: KClass<T>): RealmObjectCompanion?
+public expect fun <T : Any> realmObjectCompanionOrNull(clazz: KClass<T>): RealmObjectCompanion?
 
 /**
  * Returns the [RealmObjectCompanion] associated with a given [BaseRealmObject]'s [KClass].
  */
-internal expect fun <T : BaseRealmObject> realmObjectCompanionOrThrow(clazz: KClass<T>): RealmObjectCompanion
+public expect fun <T : BaseRealmObject> realmObjectCompanionOrThrow(clazz: KClass<T>): RealmObjectCompanion

packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/schema/CachedClassKeyMap.kt

@@ -147,7 +147,7 @@ public class CachedClassMetadata(
             properties = interopProperties.map { propertyInfo: PropertyInfo ->
                 CachedPropertyMetadata(
                     propertyInfo,
-                    companion?.io_realm_kotlin_fields?.get(propertyInfo.name)
+                    companion?.io_realm_kotlin_fields?.get(propertyInfo.name)?.second
                 )
             }
         }

packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/util/Validation.kt

@@ -38,7 +38,7 @@ public object Validation {
      * to that type, otherwise an IllegalArgumentException is thrown with the provided error message.
      */
     @OptIn(ExperimentalContracts::class)
-    public inline fun <reified T : Any?> isType(arg: Any?, errorMessage: String) {
+    public inline fun <reified T : Any?> isType(arg: Any?, errorMessage: String = "Object '$arg' is not of type ${T::class.qualifiedName}") {
         contract {
             returns() implies (arg is T)
         }

packages/library-base/src/commonMain/kotlin/io/realm/kotlin/serializers/RealmKSerializers.kt

@@ -19,8 +19,8 @@ import io.realm.kotlin.ext.asRealmObject
 import io.realm.kotlin.ext.toRealmDictionary
 import io.realm.kotlin.ext.toRealmList
 import io.realm.kotlin.ext.toRealmSet
-import io.realm.kotlin.internal.toDuration
-import io.realm.kotlin.internal.toRealmInstant
+import io.realm.kotlin.internal.asBsonDateTime
+import io.realm.kotlin.internal.asRealmInstant
 import io.realm.kotlin.types.MutableRealmInt
 import io.realm.kotlin.types.RealmAny
 import io.realm.kotlin.types.RealmAny.Type
@@ -45,7 +45,6 @@ import org.mongodb.kbson.BsonBinarySubType
 import org.mongodb.kbson.BsonDateTime
 import org.mongodb.kbson.BsonObjectId
 import org.mongodb.kbson.Decimal128
-import kotlin.time.Duration.Companion.milliseconds
 
 /**
  * KSerializer implementation for [RealmList]. Serialization is done as a generic list structure,
@@ -249,12 +248,12 @@ public object RealmInstantKSerializer : KSerializer<RealmInstant> {
     override val descriptor: SerialDescriptor = serializer.descriptor
 
     override fun deserialize(decoder: Decoder): RealmInstant =
-        decoder.decodeSerializableValue(serializer).value.milliseconds.toRealmInstant()
+        decoder.decodeSerializableValue(serializer).asRealmInstant()
 
     override fun serialize(encoder: Encoder, value: RealmInstant) {
         encoder.encodeSerializableValue(
             serializer = serializer,
-            value = BsonDateTime(value.toDuration().inWholeMilliseconds)
+            value = value.asBsonDateTime()
         )
     }
 }

packages/library-base/src/jvm/kotlin/io/realm/kotlin/internal/platform/RealmObject.kt

@@ -23,11 +23,11 @@ import kotlin.reflect.full.companionObjectInstance
 
 // TODO OPTIMIZE Can we eliminate the reflective approach? Maybe by embedding the information
 //  through the compiler plugin or something similar to the Native findAssociatedObject
-internal actual fun <T : Any> realmObjectCompanionOrNull(clazz: KClass<T>): RealmObjectCompanion? =
+public actual fun <T : Any> realmObjectCompanionOrNull(clazz: KClass<T>): RealmObjectCompanion? =
     if (clazz.companionObjectInstance is RealmObjectCompanion) {
         clazz.companionObjectInstance as RealmObjectCompanion
     } else null
 
-internal actual fun <T : BaseRealmObject> realmObjectCompanionOrThrow(clazz: KClass<T>): RealmObjectCompanion =
+public actual fun <T : BaseRealmObject> realmObjectCompanionOrThrow(clazz: KClass<T>): RealmObjectCompanion =
     realmObjectCompanionOrNull(clazz)
         ?: error("Couldn't find companion object of class '${clazz.simpleName}'.\nA common cause for this is when the `io.realm.kotlin` is not applied to the Gradle module that contains the '${clazz.simpleName}' class.")

packages/library-base/src/nativeDarwin/kotlin/io/realm/kotlin/internal/platform/RealmObject.kt

@@ -22,13 +22,13 @@ import kotlin.reflect.ExperimentalAssociatedObjects
 import kotlin.reflect.KClass
 import kotlin.reflect.findAssociatedObject
 
-internal actual fun <T : Any> realmObjectCompanionOrNull(clazz: KClass<T>): RealmObjectCompanion? =
+public actual fun <T : Any> realmObjectCompanionOrNull(clazz: KClass<T>): RealmObjectCompanion? =
     @OptIn(ExperimentalAssociatedObjects::class)
     when (val associatedObject = clazz.findAssociatedObject<ModelObject>()) {
         is RealmObjectCompanion -> associatedObject
         else -> null
     }
 
-internal actual fun <T : BaseRealmObject> realmObjectCompanionOrThrow(clazz: KClass<T>): RealmObjectCompanion =
+public actual fun <T : BaseRealmObject> realmObjectCompanionOrThrow(clazz: KClass<T>): RealmObjectCompanion =
     realmObjectCompanionOrNull(clazz)
         ?: error("Couldn't find companion object of class '${clazz.simpleName}'.\nA common cause for this is when the `io.realm.kotlin` is not applied to the Gradle module that contains the '${clazz.simpleName}' class.")

packages/library-sync/src/commonMain/kotlin/io/realm/kotlin/mongodb/User.kt

@@ -20,7 +20,10 @@ import io.realm.kotlin.mongodb.auth.ApiKeyAuth
 import io.realm.kotlin.mongodb.exceptions.AppException
 import io.realm.kotlin.mongodb.ext.customDataAsBsonDocument
 import io.realm.kotlin.mongodb.ext.profileAsBsonDocument
+import io.realm.kotlin.mongodb.mongo.MongoClient
 import io.realm.kotlin.mongodb.sync.SyncConfiguration
+import org.mongodb.kbson.ExperimentalKBsonSerializerApi
+import org.mongodb.kbson.serialization.EJson
 
 /**
  * A **user** holds the user's metadata and tokens for accessing App Services and Device Sync
@@ -201,6 +204,25 @@ public interface User {
      */
     public suspend fun linkCredentials(credentials: Credentials): User
 
+    /**
+     * Get a [MongoClient] for accessing documents from App Service's _Data Source_.
+     *
+     * Serialization to and from EJSON is performed with [KBSON](https://github.com/mongodb/kbson)
+     * that supports the [Kotlin Serialization framework](https://github.com/Kotlin/kotlinx.serialization)
+     * and handles serialization to and from classes marked with [Serializable]. Serialization of
+     * realm objects and links have some caveats and requires special configuration. For full
+     * details see [MongoClient].
+     *
+     * @param serviceName the name of the data service.
+     * @param eJson the EJson serializer that the [MongoClient] should use to convert objects and
+     * primary keys with. Will default to the apps [EJson] instance configured with
+     * [AppConfiguration.Builder.ejson]. For details on configuration of serialization see
+     * [MongoClient].
+     * throws IllegalStateException if trying to obtain a [MongoClient] from a logged out [User].
+     */
+    @ExperimentalKBsonSerializerApi
+    public fun mongoClient(serviceName: String, eJson: EJson? = null): MongoClient
+
     /**
      * Two Users are considered equal if they have the same user identity and are associated
      * with the same app.

packages/library-sync/src/commonMain/kotlin/io/realm/kotlin/mongodb/exceptions/ServiceExceptions.kt

@@ -20,8 +20,8 @@ import io.realm.kotlin.internal.interop.CodeDescription
 
 /**
  * This exception is considered the top-level or "catch-all" for problems related to HTTP requests
- * made towards App Services. This covers both HTTP transport problems, problems passing JSON
- * or the server considering the request invalid, for whatever reason.
+ * made towards App Services. This covers both HTTP transport problems, or the server considering
+ * the request invalid, for whatever reason.
  *
  * Generally, reacting to this exception will be hard, except to log the error for further
  * analysis. But in many cases a more specific subtype will be thrown, which will be easier to

packages/library-sync/src/commonMain/kotlin/io/realm/kotlin/mongodb/ext/MongoClientExt.kt

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2024 Realm Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.realm.kotlin.mongodb.ext
+
+import io.realm.kotlin.internal.platform.realmObjectCompanionOrThrow
+import io.realm.kotlin.mongodb.internal.MongoClientCollection
+import io.realm.kotlin.mongodb.internal.MongoClientImpl
+import io.realm.kotlin.mongodb.mongo.MongoClient
+import io.realm.kotlin.mongodb.mongo.MongoCollection
+import io.realm.kotlin.types.BaseRealmObject
+import org.mongodb.kbson.ExperimentalKBsonSerializerApi
+import org.mongodb.kbson.serialization.EJson
+
+/**
+ * Get a [MongoCollection] that exposes methods to retrieve and update data from the remote
+ * collection of objects of schema type [T].
+ *
+ * Serialization to and from EJSON is performed with [KBSON](https://github.com/mongodb/kbson)
+ * and requires to opt-in to the experimental [ExperimentalKBsonSerializerApi]-feature.
+ *
+ * @param eJson the EJson serializer that the [MongoCollection] should use to convert objects and
+ * primary keys with. Will default to the databases [EJson] instance.
+ * @param T the schema type indicating which for which remote entities of the collection will be
+ * serialized from and to.
+ * @param K the default type that primary keys will be serialized into.
+ * @return a [MongoCollection] that will accept and return entities from the remote collection
+ * as [T] values.
+ */
+@ExperimentalKBsonSerializerApi
+public inline fun <reified T : BaseRealmObject, K> MongoClient.collection(eJson: EJson? = null): MongoCollection<T, K> {
+    @Suppress("invisible_reference", "invisible_member")
+    return MongoClientCollection(this as MongoClientImpl, realmObjectCompanionOrThrow(T::class).io_realm_kotlin_className, eJson ?: this.eJson)
+}