feat: appMetadata (#104)

Author: stevensJourney

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.9.0 (unreleased)
+
+* Add `appMetadata` parameter to `PowerSyncDatabase.connect()` (via `ConnectOptions`) to include application metadata in sync requests. This metadata is merged into sync requests and displayed in PowerSync service logs.
+
+  Note: This requires a PowerSync service version `>=1.17.0` in order for logs to display metadata.
+
+  ```swift
+  try await database.connect(
+      connector: connector,
+      options: ConnectOptions(
+          appMetadata: ["appVersion": "1.0.0", "deviceId": "device456"]
+      )
+  )
+  ```
+
 ## 1.8.2
 
 * Fix `PowerSyncKotlin` frameworks not containing a `CFBundleVersion`.

Package.resolved

@@ -1,6 +1,6 @@
+import CSQLite
 import Foundation
 import PowerSyncKotlin
-import CSQLite
 
 final class KotlinPowerSyncDatabaseImpl: PowerSyncDatabaseProtocol,
     // `PowerSyncKotlin.PowerSyncDatabase` cannot be marked as Sendable
@@ -17,11 +17,11 @@ final class KotlinPowerSyncDatabaseImpl: PowerSyncDatabaseProtocol,
         dbFilename: String,
         logger: DatabaseLogger
     ) {
-        let rc = sqlite3_initialize();
-        if (rc != 0) {
+        let rc = sqlite3_initialize()
+        if rc != 0 {
             fatalError("Call to sqlite3_initialize() failed with \(rc)")
         }
-        
+
         let factory = sqlite3DatabaseFactory(initialStatements: [])
         kotlinDatabase = PowerSyncDatabase(
             factory: factory,
@@ -71,7 +71,7 @@ final class KotlinPowerSyncDatabaseImpl: PowerSyncDatabaseProtocol,
                 userAgent: "PowerSync Swift SDK",
                 loggingConfig: resolvedOptions.clientConfiguration?.requestLogger?.toKotlinConfig()
             ),
-            appMetadata: [:]
+            appMetadata: resolvedOptions.appMetadata
         )
     }
 

Sources/PowerSync/Kotlin/KotlinPowerSyncDatabaseImpl.swift

@@ -55,6 +55,17 @@ public struct ConnectOptions: Sendable {
     /// ```
     public var params: JsonParam
 
+    /// Application metadata that will be displayed in PowerSync service logs.
+    ///
+    /// Provide small, non-sensitive key/value pairs (for example: `appName`, `version`, `environment`) to
+    /// help identify the client in logs and diagnostics. Do not include secrets or tokens.
+    ///
+    /// Example:
+    /// ```swift
+    /// ["appName": "MyApp", "version": "1.2.3"]
+    /// ```
+    public var appMetadata: [String: String]
+
     /// Uses a new sync client implemented in Rust instead of the one implemented in Kotlin.
     ///
     /// The new client is more efficient and will become the default in the future, but is still marked as experimental for now.
@@ -85,13 +96,15 @@ public struct ConnectOptions: Sendable {
         crudThrottle: TimeInterval = 1,
         retryDelay: TimeInterval = 5,
         params: JsonParam = [:],
-        clientConfiguration: SyncClientConfiguration? = nil
+        clientConfiguration: SyncClientConfiguration? = nil,
+        appMetadata: [String: String] = [:]
     ) {
         self.crudThrottle = crudThrottle
         self.retryDelay = retryDelay
         self.params = params
         newClientImplementation = true
         self.clientConfiguration = clientConfiguration
+        self.appMetadata = appMetadata
     }
 
     /// Initializes a ``ConnectOptions`` instance with optional values, including experimental options.
@@ -105,13 +118,15 @@ public struct ConnectOptions: Sendable {
         retryDelay: TimeInterval = 5,
         params: JsonParam = [:],
         newClientImplementation: Bool = true,
-        clientConfiguration: SyncClientConfiguration? = nil
+        clientConfiguration: SyncClientConfiguration? = nil,
+        appMetadata: [String: String] = [:]
     ) {
         self.crudThrottle = crudThrottle
         self.retryDelay = retryDelay
         self.params = params
         self.newClientImplementation = newClientImplementation
         self.clientConfiguration = clientConfiguration
+        self.appMetadata = appMetadata
     }
 }
 

Sources/PowerSync/Protocol/PowerSyncDatabaseProtocol.swift

@@ -139,6 +139,57 @@ final class ConnectTests: XCTestCase {
         try await database.disconnectAndClear()
     }
 
+    func testAppMetadata() async throws {
+        let expectation = XCTestExpectation(
+            description: "Should log a request to the PowerSync endpoint with metadata"
+        )
+
+        let fakeUrl = "https://fakepowersyncinstance.fakepowersync.local"
+        let testAppName = "testAppName"
+        final class TestConnector: PowerSyncBackendConnectorProtocol {
+            let url: String
+
+            init(url: String) {
+                self.url = url
+            }
+
+            func fetchCredentials() async throws -> PowerSyncCredentials? {
+                PowerSyncCredentials(
+                    endpoint: url,
+                    token: "123"
+                )
+            }
+
+            func uploadData(database _: PowerSyncDatabaseProtocol) async throws {}
+        }
+
+        try await database.connect(
+            connector: TestConnector(url: fakeUrl),
+            options: ConnectOptions(
+                /// Note that currently, HTTP logs are only supported with the old client implementation
+                /// which uses HTTP streams.
+                /// The new client implementation uses a WebSocket connection instead.
+                /// Which we don't get logs for currently.
+                newClientImplementation: false,
+                clientConfiguration: SyncClientConfiguration(
+                    requestLogger: SyncRequestLoggerConfiguration(
+                        requestLevel: .all
+                    ) { message in
+                        // We want to see a request to the specified instance with the app_metadata present
+                        if message.contains("\"app_metadata\":{\"appName\":\"\(testAppName)\"}") {
+                            expectation.fulfill()
+                        }
+                    }
+                ),
+                appMetadata: ["appName": testAppName]
+            )
+        )
+
+        await fulfillment(of: [expectation], timeout: 5)
+
+        try await database.disconnectAndClear()
+    }
+
     func testSendableConnect() async throws {
         /// This is just a basic sanity check to confirm that these protocols are
         /// correctly defined as Sendable.