SWIFT-1102 Support snapshot reads on secondaries (#689)

Author: kmahar

Sources/MongoSwift/Operations/StartSessionOperation.swift

@@ -3,9 +3,13 @@ import Foundation
 
 /// Options to use when creating a `ClientSession`.
 public struct ClientSessionOptions {
-    /// Whether to enable causal consistency for this session. By default, causal consistency is enabled.
-    ///
-    /// - SeeAlso: https://docs.mongodb.com/manual/core/read-isolation-consistency-recency/
+    /**
+     * Whether to enable causal consistency for this session. By default, if `snapshot` is not set to true, then
+     * causal consistency is enabled. Note that setting this option to true is incompatible with setting `snapshot` to
+     * true.
+     *
+     * - SeeAlso: https://docs.mongodb.com/manual/core/read-isolation-consistency-recency/
+     */
     public var causalConsistency: Bool?
 
     /// The default `TransactionOptions` to use for transactions started on this session.
@@ -16,10 +20,24 @@ public struct ClientSessionOptions {
     /// applicable (e.g. write concern).
     public var defaultTransactionOptions: TransactionOptions?
 
+    /**
+     * If true, then all reads performed using this session will read from the same snapshot. This option defaults to
+     * false.
+     *
+     * Note that setting this option to true is incompatible with setting `causalConsistency` to true.
+     * - SeeAlso: https://docs.mongodb.com/manual/reference/read-concern-snapshot/
+     */
+    public var snapshot: Bool?
+
     /// Convenience initializer allowing any/all parameters to be omitted.
-    public init(causalConsistency: Bool? = nil, defaultTransactionOptions: TransactionOptions? = nil) {
+    public init(
+        causalConsistency: Bool? = nil,
+        defaultTransactionOptions: TransactionOptions? = nil,
+        snapshot: Bool? = nil
+    ) {
         self.causalConsistency = causalConsistency
         self.defaultTransactionOptions = defaultTransactionOptions
+        self.snapshot = snapshot
     }
 }
 
@@ -28,11 +46,17 @@ public struct ClientSessionOptions {
 private func withSessionOpts<T>(
     wrapping options: ClientSessionOptions?,
     _ body: (OpaquePointer) throws -> T
-) rethrows -> T {
+) throws -> T {
     // swiftlint:disable:next force_unwrapping
     let opts = mongoc_session_opts_new()! // always returns a value
     defer { mongoc_session_opts_destroy(opts) }
 
+    if options?.causalConsistency == true && options?.snapshot == true {
+        throw MongoError.InvalidArgumentError(
+            message: "Only one of causalConsistency and snapshot can be set to true."
+        )
+    }
+
     if let causalConsistency = options?.causalConsistency {
         mongoc_session_opts_set_causal_consistency(opts, causalConsistency)
     }
@@ -41,6 +65,10 @@ private func withSessionOpts<T>(
         mongoc_session_opts_set_default_transaction_opts(opts, $0)
     }
 
+    if let snapshot = options?.snapshot {
+        mongoc_session_opts_set_snapshot(opts, snapshot)
+    }
+
     return try body(opts)
 }
 

Tests/LinuxMain.swift

@@ -360,6 +360,8 @@ extension SyncClientSessionTests {
         ("testCausalConsistency", testCausalConsistency),
         ("testCausalConsistencyStandalone", testCausalConsistencyStandalone),
         ("testCausalConsistencyAnyTopology", testCausalConsistencyAnyTopology),
+        ("testSessionsUnified", testSessionsUnified),
+        ("testSnapshotSessionsProse", testSnapshotSessionsProse),
     ]
 }
 

Tests/MongoSwiftSyncTests/ClientSessionTests.swift

@@ -524,4 +524,26 @@ final class SyncClientSessionTests: MongoSwiftTestCase {
             expect(session.operationTime).to(beNil())
         }
     }
+
+    func testSessionsUnified() throws {
+        let tests = try retrieveSpecTestFiles(
+            specName: "sessions",
+            subdirectory: "unified",
+            asType: UnifiedTestFile.self
+        )
+        let runner = try UnifiedTestRunner()
+        try runner.runFiles(tests.map { $0.1 })
+    }
+
+    func testSnapshotSessionsProse() throws {
+        /// 1. Setting both snapshot and causalConsistency to true is not allowed
+        try self.withTestNamespace { client, _, _ in
+            let invalidOpts = ClientSessionOptions(causalConsistency: true, snapshot: true)
+            let session = client.startSession(options: invalidOpts)
+            // We don't actually start the underlying libmongoc session until the ClientSession is used, so we need to
+            // try to do an operation to generate an error.
+            expect(try client.listDatabaseNames(session: session))
+                .to(throwError(errorType: MongoError.InvalidArgumentError.self))
+        }
+    }
 }

Tests/MongoSwiftSyncTests/SpecTestRunner/CodableExtensions.swift

@@ -69,15 +69,20 @@ extension ClientSessionOptions: StrictDecodable {
 
         let container = try decoder.container(keyedBy: CodingKeys.self)
         let causalConsistency = try container.decodeIfPresent(Bool.self, forKey: .causalConsistency)
+        let snapshot = try container.decodeIfPresent(Bool.self, forKey: .snapshot)
         let defaultTransactionOptions = try container.decodeIfPresent(
             TransactionOptions.self,
             forKey: .defaultTransactionOptions
         )
-        self.init(causalConsistency: causalConsistency, defaultTransactionOptions: defaultTransactionOptions)
+        self.init(
+            causalConsistency: causalConsistency,
+            defaultTransactionOptions: defaultTransactionOptions,
+            snapshot: snapshot
+        )
     }
 
     internal enum CodingKeys: String, CodingKey, CaseIterable {
-        case causalConsistency, defaultTransactionOptions
+        case causalConsistency, defaultTransactionOptions, snapshot
     }
 }
 

