SWIFT-851 Namespace error types (#491)

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 InvalidArgumentError(message: "y must be a double")
+        throw MongoError.InvalidArgumentError(message: "y must be a double")
     }
     print(d * d)
 }

Guides/Error-Handling.md

@@ -15,55 +15,55 @@
 * [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 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.
+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 (`MongoServerError`, `MongoUserError`, `MongoRuntimeError`), each of which are protocols that inherit from the `MongoErrorProtocol` 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.
 
 
 ### 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 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.yml).
 
-The possible errors that conform to `ServerError` are as follows:
-- `CommandError`:
+The possible errors that conform to `MongoServerError` are as follows:
+- `MongoError.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`
+- `MongoError.WriteError`
     - Thrown when a single write command fails on the server (e.g. insertOne, updateOne, updateMany).
-- `BulkWriteError`
+- `MongoError.BulkWriteError`
     - Thrown when the server returns errors as part of an executed bulk write.
     - If WriteConcernFailure is populated, writeErrors may not be.
-    - **Note:** `InsertMany` throws a `BulkWriteError`, _not_ a `WriteError`.
+    - **Note:** `InsertMany` throws a `MongoError.BulkWriteError`, _not_ a `MongoError.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 possible errors that conform to `UserError` are as follows:
-- `LogicError`
+The possible errors that conform to `MongoUserError` are as follows:
+- `MongoError.LogicError`
     - Thrown when the user uses the driver incorrectly (e.g. advancing a dead cursor).
-- `InvalidArgumentError`
+- `MongoError.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`
+The `MongoRuntimeError` cases are as follows:
+- `MongoError.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. 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`
+- `MongoError.ConnectionError`
     - Thrown during any connection establishment / socket related errors.
     - This error also conforms to `LabeledError`.
-- `AuthenticationError`
+- `MongoError.AuthenticationError`
     - Thrown when the driver is not authorized to perform a requested command (e.g. due to invalid credentials)
-- `ServerSelectionError`
+- `MongoError.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.
 
 
 ### 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.
+Some types of errors may contain more specific information describing the context in which they occured. Such errors conform to the `MongoLabeledError` protocol, and the extra information is conveyed through the `errorLabels` property. Specifically, any server error or connection related error may contain labels.
 
 The following error labels are currently defined. Future versions of MongoDB may introduce new labels:
 - `TransientTransactionError`:
@@ -73,7 +73,7 @@ The following error labels are currently defined. Future versions of MongoDB may
 
 
 ### 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 or any of the other error protocols defined in the driver.
+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 `MongoErrorProtocol` 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.
 
@@ -83,14 +83,14 @@ See the official documentation for both [`EncodingErrors`](https://developer.app
 ```swift
 do {
     // something involving the driver
-} catch let error as MongoError {
+} catch let error as MongoErrorProtocol {
     print("Driver error!")
     switch error.self {
-    case let runtimeError as RuntimeError:
+    case let runtimeError as MongoRuntimeError:
         // handle RuntimeError
-    case let serverError as ServerError:
+    case let serverError as MongoServerError:
         // handle ServerError
-    case let userError as UserError:
+    case let userError as MongoUserError:
         // handle UserError
     default:
         // should never get here
@@ -106,7 +106,7 @@ do {
 ```swift
 do {
     try db.runCommand(["asdfasdf": "sadfsadfasdf"])
-} catch let commandError as CommandError {
+} catch let commandError as MongoError.CommandError {
     print("Command failed: code: \(commandError.code) message: \(commandError.message)")
 } catch { ... }
 ```
@@ -121,7 +121,7 @@ Command failed: code: 59 message: no such command: 'asdfasdf'
 do {
     try coll.insertOne(["_id": 1])
     try coll.insertOne(["_id": 1])
-} catch let writeError as WriteError where writeError.writeFailure?.code == 11000 {
+} catch let writeError as MongoError.WriteError where writeError.writeFailure?.code == 11000 {
     print("duplicate key error: \(1) \(writeError.writeFailure?.message ?? "")")
 }
 ```
@@ -136,7 +136,7 @@ let docs: [Document] = [["_id": 2], ["_id": 1]]
 do {
     try coll.insertOne(["_id": 1])
     try coll.insertMany(docs)
-} catch let bwe as BulkWriteError {
+} catch let bwe as MongoError.BulkWriteError {
     if let writeErrors = bwe.writeFailures {
         writeErrors.forEach { err in print("Write Error inserting \(docs[err.index]), code: \(err.code), message: \(err.message)") }
     }

Sources/MongoSwift/APM.swift

@@ -222,8 +222,8 @@ public struct CommandFailedEvent: MongoSwiftEvent, CommandEventProtocol {
     /// The command name.
     public let commandName: String
 
-    /// The failure, represented as a MongoError.
-    public let failure: MongoError
+    /// The failure, represented as a MongoErrorProtocol.
+    public let failure: MongoErrorProtocol
 
     /// The client generated request id.
     public let requestID: Int64
@@ -588,7 +588,7 @@ public struct ServerHeartbeatFailedEvent: MongoSwiftEvent {
     public let duration: Int
 
     /// The failure.
-    public let failure: MongoError
+    public let failure: MongoErrorProtocol
 
     /// The address of the server.
     public let serverAddress: ServerAddress

Sources/MongoSwift/BSON/BSONDecoder.swift

@@ -360,7 +360,12 @@ extension _BSONDecoder {
         case .binary:
             let binary = try self.unboxCustom(value) { $0.binaryValue }
             guard let data = binary.data.getBytes(at: 0, length: binary.data.writerIndex) else {
-                throw InternalError(message: "Cannot read \(binary.data.writerIndex) bytes from Binary.data")
+                throw DecodingError.dataCorrupted(
+                    DecodingError.Context(
+                        codingPath: self.codingPath,
+                        debugDescription: "Cannot read \(binary.data.writerIndex) bytes from Binary.data"
+                    )
+                )
             }
             return Data(data)
         case .base64:

Sources/MongoSwift/BSON/BSONDocument.swift

@@ -9,7 +9,7 @@ internal typealias MutableBSONPointer = UnsafeMutablePointer<bson_t>
 public struct BSONDocument {
     /// Error thrown when BSON buffer is too small.
     internal static let BSONBufferTooSmallError =
-        InternalError(message: "BSON buffer is unexpectedly too small (< 5 bytes)")
+        MongoError.InternalError(message: "BSON buffer is unexpectedly too small (< 5 bytes)")
 
     /// The storage backing a `BSONDocument`.
     private class Storage {
@@ -145,10 +145,10 @@ extension BSONDocument {
      * presence first.
      *
      * - Throws:
-     *   - `InternalError` if the new value is an `Int` and cannot be written to BSON.
-     *   - `LogicError` if the new value is a `BSONDecimal128` or `BSONObjectID` and is improperly formatted.
-     *   - `LogicError` if the new value is an `Array` and it contains a non-`BSONValue` element.
-     *   - `InternalError` if the underlying `bson_t` would exceed the maximum size by encoding this
+     *   - `MongoError.InternalError` if the new value is an `Int` and cannot be written to BSON.
+     *   - `MongoError.LogicError` if the new value is a `BSONDecimal128` or `BSONObjectID` and is improperly formatted.
+     *   - `MongoError.LogicError` if the new value is an `Array` and it contains a non-`BSONValue` element.
+     *   - `MongoError.InternalError` if the underlying `bson_t` would exceed the maximum size by encoding this
      *     key-value pair.
      */
     internal mutating func setValue(for key: String, to newValue: BSON, checkForKey: Bool = true) throws {
@@ -210,7 +210,7 @@ extension BSONDocument {
     /// Retrieves the value associated with `for` as a `BSON?`, which can be nil if the key does not exist in the
     /// `BSONDocument`.
     ///
-    /// - Throws: `InternalError` if the BSON buffer is too small (< 5 bytes).
+    /// - Throws: `MongoError.InternalError` if the BSON buffer is too small (< 5 bytes).
     internal func getValue(for key: String) throws -> BSON? {
         guard let iter = BSONDocumentIterator(over: self) else {
             throw BSONDocument.BSONBufferTooSmallError
@@ -232,7 +232,7 @@ extension BSONDocument {
             }
         }
         guard success else {
-            throw InternalError(
+            throw MongoError.InternalError(
                 message: "Failed to merge \(doc) with \(self). This is likely due to " +
                     "the merged document being too large."
             )
@@ -255,15 +255,15 @@ extension BSONDocument {
     /// excluding a non-zero number of keys
     internal func copyElements(to otherDoc: inout BSONDocument, excluding keys: [String]) throws {
         guard !keys.isEmpty else {
-            throw InternalError(message: "No keys to exclude, use 'bson_copy' instead")
+            throw MongoError.InternalError(message: "No keys to exclude, use 'bson_copy' instead")
         }
 
         let cStrings: [ContiguousArray<CChar>] = keys.map { $0.utf8CString }
 
         var cPtrs: [UnsafePointer<CChar>] = try cStrings.map { cString in
             let bufferPtr: UnsafeBufferPointer<CChar> = cString.withUnsafeBufferPointer { $0 }
             guard let cPtr = bufferPtr.baseAddress else {
-                throw InternalError(message: "Failed to copy strings")
+                throw MongoError.InternalError(message: "Failed to copy strings")
             }
             return cPtr
         }
@@ -373,16 +373,16 @@ extension BSONDocument {
      * - Returns: the parsed `BSONDocument`
      *
      * - Throws:
-     *   - A `InvalidArgumentError` if the data passed in is invalid JSON.
+     *   - A `MongoError.InvalidArgumentError` if the data passed in is invalid JSON.
      */
     public init(fromJSON: Data) throws {
         self._storage = Storage(stealing: try fromJSON.withUnsafeBytePointer { bytes in
             var error = bson_error_t()
             guard let bson = bson_new_from_json(bytes, fromJSON.count, &error) else {
                 if error.domain == BSON_ERROR_JSON {
-                    throw InvalidArgumentError(message: "Invalid JSON: \(toErrorString(error))")
+                    throw MongoError.InvalidArgumentError(message: "Invalid JSON: \(toErrorString(error))")
                 }
-                throw InternalError(message: toErrorString(error))
+                throw MongoError.InternalError(message: toErrorString(error))
             }
 
             return bson
@@ -391,7 +391,7 @@ extension BSONDocument {
 
     /// Convenience initializer for constructing a `BSONDocument` from a `String`.
     /// - Throws:
-    ///   - A `InvalidArgumentError` if the string passed in is invalid JSON.
+    ///   - A `MongoError.InvalidArgumentError` if the string passed in is invalid JSON.
     public init(fromJSON json: String) throws {
         // `String`s are Unicode under the hood so force unwrap always succeeds.
         // see https://www.objc.io/blog/2018/02/13/string-to-data-and-back/
@@ -401,15 +401,15 @@ extension BSONDocument {
     /**
      * Constructs a `BSONDocument` from raw BSON `Data`.
      * - Throws:
-     *   - A `InvalidArgumentError` if `bson` is too short or too long to be valid BSON.
-     *   - A `InvalidArgumentError` if the first four bytes of `bson` do not contain `bson.count`.
-     *   - A `InvalidArgumentError` if the final byte of `bson` is not a null byte.
+     *   - A `MongoError.InvalidArgumentError` if `bson` is too short or too long to be valid BSON.
+     *   - A `MongoError.InvalidArgumentError` if the first four bytes of `bson` do not contain `bson.count`.
+     *   - A `MongoError.InvalidArgumentError` if the final byte of `bson` is not a null byte.
      * - SeeAlso: http://bsonspec.org/
      */
     public init(fromBSON bson: Data) throws {
         self._storage = Storage(stealing: try bson.withUnsafeBytePointer { bytes in
             guard let data = bson_new_from_data(bytes, bson.count) else {
-                throw InvalidArgumentError(message: "Invalid BSON data")
+                throw MongoError.InvalidArgumentError(message: "Invalid BSON data")
             }
             return data
         })
@@ -520,7 +520,7 @@ extension BSONDocument: BSONValue {
             bson_iter_document(iterPtr, &length, document)
 
             guard let docData = bson_new_from_data(document.pointee, Int(length)) else {
-                throw InternalError(message: "Failed to create a Document from iterator")
+                throw MongoError.InternalError(message: "Failed to create a Document from iterator")
             }
 
             return self.init(stealing: docData)

Sources/MongoSwift/BSON/BSONDocumentIterator.swift

@@ -102,10 +102,10 @@ public class BSONDocumentIterator: IteratorProtocol {
     /// Returns the current value (equivalent to the `currentValue` property) or throws on error.
     ///
     /// - Throws:
-    ///   - `InternalError` if the current value of this `BSONDocumentIterator` cannot be decoded to BSON.
+    ///   - `MongoError.InternalError` if the current value of this `BSONDocumentIterator` cannot be decoded to BSON.
     internal func safeCurrentValue() throws -> BSON {
         guard let bsonType = BSONDocumentIterator.bsonTypeMap[currentType] else {
-            throw InternalError(
+            throw MongoError.InternalError(
                 message: "Unknown BSONType for iterator's current value with type: \(self.currentType)"
             )
         }
@@ -177,8 +177,8 @@ public class BSONDocumentIterator: IteratorProtocol {
      * Overwrites the current value of this `BSONDocumentIterator` with the supplied value.
      *
      * - Throws:
-     *   - `InternalError` if the new value is an `Int` and cannot be written to BSON.
-     *   - `LogicError` if the new value is a `BSONDecimal128` or `BSONObjectID` and is improperly formatted.
+     *   - `MongoError.InternalError` if the new value is an `Int` and cannot be written to BSON.
+     *   - `MongoError.LogicError` if the new value is a `BSONDecimal128` or `BSONObjectID` and is improperly formatted.
      */
     internal func overwriteCurrentValue(with newValue: Overwritable) throws {
         let newValueType = type(of: newValue).bsonType