Added experimental API

realm · nhachicha · Jan 18, 2024 · Jan 18, 2024 · Jan 18, 2024 · Jan 19, 2024
commit 44549febcf41fa76b0681e8ac4fca0f854f2f68c
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 ### 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))
+* Added an experimental configuration API which will allow to pass the encryption key using a callback https://github.com/realm/realm-kotlin/pull/1636.
 
 ### 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))

diff --git a/packages/library-base/src/commonMain/kotlin/io/realm/kotlin/Configuration.kt b/packages/library-base/src/commonMain/kotlin/io/realm/kotlin/Configuration.kt
@@ -17,6 +17,7 @@
 package io.realm.kotlin
 
 import io.realm.kotlin.Configuration.SharedBuilder
+import io.realm.kotlin.annotations.ExperimentalEncryptionCallbackApi
 import io.realm.kotlin.internal.MISSING_PLUGIN_MESSAGE
 import io.realm.kotlin.internal.REALM_FILE_EXTENSION
 import io.realm.kotlin.internal.platform.PATH_SEPARATOR
@@ -106,6 +107,7 @@ public data class InitialRealmFileConfiguration(
     val checksum: String?
 )
 
+@ExperimentalEncryptionCallbackApi
 public interface EncryptionKeyCallback {
     /**
      * Provides the native memory address of the 64 byte array containing the key used to encrypt and decrypt the Realm file.
@@ -170,6 +172,7 @@ public interface Configuration {
      *
      * @return null on unencrypted Realms.
      */
+    @OptIn(ExperimentalEncryptionCallbackApi::class)
     public val encryptionKeyAsCallback: EncryptionKeyCallback?
 
     /**
@@ -253,6 +256,7 @@ public interface Configuration {
         protected var writeDispatcher: CoroutineDispatcher? = null
         protected var schemaVersion: Long = 0
         protected var encryptionKey: ByteArray? = null
+        @OptIn(ExperimentalEncryptionCallbackApi::class)
         protected var encryptionKeyAsCallback: EncryptionKeyCallback? = null
         protected var compactOnLaunchCallback: CompactOnLaunchCallback? = null
         protected var initialDataCallback: InitialDataCallback? = null
@@ -416,6 +420,7 @@ public interface Configuration {
          * val realm = Realm.open(encryptedConf)
          *```
          */
+        @OptIn(ExperimentalEncryptionCallbackApi::class)
         public fun encryptionKey(encryptionKeyAsCallback: EncryptionKeyCallback): S =
             apply { this.encryptionKeyAsCallback = encryptionKeyAsCallback } as S
 

diff --git a/packages/library-base/src/commonMain/kotlin/io/realm/kotlin/RealmConfiguration.kt b/packages/library-base/src/commonMain/kotlin/io/realm/kotlin/RealmConfiguration.kt
@@ -16,6 +16,7 @@
 
 package io.realm.kotlin
 
+import io.realm.kotlin.annotations.ExperimentalEncryptionCallbackApi
 import io.realm.kotlin.internal.ContextLogger
 import io.realm.kotlin.internal.RealmConfigurationImpl
 import io.realm.kotlin.internal.platform.appFilesDirectory
@@ -185,6 +186,7 @@ public interface RealmConfiguration : Configuration {
                 writerDispatcherFactory,
                 schemaVersion,
                 encryptionKey,
+                @OptIn(ExperimentalEncryptionCallbackApi::class)
                 encryptionKeyAsCallback,
                 deleteRealmIfMigrationNeeded,
                 compactOnLaunchCallback,

diff --git a/...se/src/commonMain/kotlin/io/realm/kotlin/annotations/ExperimentalEncryptionCallbackApi.kt b/...se/src/commonMain/kotlin/io/realm/kotlin/annotations/ExperimentalEncryptionCallbackApi.kt
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2023 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.annotations
+
+/**
+ * This annotation mark Realm API for encryption callback **experimental**, i.e.
+ * there are no guarantees given that this API cannot change without warning between minor and
+ * major versions. They will not change between patch versions.
+ *
+ * For all other purposes these APIs are considered stable, i.e. they undergo the same testing
+ * as other parts of the API and should behave as documented with no bugs. It is primarily
+ * marked as experimental because we are unsure if this API provide value and solve the use
+ * cases that people have. If not, they will be changed or removed altogether.
+ */
+@MustBeDocumented
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.PROPERTY,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.TYPEALIAS
+)
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
+public annotation class ExperimentalEncryptionCallbackApi
diff --git a/packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/ConfigurationImpl.kt b/packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/ConfigurationImpl.kt
@@ -21,6 +21,7 @@ import io.realm.kotlin.EncryptionKeyCallback
 import io.realm.kotlin.InitialDataCallback
 import io.realm.kotlin.InitialRealmFileConfiguration
 import io.realm.kotlin.LogConfiguration
+import io.realm.kotlin.annotations.ExperimentalEncryptionCallbackApi
 import io.realm.kotlin.dynamic.DynamicMutableRealm
 import io.realm.kotlin.dynamic.DynamicMutableRealmObject
 import io.realm.kotlin.dynamic.DynamicRealm
@@ -61,6 +62,7 @@ public open class ConfigurationImpl(
     schemaVersion: Long,
     schemaMode: SchemaMode,
     private val userEncryptionKey: ByteArray?,
+    @OptIn(ExperimentalEncryptionCallbackApi::class)
     override val encryptionKeyAsCallback: EncryptionKeyCallback?,
     compactOnLaunchCallback: CompactOnLaunchCallback?,
     userMigration: RealmMigration?,
@@ -232,6 +234,7 @@ public open class ConfigurationImpl(
                 RealmInterop.realm_config_set_encryption_key(nativeConfig, key)
             }
 
+            @OptIn(ExperimentalEncryptionCallbackApi::class)
             encryptionKeyAsCallback?.let {
                 RealmInterop.realm_config_set_encryption_key_from_pointer(nativeConfig, it.keyPointer())
             }

diff --git a/...ges/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/RealmConfigurationImpl.kt b/...ges/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/RealmConfigurationImpl.kt
@@ -22,6 +22,7 @@ import io.realm.kotlin.InitialDataCallback
 import io.realm.kotlin.InitialRealmFileConfiguration
 import io.realm.kotlin.LogConfiguration
 import io.realm.kotlin.RealmConfiguration
+import io.realm.kotlin.annotations.ExperimentalEncryptionCallbackApi
 import io.realm.kotlin.internal.interop.SchemaMode
 import io.realm.kotlin.internal.util.CoroutineDispatcherFactory
 import io.realm.kotlin.migration.RealmMigration
@@ -41,6 +42,7 @@ internal class RealmConfigurationImpl(
     writeDispatcherFactory: CoroutineDispatcherFactory,
     schemaVersion: Long,
     encryptionKey: ByteArray?,
+    @OptIn(ExperimentalEncryptionCallbackApi::class)
     encryptionKeyAsCallback: EncryptionKeyCallback?,
     override val deleteRealmIfMigrationNeeded: Boolean,
     compactOnLaunchCallback: CompactOnLaunchCallback?,
@@ -64,6 +66,7 @@ internal class RealmConfigurationImpl(
         false -> SchemaMode.RLM_SCHEMA_MODE_AUTOMATIC
     },
     encryptionKey,
+    @OptIn(ExperimentalEncryptionCallbackApi::class)
     encryptionKeyAsCallback,
     compactOnLaunchCallback,
     migration,

diff --git a/packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/RealmImpl.kt b/packages/library-base/src/commonMain/kotlin/io/realm/kotlin/internal/RealmImpl.kt
@@ -19,6 +19,7 @@ package io.realm.kotlin.internal
 import io.realm.kotlin.Configuration
 import io.realm.kotlin.MutableRealm
 import io.realm.kotlin.Realm
+import io.realm.kotlin.annotations.ExperimentalEncryptionCallbackApi
 import io.realm.kotlin.dynamic.DynamicRealm
 import io.realm.kotlin.internal.dynamic.DynamicRealmImpl
 import io.realm.kotlin.internal.interop.ClassKey
@@ -139,6 +140,7 @@ public class RealmImpl private constructor(
             }
 
             realmScope.launch {
+                @OptIn(ExperimentalEncryptionCallbackApi::class)
                 configuration.encryptionKeyAsCallback?.let {
                     // if we're using an encryption key as a callback, we preemptively open the notifier and writer Realm
                     // with the given configuration because the key might be deleted from memory after the Realm is open.

diff --git a/...ages/library-sync/src/commonMain/kotlin/io/realm/kotlin/mongodb/sync/SyncConfiguration.kt b/...ages/library-sync/src/commonMain/kotlin/io/realm/kotlin/mongodb/sync/SyncConfiguration.kt
@@ -20,6 +20,7 @@ import io.realm.kotlin.LogConfiguration
 import io.realm.kotlin.MutableRealm
 import io.realm.kotlin.Realm
 import io.realm.kotlin.TypedRealm
+import io.realm.kotlin.annotations.ExperimentalEncryptionCallbackApi
 import io.realm.kotlin.internal.ConfigurationImpl
 import io.realm.kotlin.internal.ContextLogger
 import io.realm.kotlin.internal.ObjectIdImpl
@@ -565,6 +566,7 @@ public interface SyncConfiguration : Configuration {
                 schemaVersion,
                 SchemaMode.RLM_SCHEMA_MODE_ADDITIVE_DISCOVERED,
                 encryptionKey,
+                @OptIn(ExperimentalEncryptionCallbackApi::class)
                 encryptionKeyAsCallback,
                 compactOnLaunchCallback,
                 null, // migration is not relevant for sync,

diff --git a/packages/test-base/src/commonTest/kotlin/io/realm/kotlin/test/common/EncryptionTests.kt b/packages/test-base/src/commonTest/kotlin/io/realm/kotlin/test/common/EncryptionTests.kt
@@ -19,6 +19,7 @@ package io.realm.kotlin.test.common
 import io.realm.kotlin.EncryptionKeyCallback
 import io.realm.kotlin.Realm
 import io.realm.kotlin.RealmConfiguration
+import io.realm.kotlin.annotations.ExperimentalEncryptionCallbackApi
 import io.realm.kotlin.entities.Sample
 import io.realm.kotlin.test.platform.PlatformUtils
 import io.realm.kotlin.test.util.use
@@ -128,6 +129,7 @@ class EncryptionTests {
             }
     }
 
+    @OptIn(ExperimentalEncryptionCallbackApi::class)
     @Test
     fun openEncryptedRealmWithEncryptionKeyCallback() = runBlocking {
         val key: ByteArray = Random.nextBytes(64)