Tests/MongoSwiftSyncTests/UnifiedTestRunner/UnifiedClientOperations.swift

@@ -25,11 +25,19 @@ struct AssertNumberConnectionsCheckedOut: UnifiedOperationProtocol {
 }
 
 struct UnifiedListDatabases: UnifiedOperationProtocol {
-    static var knownArguments: Set<String> { [] }
+    /// Optional identifier for a session entity to use.
+    let session: String?
+
+    static var knownArguments: Set<String> { ["session"] }
+
+    init() {
+        self.session = nil
+    }
 
     func execute(on object: UnifiedOperation.Object, context: Context) throws -> UnifiedOperationResult {
         let testClient = try context.entities.getEntity(from: object).asTestClient()
-        let dbSpecs = try testClient.client.listDatabases()
+        let session = try context.entities.resolveSession(id: self.session)
+        let dbSpecs = try testClient.client.listDatabases(session: session)
         let encoded = try BSONEncoder().encode(dbSpecs)
         return .bson(.array(encoded.map { .document($0) }))
     }

Tests/MongoSwiftSyncTests/UnifiedTestRunner/UnifiedCollectionOperations.swift

@@ -565,13 +565,17 @@ struct UnifiedCountDocuments: UnifiedOperationProtocol {
     /// Filter for the query.
     let filter: BSONDocument
 
+    /// Optional identifier for a session entity to use.
+    let session: String?
+
     static var knownArguments: Set<String> {
-        ["filter"]
+        ["filter", "session"]
     }
 
     func execute(on object: UnifiedOperation.Object, context: Context) throws -> UnifiedOperationResult {
         let collection = try context.entities.getEntity(from: object).asCollection()
-        let result = try collection.countDocuments(filter)
+        let session = try context.entities.resolveSession(id: self.session)
+        let result = try collection.countDocuments(filter, session: session)
         return .bson(BSON(result))
     }
 }
@@ -605,13 +609,17 @@ struct UnifiedDistinct: UnifiedOperationProtocol {
     /// Filter for the query.
     let filter: BSONDocument
 
+    /// Optional identifier for a session entity to use.
+    let session: String?
+
     static var knownArguments: Set<String> {
-        ["fieldName", "filter"]
+        ["fieldName", "filter", "session"]
     }
 
     func execute(on object: UnifiedOperation.Object, context: Context) throws -> UnifiedOperationResult {
         let collection = try context.entities.getEntity(from: object).asCollection()
-        let result = try collection.distinct(fieldName: self.fieldName, filter: filter)
+        let session = try context.entities.resolveSession(id: self.session)
+        let result = try collection.distinct(fieldName: self.fieldName, filter: filter, session: session)
         return .bson(.array(result))
     }
 }

Tests/MongoSwiftSyncTests/UnifiedTestRunner/UnifiedDatabaseOperations.swift

@@ -61,8 +61,11 @@ struct UnifiedRunCommand: UnifiedOperationProtocol {
     /// The command to run.
     let command: BSONDocument
 
+    /// Optional identifier for a session entity to use.
+    let session: String?
+
     static var knownArguments: Set<String> {
-        ["commandName", "command"]
+        ["commandName", "command", "session"]
     }
 
     func execute(on object: UnifiedOperation.Object, context: Context) throws -> UnifiedOperationResult {
@@ -76,14 +79,15 @@ struct UnifiedRunCommand: UnifiedOperationProtocol {
             }
         }
         let db = try context.entities.getEntity(from: object).asDatabase()
-        try db.runCommand(orderedCommand)
+        let session = try context.entities.resolveSession(id: self.session)
+        try db.runCommand(orderedCommand, session: session)
         return .none
     }
 }
 
 struct UnifiedListCollections: UnifiedOperationProtocol {
     /// Filter to use for the command.
-    let filter: BSONDocument
+    let filter: BSONDocument?
 
     /// Optional identifier for a session entity to use.
     let session: String?
@@ -98,7 +102,7 @@ struct UnifiedListCollections: UnifiedOperationProtocol {
         self.options = try decoder.singleValueContainer().decode(ListCollectionsOptions.self)
         let container = try decoder.container(keyedBy: CodingKeys.self)
         self.session = try container.decodeIfPresent(String.self, forKey: .session)
-        self.filter = try container.decode(BSONDocument.self, forKey: .filter)
+        self.filter = try container.decodeIfPresent(BSONDocument.self, forKey: .filter)
     }
 
     static var knownArguments: Set<String> {

Tests/MongoSwiftSyncTests/UnifiedTestRunner/UnifiedOperation.swift

@@ -219,7 +219,11 @@ struct UnifiedOperation: Decodable {
         case "listCollections":
             self.operation = try container.decode(UnifiedListCollections.self, forKey: .arguments)
         case "listDatabases":
-            self.operation = UnifiedListDatabases()
+            if container.allKeys.contains(.arguments) {
+                self.operation = try container.decode(UnifiedListDatabases.self, forKey: .arguments)
+            } else {
+                self.operation = UnifiedListDatabases()
+            }
         case "listIndexes":
             self.operation = try container.decode(UnifiedListIndexes.self, forKey: .arguments)
         case "replaceOne":