Attachments package (#159)

Author: stevensJourney

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.0-BETA31
+
+* Added helpers for Attachment syncing.
+
 ## 1.0.0-BETA30
 
 * Fix a deadlock when calling `connect()` immediately after opening a database.
@@ -10,22 +14,31 @@
 * Fix potential race condition between jobs in `connect()` and `disconnect()`.
 * [JVM Windows] Fixed PowerSync Extension temporary file deletion error on process shutdown.
 * [iOS] Fixed issue where automatic driver migrations would fail with the error:
+
 ```
 Sqlite operation failure database is locked attempted to run migration and failed. closing connection
 ```
+
 * Fix race condition causing data received during uploads not to be applied.
 
 ## 1.0.0-BETA28
 
 * Update PowerSync SQLite core extension to 0.3.12.
-* Added queing protection and warnings when connecting multiple PowerSync clients to the same database file.
-* Improved concurrent SQLite connection support accross various platforms. All platforms now use a single write connection and multiple read connections for concurrent read queries.
-* Added the ability to open a SQLite database given a custom `dbDirectory` path. This is currently not supported on iOS due to internal driver restrictions.
+* Added queing protection and warnings when connecting multiple PowerSync clients to the same
+  database file.
+* Improved concurrent SQLite connection support accross various platforms. All platforms now use a
+  single write connection and multiple read connections for concurrent read queries.
+* Added the ability to open a SQLite database given a custom `dbDirectory` path. This is currently
+  not supported on iOS due to internal driver restrictions.
 * Internaly improved the linking of SQLite for iOS.
 * Enabled Full Text Search on iOS platforms.
 * Added the ability to update the schema for existing PowerSync clients.
-* Fixed bug where local only, insert only and view name overrides were not applied for schema tables.
-* The Android SQLite driver now uses the [Xerial JDBC library](https://github.com/xerial/sqlite-jdbc). This removes the requirement for users to add the jitpack Maven repository to their projects.
+* Fixed bug where local only, insert only and view name overrides were not applied for schema
+  tables.
+* The Android SQLite driver now uses
+  the [Xerial JDBC library](https://github.com/xerial/sqlite-jdbc). This removes the requirement for
+  users to add the jitpack Maven repository to their projects.
+
 ```diff
 // settings.gradle.kts example
     repositories {
@@ -53,8 +66,10 @@ Sqlite operation failure database is locked attempted to run migration and faile
 
 ## 1.0.0-BETA24
 
-* Improve internal handling of watch queries to avoid issues where updates are not being received due to transaction commits occurring after the query is run.
-* Fix issue in JVM build where `columnNames` was throwing an error due to the index of the JDBC driver starting at 1 instead of 0 as in the other drivers/
+* Improve internal handling of watch queries to avoid issues where updates are not being received
+  due to transaction commits occurring after the query is run.
+* Fix issue in JVM build where `columnNames` was throwing an error due to the index of the JDBC
+  driver starting at 1 instead of 0 as in the other drivers/
 * Throw and not just catch `CancellationExceptions` in `runWrappedSuspending`
 
 ## 1.0.0-BETA23
@@ -72,14 +87,18 @@ Sqlite operation failure database is locked attempted to run migration and faile
 
 ## 1.0.0-BETA20
 
-* Add cursor optional functions: `getStringOptional`, `getLongOptional`, `getDoubleOptional`, `getBooleanOptional` and `getBytesOptional` when using the column name which allow for optional return types
+* Add cursor optional functions: `getStringOptional`, `getLongOptional`, `getDoubleOptional`,
+  `getBooleanOptional` and `getBytesOptional` when using the column name which allow for optional
+  return types
 * Throw errors for invalid column on all cursor functions
-* `getString`, `getLong`, `getBytes`, `getDouble` and `getBoolean` used with the column name will now throw an error for non-null values and expect a non optional return type
+* `getString`, `getLong`, `getBytes`, `getDouble` and `getBoolean` used with the column name will
+  now throw an error for non-null values and expect a non optional return type
 
 ## 1.0.0-BETA19
 
 * Allow cursor to get values by column name e.g. `getStringOptional("id")`
-* BREAKING CHANGE: If you were using `SqlCursor` from SqlDelight previously for your own custom mapper then you must now change to `SqlCursor` exported by the PowerSync module.
+* BREAKING CHANGE: If you were using `SqlCursor` from SqlDelight previously for your own custom
+  mapper then you must now change to `SqlCursor` exported by the PowerSync module.
 
   Previously you would import it like this:
 
@@ -95,7 +114,8 @@ Sqlite operation failure database is locked attempted to run migration and faile
 
 ## 1.0.0-BETA18
 
-* BREAKING CHANGE: Move from async sqldelight calls to synchronous calls. This will only affect `readTransaction` and `writeTransaction`where the callback function is no longer asynchronous.
+* BREAKING CHANGE: Move from async sqldelight calls to synchronous calls. This will only affect
+  `readTransaction` and `writeTransaction`where the callback function is no longer asynchronous.
 
 ## 1.0.0-BETA17
 
@@ -104,7 +124,8 @@ Sqlite operation failure database is locked attempted to run migration and faile
 ## 1.0.0-BETA16
 
 * Add `close` method to database methods
-* Throw when error is a `CancellationError` and remove invalidation for all errors in `streamingSync` catch.
+* Throw when error is a `CancellationError` and remove invalidation for all errors in
+  `streamingSync` catch.
 
 ## 1.0.0-BETA15
 
@@ -118,7 +139,8 @@ Sqlite operation failure database is locked attempted to run migration and faile
 
 ## 1.0.0-BETA13
 
-* Move iOS database driver to use IO dispatcher which should avoid race conditions and improve performance.
+* Move iOS database driver to use IO dispatcher which should avoid race conditions and improve
+  performance.
 
 ## 1.0.0-BETA12
 
@@ -135,7 +157,8 @@ Sqlite operation failure database is locked attempted to run migration and faile
 ## 1.0.0-BETA9
 
 * Re-enable SKIE `SuspendInterop`
-* Move transaction functions out of `PowerSyncTransactionFactory` to avoid threading issues in Swift SDK
+* Move transaction functions out of `PowerSyncTransactionFactory` to avoid threading issues in Swift
+  SDK
 
 ## 1.0.0-BETA8
 
@@ -164,37 +187,43 @@ Sqlite operation failure database is locked attempted to run migration and faile
 * Add `waitForFirstSync` function - which resolves after the initial sync is completed
 * Upgrade to Kotlin 2.0.20 - should not cause any issues with users who are still on Kotlin 1.9
 * Upgrade `powersync-sqlite-core` to 0.3.0 - improves incremental sync performance
-* Add client sync parameters - which allows you specify sync parameters from the client https://docs.powersync.com/usage/sync-rules/advanced-topics/client-parameters-beta
+* Add client sync parameters - which allows you specify sync parameters from the
+  client https://docs.powersync.com/usage/sync-rules/advanced-topics/client-parameters-beta
+
 ```kotlin
 val params = JsonParam.Map(
-  mapOf(
-    "name" to JsonParam.String("John Doe"),
-    "age" to JsonParam.Number(30),
-    "isStudent" to JsonParam.Boolean(false)
-  )
+    mapOf(
+        "name" to JsonParam.String("John Doe"),
+        "age" to JsonParam.Number(30),
+        "isStudent" to JsonParam.Boolean(false)
+    )
 )
 
 connect(
-...
-  params = params
+    ...
+params = params
 )
 ```
+
 * Add schema validation when schema is generated
-* Add warning message if there is a crudItem in the queue that has not yet been synced and after a delay rerun the upload
+* Add warning message if there is a crudItem in the queue that has not yet been synced and after a
+  delay rerun the upload
 
 ## 1.0.0-BETA2
 
 * Publish persistence package
 
 ## 1.0.0-BETA1
 
-* Improve API by changing from Builder pattern to simply instantiating the database `PowerSyncDatabase`
+* Improve API by changing from Builder pattern to simply instantiating the database
+  `PowerSyncDatabase`
   E.g. `val db = PowerSyncDatabase(factory, schema)`
 * Use callback context in transactions
   E.g. `db.writeTransaction{ ctx -> ctx.execute(...) }`
 * Removed unnecessary expiredAt field
 * Added table max column validation as there is a hard limit of 63 columns
 * Moved SQLDelight models to a separate module to reduce export size
-* Replaced default Logger with [Kermit Logger](https://kermit.touchlab.co/) which allows users to more easily use and/or change Logger settings
+* Replaced default Logger with [Kermit Logger](https://kermit.touchlab.co/) which allows users to
+  more easily use and/or change Logger settings
 * Add `retryDelay` and `crudThrottle` options when setting up database connection
 * Changed `_viewNameOverride` to `viewNameOverride`

connectors/supabase/build.gradle.kts

@@ -28,6 +28,7 @@ kotlin {
             implementation(libs.kotlinx.coroutines.core)
             implementation(libs.supabase.client)
             api(libs.supabase.auth)
+            api(libs.supabase.storage)
         }
     }
 }

connectors/supabase/src/commonMain/kotlin/com/powersync/connector/supabase/SupabaseConnector.kt

@@ -17,6 +17,9 @@ import io.github.jan.supabase.auth.user.UserSession
 import io.github.jan.supabase.createSupabaseClient
 import io.github.jan.supabase.postgrest.Postgrest
 import io.github.jan.supabase.postgrest.from
+import io.github.jan.supabase.storage.BucketApi
+import io.github.jan.supabase.storage.Storage
+import io.github.jan.supabase.storage.storage
 import io.ktor.client.plugins.HttpSend
 import io.ktor.client.plugins.plugin
 import io.ktor.client.statement.bodyAsText
@@ -31,6 +34,7 @@ import kotlinx.serialization.json.Json
 public class SupabaseConnector(
     public val supabaseClient: SupabaseClient,
     public val powerSyncEndpoint: String,
+    private val storageBucket: String? = null,
 ) : PowerSyncBackendConnector() {
     private var errorCode: String? = null
 
@@ -52,17 +56,29 @@ public class SupabaseConnector(
             }
     }
 
+    public fun storageBucket(): BucketApi {
+        if (storageBucket == null) {
+            throw Exception("No bucket has been specified")
+        }
+        return supabaseClient.storage[storageBucket]
+    }
+
     public constructor(
         supabaseUrl: String,
         supabaseKey: String,
         powerSyncEndpoint: String,
+        storageBucket: String? = null,
     ) : this(
         supabaseClient =
             createSupabaseClient(supabaseUrl, supabaseKey) {
                 install(Auth)
                 install(Postgrest)
+                if (storageBucket != null) {
+                    install(Storage)
+                }
             },
         powerSyncEndpoint = powerSyncEndpoint,
+        storageBucket = storageBucket,
     )
 
     init {
@@ -81,7 +97,10 @@ public class SupabaseConnector(
                 val responseText = response.bodyAsText()
 
                 try {
-                    val error = Json { coerceInputValues = true }.decodeFromString<Map<String, String?>>(responseText)
+                    val error =
+                        Json { coerceInputValues = true }.decodeFromString<Map<String, String?>>(
+                            responseText,
+                        )
                     errorCode = error["code"]
                 } catch (e: Exception) {
                     Logger.e("Failed to parse error response: $e")
@@ -139,7 +158,9 @@ public class SupabaseConnector(
             check(supabaseClient.auth.sessionStatus.value is SessionStatus.Authenticated) { "Supabase client is not authenticated" }
 
             // Use Supabase token for PowerSync
-            val session = supabaseClient.auth.currentSessionOrNull() ?: error("Could not fetch Supabase credentials")
+            val session =
+                supabaseClient.auth.currentSessionOrNull()
+                    ?: error("Could not fetch Supabase credentials")
 
             check(session.user != null) { "No user data" }
 

connectors/supabase/src/commonMain/kotlin/com/powersync/connector/supabase/SupabaseRemoteStorage.kt

@@ -0,0 +1,57 @@
+package com.powersync.connector.supabase
+
+import com.powersync.attachments.Attachment
+import com.powersync.attachments.RemoteStorage
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flowOf
+
+/**
+ * Implementation of [RemoteStorage] that uses Supabase as the backend storage provider.
+ *
+ * @property connector The Supabase connector used to interact with the Supabase storage bucket.
+ */
+public class SupabaseRemoteStorage(
+    public val connector: SupabaseConnector,
+) : RemoteStorage {
+    /**
+     * Uploads a file to the Supabase storage bucket.
+     *
+     * @param fileData A [Flow] of [ByteArray] representing the file data to be uploaded.
+     * @param attachment The [Attachment] metadata associated with the file.
+     * @throws IllegalStateException If the attachment size is not specified.
+     */
+    override suspend fun uploadFile(
+        fileData: Flow<ByteArray>,
+        attachment: Attachment,
+    ) {
+        val byteSize =
+            attachment.size?.toInt() ?: error("Cannot upload a file with no byte size specified")
+        // Supabase wants a single ByteArray
+        val buffer = ByteArray(byteSize)
+        var position = 0
+        fileData.collect {
+            it.copyInto(buffer, destinationOffset = position)
+            position += it.size
+        }
+
+        connector.storageBucket().upload(attachment.filename, buffer)
+    }
+
+    /**
+     * Downloads a file from the Supabase storage bucket.
+     *
+     * @param attachment The [Attachment] record associated with the file to be downloaded.
+     * @return A [Flow] of [ByteArray] representing the file data.
+     */
+    override suspend fun downloadFile(attachment: Attachment): Flow<ByteArray> =
+        flowOf(connector.storageBucket().downloadAuthenticated(attachment.filename))
+
+    /**
+     * Deletes a file from the Supabase storage bucket.
+     *
+     * @param attachment The [Attachment] record associated with the file to be deleted.
+     */
+    override suspend fun deleteFile(attachment: Attachment) {
+        connector.storageBucket().delete(attachment.filename)
+    }
+}

core/README.md

@@ -24,8 +24,14 @@ structure:
 ## Note on SQLDelight
 
 The PowerSync core module, internally makes use
-of [SQLDelight](https://sqldelight.github.io/sqldelight/latest/) for it database API and typesafe database
+of [SQLDelight](https://sqldelight.github.io/sqldelight/latest/) for it database API and typesafe
+database
 query generation.
 
 The PowerSync core module does not currently support integrating with SQLDelight from client
 applications.
+
+## Attachment Helpers
+
+This module contains attachment helpers under the `com.powersync.attachments` package. See
+the [Attachment Helpers README](./src/commonMain/kotlin/com/powersync/attachments/README.md)