SWIFT-502 Reimplement errors as structs (#374)

Author: patrickfreed

Guides/BSON.md

@@ -64,7 +64,7 @@ func foo(x: BSON, y: BSON) throws {
         print("got something else")
     }
     guard case let .double(d) = y else {
-        throw UserError.invalidArgumentError(message: "y must be a double")
+        throw InvalidArgumentError(message: "y must be a double")
     }
     print(d * d)
 }

Guides/Error-Handling.md

@@ -14,53 +14,56 @@
 * [See Also](#see-also)
 
 ## Error Types
-The driver uses errors to communicate that an operation failed, an assumption wasn't met, or that the user did something incorrectly. Applications that use the driver can in turn catch these errors and respond appropriately without crashing or resulting in an otherwise inconsistent state. To correctly model the different sources of errors, the driver defines three separate types of errors (`ServerError`, `UserError`, `RuntimeError`), each of which conforms to the `MongoError` protocol. These errors are defined in `MongoError.swift` and are outlined here. The documentation for every public function that throws lists some of the errors that could possibly be thrown and the reasons they might be. The errors listed there are not comprehensive but will generally cover the most common cases.
+The driver uses errors to communicate that an operation failed, an assumption wasn't met, or that the user did something incorrectly. Applications that use the driver can in turn catch these errors and respond appropriately without crashing or resulting in an otherwise inconsistent state. To correctly model the different sources of errors, the driver defines three separate caregories of errors (`ServerError`, `UserError`, `RuntimeError`), each of which are protocols that inherit from the `MongoError` protocol. These protocols are defined in `MongoError.swift`, and the structs that conform to them are outlined here. The documentation for every public function that throws lists some of the errors that could possibly be thrown and the reasons they might be. The errors listed there are not comprehensive but will generally cover the most common cases.
 
-**Error Labels:** Some types of errors may contain more specific information describing the context in which they occured. This information is conveyed through the usage of `errorLabels`. Specifically, any server error or connection related error may contain labels.
+**Error Labels:** Some types of errors may contain more specific information describing the context in which they occured. Such errors conform to the `LabeledError` protocol, and the extra information is conveyed through the `errorLabels` property. Specifically, any server error or connection related error may contain labels.
 
 ### Server Errors
-Server errors correspond to failures that occur in the database itself and are returned to the driver via some response to a command. Each `ServerError` case contains at least one error code representing what went wrong on the server.
+Server errors correspond to failures that occur in the database itself and are returned to the driver via some response to a command. Each error that conforms to `ServerError` contains at least one error code representing what went wrong on the server.
 
-For an enumeration of the possible server error codes, [see this list](https://github.com/mongodb/mongo/blob/master/src/mongo/base/error_codes.err).
+For an enumeration of the possible server error codes, [see this list](https://github.com/mongodb/mongo/blob/master/src/mongo/base/error_codes.yml).
 
-The `ServerError` cases are as follows:
-- `.commandError(code: ServerErrorCode, message: String, errorLabels: [String]?)`:
+The possible errors that conform to `ServerError` are as follows:
+- `CommandError`:
     - Thrown when commands experience errors server side that prevent execution.
     - Example command failures include failure to parse, operation aborted by the user, and unexpected errors during execution.
-- `.writeError(writeError: WriteError?, writeConcernError: WriteConcernError?, errorLabels: [String]?)`
-    - Thrown when a single write command fails on the server.
-    - Only one of the two optionals will be non-nil.
-- `.bulkWriteError(writeErrors: [BulkWriteError]?, writeConcernError: WriteConcernError?, result: BulkWriteResult, errorLabels: [String]?)`
+- `WriteError`
+    - Thrown when a single write command fails on the server (e.g. insertOne, updateOne, updateMany).
+- `BulkWriteError`
     - Thrown when the server returns errors as part of an executed bulk write.
-    - If WriteConcernError is populated, writeErrors may not be.
-    - **Note:** `InsertMany` throws a `.bulkWriteError`, _not_ a `.writeError`.
+    - If WriteConcernFailure is populated, writeErrors may not be.
+    - **Note:** `InsertMany` throws a `BulkWriteError`, _not_ a `WriteError`.
 
 
 ### User Errors
 User applications can sometimes cause errors by using the driver incorrectly (e.g. by passing invalid argument combinations). This category of error covers those cases.
 
-The `UserError` cases are as follows:
-- `.logicError(message: String)`
+The possible errors that conform to `UserError` are as follows:
+- `LogicError`
     - Thrown when the user uses the driver incorrectly (e.g. advancing a dead cursor).
-- `.invalidArgument(message: String)`
+- `InvalidArgumentError`
     - Thrown when user passes invalid arguments to some driver function.
 
 
 ### Runtime Errors
 The driver may experience errors that happen at runtime unexpectedly. These errors don't fit neatly into the categories of occurring only server-side or only as part of the user's fault, so they are represented by their own set of cases.
 
 The `RuntimeError` cases are as follows:
-- `.internalError(message: String)`
+- `InternalError`
     - Thrown when something is null when it shouldn't be, the driver has an internal failure, or MongoSwift cannot understand a server response.
-    - This is generally indicative of a bug somewhere in the driver stack or a system related failure (e.g. memory allocation failure). If you experience an error that you think is the result of a bug, please file a bug report on GitHub or our Jira project.
-- `.connectionError(message: String, errorLabels: [String]?)`
+    - This is generally indicative of a bug somewhere in the driver stack or a system related failure (e.g. a memory allocation failure). If you experience an error that you think is the result of a bug, please file a bug report on GitHub or our Jira project.
+- `ConnectionError`
     - Thrown during any connection establishment / socket related errors.
-- `.authenticationError(message: String)`
+    - This error also conforms to `LabeledError`.
+- `AuthenticationError`
     - Thrown when the driver is not authorized to perform a requested command (e.g. due to invalid credentials)
+- `ServerSelectionError`
+    - Thrown when the driver was unable to select a server for an operation (e.g. due to a timeout or unsatisfiable read preference)
+    - See [the official MongoDB documentation](https://docs.mongodb.com/manual/core/read-preference-mechanics/) for more information.
 
 
 ### Encoding/Decoding Errors
-As part of the driver, `BSONEncoder` and `BSONDecoder` are implemented according to the `Encoder` and `Decoder` protocols [defined in Apple's Foundation](https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types). User applications can use them to seamlessly convert between their Swift data structures and the BSON documents stored in the database. While this functionality is part of the public API, the driver itself also makes heavy use of it internally. During any encoding or decoding operations, errors can occur that prevent the data from being written to or read from BSON. In these cases, the driver throws an `EncodingError` or `DecodingError` as appropriate. These error types are not unique to MongoSwift and are commonly used by other encoder implementations, such as Foundation's `JSONEncoder`, so they do not conform to the `MongoError` protocol.
+As part of the driver, `BSONEncoder` and `BSONDecoder` are implemented according to the `Encoder` and `Decoder` protocols [defined in Apple's Foundation](https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types). User applications can use them to seamlessly convert between their Swift data structures and the BSON documents stored in the database. While this functionality is part of the public API, the driver itself also makes heavy use of it internally. During any encoding or decoding operations, errors can occur that prevent the data from being written to or read from BSON. In these cases, the driver throws an `EncodingError` or `DecodingError` as appropriate. These error types are not unique to MongoSwift and are commonly used by other encoder implementations, such as Foundation's `JSONEncoder`, so they do not conform to the `MongoError` protocol or any of the other error protocols defined in the driver.
 
 See the official documentation for both [`EncodingErrors`](https://developer.apple.com/documentation/swift/encodingerror) and [`DecodingErrors`](https://developer.apple.com/documentation/swift/decodingerror) for more information.
 
@@ -93,8 +96,8 @@ do {
 ```swift
 do {
     try db.runCommand(["asdfasdf": "sadfsadfasdf"])
-} catch let ServerError.commandError(code, message, _) {
-    print("Command failed: code: \(code) message: \(message)")
+} catch let commandError as CommandError {
+    print("Command failed: code: \(commandError.code) message: \(commandError.message)")
 } catch { ... }
 ```
 Output:
@@ -108,8 +111,8 @@ Command failed: code: 59 message: no such command: 'asdfasdf'
 do {
     try coll.insertOne(["_id": 1])
     try coll.insertOne(["_id": 1])
-} catch let ServerError.writeError(writeError, _, _) where writeError?.code == 11000 {
-    print("duplicate key error: \(1) \(writeError?.message ?? "")")
+} catch let writeError as WriteError where writeError.writeFailure?.code == 11000 {
+    print("duplicate key error: \(1) \(writeError.writeFailure?.message ?? "")")
 }
 ```
 Output:
@@ -123,11 +126,11 @@ let docs: [Document] = [["_id": 2], ["_id": 1]]
 do {
     try coll.insertOne(["_id": 1])
     try coll.insertMany(docs)
-} catch let ServerError.bulkWriteError(writeErrors, _, result, _) {
-    if let writeErrors = writeErrors {
+} catch let bwe as BulkWriteError {
+    if let writeErrors = bwe.writeFailures {
         writeErrors.forEach { err in print("Write Error inserting \(docs[err.index]), code: \(err.code), message: \(err.message)") }
     }
-    if let result = result {
+    if let result = bwe.result {
         print("Result: ")
         print("nInserted: \(result.insertedCount)")
         print("InsertedIds: \(result.insertedIds)")

Sources/MongoSwift/APM.swift

@@ -136,7 +136,7 @@ public struct CommandFailedEvent: MongoCommandEvent, InitializableFromOpaquePoin
         var error = bson_error_t()
         mongoc_apm_command_failed_get_error(event, &error)
         let reply = Document(copying: mongoc_apm_command_failed_get_reply(event))
-        self.failure = extractMongoError(error: error, reply: reply) // should always return a ServerError.commandError
+        self.failure = extractMongoError(error: error, reply: reply) // should always return a CommandError
         self.requestId = mongoc_apm_command_failed_get_request_id(event)
         self.operationId = mongoc_apm_command_failed_get_operation_id(event)
         self.connectionId = ConnectionId(mongoc_apm_command_failed_get_host(event))