DataRaft swift package

Sources/DataRaft/Protocols/DatabaseServiceProtocol.swift

@@ -0,0 +1,55 @@
+import Foundation
+import DataLiteCore
+
+/// A protocol that defines a common interface for working with a database connection.
+///
+/// Conforming types provide methods for executing closures with a live `Connection`, optionally
+/// wrapped in transactions. These closures are guaranteed to execute in a thread-safe and
+/// serialized manner. Implementations may also support reconnecting and managing encryption keys.
+public protocol DatabaseServiceProtocol: AnyObject {
+    /// A closure that performs a database operation using an active connection.
+    ///
+    /// The `Perform<T>` alias defines the signature for a database operation block
+    /// that receives a live `Connection` and either returns a result or throws an error.
+    /// It is commonly used to express atomic units of work in ``perform(_:)`` or
+    /// ``perform(in:closure:)`` calls.
+    ///
+    /// - Parameter T: The result type returned by the closure.
+    /// - Returns: A value of type `T` produced by the closure.
+    /// - Throws: Any error that occurs during execution of the database operation.
+    typealias Perform<T> = (Connection) throws -> T
+    
+    /// The object responsible for providing encryption keys for the database connection.
+    ///
+    /// When assigned, the key provider will be queried for a new key and applied to the current
+    /// connection, if available.
+    var keyProvider: DatabaseServiceKeyProvider? { get set }
+    
+    /// Re-establishes the database connection using the stored provider.
+    ///
+    /// If a `keyProvider` is set, the returned connection will attempt to apply a new key.
+    ///
+    /// - Throws: Any error that occurs during connection creation or key application.
+    func reconnect() throws
+    
+    /// Executes the given closure with a live connection.
+    ///
+    /// - Parameter closure: The operation to execute.
+    /// - Returns: The result produced by the closure.
+    /// - Throws: Any error thrown during execution.
+    func perform<T>(_ closure: Perform<T>) rethrows -> T
+    
+    /// Executes the given closure within a transaction.
+    ///
+    /// If no transaction is active, a new one is started and committed or rolled back as needed.
+    ///
+    /// - Parameters:
+    ///   - transaction: The transaction type to begin.
+    ///   - closure: The operation to execute within the transaction.
+    /// - Returns: The result produced by the closure.
+    /// - Throws: Any error thrown by the closure or transaction.
+    func perform<T>(
+        in transaction: TransactionType,
+        closure: Perform<T>
+    ) rethrows -> T
+}