89 lines
3.9 KiB
Swift
89 lines
3.9 KiB
Swift
import Foundation
|
|
import DataLiteCore
|
|
|
|
/// A protocol that defines a common interface for working with a database connection.
|
|
///
|
|
/// `DatabaseServiceProtocol` abstracts the core operations required to safely interact with a
|
|
/// SQLite-compatible database. Conforming types provide thread-safe execution of closures with a live
|
|
/// `Connection`, optional transaction support, reconnection logic, and pluggable encryption key
|
|
/// management via a ``DatabaseServiceKeyProvider``.
|
|
///
|
|
/// This protocol forms the foundation for safe, modular service layers on top of a database.
|
|
///
|
|
/// ## Topics
|
|
///
|
|
/// ### Key Management
|
|
///
|
|
/// - ``DatabaseServiceKeyProvider``
|
|
/// - ``keyProvider``
|
|
///
|
|
/// ### Connection Management
|
|
///
|
|
/// - ``reconnect()``
|
|
///
|
|
/// ### Database Operations
|
|
///
|
|
/// - ``Perform``
|
|
/// - ``perform(_:)``
|
|
/// - ``perform(in:closure:)``
|
|
public protocol DatabaseServiceProtocol: AnyObject {
|
|
/// A closure that performs a database operation using an active connection.
|
|
///
|
|
/// The `Perform<T>` type alias defines a closure signature for a database operation that
|
|
/// receives a live `Connection` and returns a value or throws an error. This enables
|
|
/// callers to express discrete, atomic database operations for execution via
|
|
/// ``perform(_:)`` or ``perform(in:closure:)``.
|
|
///
|
|
/// - Parameter connection: The active database connection.
|
|
/// - Returns: The result of the operation.
|
|
/// - Throws: Any error thrown during execution of the 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 key and applied to the current
|
|
/// connection, if available. If key retrieval or application fails, the error is reported
|
|
/// via `databaseService(_:didReceive:)` and not thrown from the setter.
|
|
///
|
|
/// - Important: Setting this property does not guarantee that the connection becomes available;
|
|
/// error handling is asynchronous via callback.
|
|
var keyProvider: DatabaseServiceKeyProvider? { get set }
|
|
|
|
/// Re-establishes the database connection using the stored provider.
|
|
///
|
|
/// If a `keyProvider` is set, the method attempts to retrieve and apply a key
|
|
/// to the new connection. All errors encountered during connection creation or
|
|
/// key application are thrown. If an error occurs that is related to encryption key
|
|
/// retrieval or application, it is also reported to the `DatabaseServiceKeyProvider`
|
|
/// via its `databaseService(_:didReceive:)` callback.
|
|
///
|
|
/// - Throws: Any error that occurs during connection creation or key application.
|
|
func reconnect() throws
|
|
|
|
/// Executes the given closure with a live connection in a thread-safe manner.
|
|
///
|
|
/// All invocations are serialized to prevent concurrent database access.
|
|
///
|
|
/// - Parameter closure: The database operation to perform.
|
|
/// - Returns: The result produced by the closure.
|
|
/// - Throws: Any error thrown by the closure.
|
|
func perform<T>(_ closure: Perform<T>) rethrows -> T
|
|
|
|
/// Executes the given closure within a transaction.
|
|
///
|
|
/// If no transaction is active, a new transaction of the specified type is started. The closure
|
|
/// is executed atomically: if it succeeds, the transaction is committed; if it throws, the
|
|
/// transaction is rolled back. If a transaction is already active, the closure is executed
|
|
/// without starting a new one.
|
|
///
|
|
/// - Parameters:
|
|
/// - transaction: The type of transaction to begin (e.g., `deferred`, `immediate`, `exclusive`).
|
|
/// - closure: The database operation to perform within the transaction.
|
|
/// - Returns: The result produced by the closure.
|
|
/// - Throws: Any error thrown by the closure or transaction control statements.
|
|
func perform<T>(
|
|
in transaction: TransactionType,
|
|
closure: Perform<T>
|
|
) rethrows -> T
|
|
}
|