docs(backup): add multiplatform sample implementations and documentat…

…ion (#3269) Introduced examples showcasing `MPBackupImporter` and `MPBackupExporter` usage for different platforms. Updated documentation, README, and build configurations to support multiplatform samples, including JS and non-JS targets.
wireapp · Feb 6, 2025 · 87e30ee · 87e30ee
1 parent 6f99a66
commit 87e30ee
Show file tree

Hide file tree

Showing 22 changed files with 302 additions and 66 deletions.
diff --git a/backup/README.md b/backup/README.md
@@ -3,6 +3,17 @@
 This module implements the Wire Cross-platform Backup solution.
 Its purpose is to create a common implementation to be used by iOS, Web, and Android.
 
+## Samples
+
+If you want to jump straight to examples, checkout the `nonJs` and `js` versions in the documentation:
+- [Importing](https://wireapp.github.io/kalium/backup/com.wire.backup.ingest/-m-p-backup-importer/index.html)
+- [Exporting](https://wireapp.github.io/kalium/backup/com.wire.backup.dump/-m-p-backup-exporter/index.html)
+
+## Data structure
+
+To see the currently supported data (conversations, users, messages, etc.), check
+[BackupData](https://wireapp.github.io/kalium/backup/com.wire.backup.data/-backup-message/index.html)
+
 ## Capabilities
 
 > [!TIP]

diff --git a/backup/build.gradle.kts b/backup/build.gradle.kts
@@ -37,7 +37,6 @@ android {
     }
 }
 
-@Suppress("UnusedPrivateProperty")
 kotlin {
     // Makes visibility modifiers mandatory
     // Useful for a library that will be called by other clients

diff --git a/backup/src/commonMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt b/backup/src/commonMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt
@@ -207,4 +207,8 @@ public abstract class CommonMPBackupExporter(
     }
 }
 
+/**
+ * Entity able to serialize [BackupData] entities, like [BackupMessage], [BackupConversation], [BackupUser]
+ * into a cross-platform [BackupData] format.
+ */
 public expect class MPBackupExporter : CommonMPBackupExporter
diff --git a/backup/src/commonMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt b/backup/src/commonMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt
@@ -157,4 +157,9 @@ public abstract class CommonMPBackupImporter internal constructor(
     internal abstract suspend fun unzipAllEntries(): BackupPageStorage
 }
 
+/**
+ * Entity able to parse backed-up data and returns
+ * digestible data in [BackupData] format.
+ * @sample samples.backup.BackupSample.commonImport
+ */
 public expect class MPBackupImporter : CommonMPBackupImporter
diff --git a/backup/src/jsMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt b/backup/src/jsMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt
@@ -17,10 +17,14 @@
  */
 package com.wire.backup.dump
 
+import com.wire.backup.data.BackupConversation
+import com.wire.backup.data.BackupMessage
 import com.wire.backup.data.BackupQualifiedId
+import com.wire.backup.data.BackupUser
 import com.wire.backup.filesystem.BackupPage
 import com.wire.backup.filesystem.BackupPageStorage
 import com.wire.backup.filesystem.InMemoryBackupPageStorage
+import com.wire.kalium.protobuf.backup.BackupData
 import ext.libsodium.com.ionspin.kotlin.crypto.toUByteArray
 import ext.libsodium.com.ionspin.kotlin.crypto.toUInt8Array
 import kotlinx.coroutines.Deferred
@@ -32,6 +36,11 @@ import okio.Source
 import okio.buffer
 import kotlin.js.Promise
 
+/**
+ * Entity able to serialize [BackupData] entities, like [BackupMessage], [BackupConversation], [BackupUser]
+ * into a cross-platform [BackupData] format.
+ * @sample samples.backup.BackupSamplesJs.exportBackup
+ */
 @JsExport
 public actual class MPBackupExporter(
     selfUserId: BackupQualifiedId

diff --git a/backup/src/jsMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt b/backup/src/jsMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt
@@ -17,6 +17,7 @@
  */
 package com.wire.backup.ingest
 
+import com.wire.backup.data.BackupData
 import com.wire.backup.dump.JSZip
 import com.wire.backup.filesystem.BackupPage
 import com.wire.backup.filesystem.BackupPageStorage
@@ -31,6 +32,12 @@ import okio.Sink
 import org.khronos.webgl.Uint8Array
 import kotlin.js.Promise
 
+/**
+ * Entity able to parse backed-up data and returns
+ * digestible data in [BackupData] format.
+ * @sample samples.backup.BackupSamplesJs.peekBackup
+ * @sample samples.backup.BackupSamples.commonImport
+ */
 @JsExport
 public actual class MPBackupImporter : CommonMPBackupImporter() {
     private val inMemoryUnencryptedBuffer = Buffer()

diff --git a/backup/src/nonJsMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt b/backup/src/nonJsMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt
@@ -18,17 +18,26 @@
 package com.wire.backup.dump
 
 import com.rickclephas.kmp.nativecoroutines.NativeCoroutines
+import com.wire.backup.data.BackupConversation
+import com.wire.backup.data.BackupMessage
 import com.wire.backup.data.BackupQualifiedId
+import com.wire.backup.data.BackupUser
 import com.wire.backup.filesystem.BackupPage
 import com.wire.backup.filesystem.BackupPageStorage
 import com.wire.backup.filesystem.FileBasedBackupPageStorage
+import com.wire.kalium.protobuf.backup.BackupData
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.Deferred
 import okio.FileSystem
 import okio.Path.Companion.toPath
 import okio.SYSTEM
 import okio.Source
 
+/**
+ * Entity able to serialize [BackupData] entities, like [BackupMessage], [BackupConversation], [BackupUser]
+ * into a cross-platform [BackupData] format.
+ * @sample samples.backup.BackupSamplesNonJS.exportBackup
+ */
 public actual class MPBackupExporter(
     selfUserId: BackupQualifiedId,
     workDirectory: String,

diff --git a/backup/src/nonJsMain/kotlin/com/wire/backup/ingest/BackupFileUnzipper.kt b/backup/src/nonJsMain/kotlin/com/wire/backup/ingest/BackupFileUnzipper.kt
@@ -17,7 +17,7 @@
  */
 package com.wire.backup.ingest
 
-public interface BackupFileUnzipper {
+public fun interface BackupFileUnzipper {
 
     /**
      * Unzip all the entries stored within the file at [zipPath] to _some_ directory of choice.

diff --git a/backup/src/nonJsMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt b/backup/src/nonJsMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt
@@ -18,6 +18,7 @@
 package com.wire.backup.ingest
 
 import com.rickclephas.kmp.nativecoroutines.NativeCoroutines
+import com.wire.backup.data.BackupData
 import com.wire.backup.filesystem.BackupPageStorage
 import com.wire.backup.filesystem.FileBasedBackupPageStorage
 import okio.FileSystem
@@ -28,6 +29,12 @@ import okio.Sink
 import kotlin.experimental.ExperimentalObjCName
 import kotlin.native.ObjCName
 
+/**
+ * Entity able to parse backed-up data and returns
+ * digestible data in [BackupData] format.
+ * @sample samples.backup.BackupSamplesNonJS.peekBackup
+ * @sample samples.backup.BackupSamples.commonImport
+ */
 @OptIn(ExperimentalObjCName::class)
 public actual class MPBackupImporter(
     private val pathToWorkDirectory: String,

diff --git a/buildSrc/src/main/kotlin/com/wire/kalium/plugins/CommonDokkaConfig.kt b/buildSrc/src/main/kotlin/com/wire/kalium/plugins/CommonDokkaConfig.kt
@@ -23,6 +23,7 @@ import org.jetbrains.dokka.DokkaConfiguration.Visibility
 import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
 
 val documentedSubprojects = listOf(
+    "backup",
     "calling",
     "cli",
     "cryptography",

diff --git a/data/build.gradle.kts b/data/build.gradle.kts
@@ -27,7 +27,6 @@ kaliumLibrary {
     multiplatform { }
 }
 
-@Suppress("UnusedPrivateProperty")
 kotlin {
     sourceSets {
         val commonMain by getting {