From 8bcbff74b4052dccd04f4b89288cd9be43254696 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 30 Jul 2021 11:19:37 -0400 Subject: [PATCH 01/13] docs: Update error documentation --- docs/errors.md | 109 ++++++++++++++++++++++++++----------------------- 1 file changed, 57 insertions(+), 52 deletions(-) diff --git a/docs/errors.md b/docs/errors.md index f008c365651..e10f9f82c37 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -6,7 +6,7 @@ **Advisory Group**: Daria Purdue, Eric Adum, Neal Beeken -### Contents +## Contents - [Introduction](#Introduction) - [Errors](#errors) @@ -30,12 +30,13 @@ - [`MongoNetworkError`](#MongoNetworkError-1) - [`MongoNetworkTimeoutError`](#MongoNetworkTimeoutError-1) -# Errors +## Errors All errors are derived from the `MongoError` class which should **never** be instantiated. -There are four main error classes which stem from `MongoError`: `MongoDriverError`, `MongoNetworkError`, `MongoServerError`, and `MongoSystemError`. +There are four main error classes which stem from `MongoError`: `MongoDriverError`, +`MongoNetworkError`, `MongoServerError`, and `MongoSystemError`. -## `MongoError` +### `MongoError` The base class from which all errors in the Node driver subclass. `MongoError` should **never** be be directly instantiated. @@ -48,10 +49,9 @@ Children of `MongoError` include: - [`MongoServerError`](#MongoServerError) - [`MongoSystemError`](#MongoSystemError) -## `MongoDriverError` +### `MongoDriverError` -This class represents errors which originate in the driver itself or in the user's use of the driver. -This class should **never** be directly instantiated. +This class represents errors which originate in the driver itself or in the user's use of the driver. This class should **never** be directly instantiated. Its children are the main classes of errors that most users will interact with: [**`MongoAPIError`**](#MongoAPIError) and [**`MongoRuntimeError`**](#MongoRuntimeError). ### `MongoAPIError` @@ -74,8 +74,45 @@ Children of `MongoAPIError` include: - Thrown when a user fails to provide authentication credentials before attempting to connect to the mongo server. - #### `MongoMissingDependencyError` + - Thrown when a required module or dependency is not present. +- #### `MongoTransactionError` + + - Thrown when the user makes a mistake in the usage of transactions (e.g.: attempting to commit a transaction with a readPreference other than primary). + +- #### `MongoNotConnectedError` + + - Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance. + +- #### `MongoExpiredSessionError` + + - Thrown when the user attempts to operate on a session that has expired or has been closed. + +- #### `MongoServerClosedError` + + - Thrown when an attempt is made to operate on a closed server. + +- #### `MongoTopologyClosedError` + + - Thrown when an attempt is made to operate on a dropped, or otherwise unavailable, database. + +- #### `MongoTailableCursorError` + + - Thrown when the user calls a function or method that is not supported on a tailable cursor. + +- #### `MongoCursorInUseError` + + - Thrown when the user attempts to add options to an already initialized cursor. + +- #### `MongoCursorExhaustedError` + + - Thrown when an attempt is made to read from a cursor that has been exhausted. + +- #### `MongoBatchReExecutionError` + + - Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. + ### `MongoRuntimeError` This class represents errors which occur when the driver encounters unexpected input or reaches an unexpected/invalid internal state. @@ -92,18 +129,6 @@ _MongoRuntimeError children (pt 3)_ Children of `MongoRuntimeError` include: -- #### `MongoTransactionError` - - - Thrown when the user makes a mistake in the usage of transactions (e.g.: attempting to commit a transaction with a readPreference other than primary). - -- #### `MongoNotConnectedError` - - - Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance. - -- #### `MongoKerberosError` - - - Thrown when the user attempts to authenticate via Kerberos, but fails to connect to the Kerberos client. - - #### `MongoCompressionError` - Thrown when the driver fails to compress data before sending it to the server. @@ -112,47 +137,27 @@ Children of `MongoRuntimeError` include: - Thrown when the driver fails to decompress data received from the server -- #### `MongoExpiredSessionError` - - - Thrown when the user attempts to operate on a session that has expired or has been closed. - - #### `MongoURIError` - Thrown when a user supplies an incorrect URI to the driver. -- #### `MongoResourceClosedError` +- #### `MongoChangeStreamError` - - Thrown when there is an attempt to access a resource which has already been or will be closed/destroyed. - - Children of this error class include: - - **`MongoServerClosedError`**: Thrown when an attempt is made to operate on a closed server. - - **`MongoStreamClosedError`**: Thrown when an attempt is made to operate on a closed stream. - - **`MongoTopologyClosedError`**: Thrown when an attempt is made to operate on a dropped, or otherwise unavailable, database. + - Thrown when an error is encountered when operating on a ChangeStream. -- #### `MongoCursorError` +- #### `MongoGridFSStreamError` - - Thrown when the user incorrectly uses a cursor object. - - Children of this error class include: - - **`MongoTailableCursorError`**: Thrown when the user calls a function or method that is not supported on a tailable cursor. - - **`MongoCursorInUseError`**: Thrown when the user attempts to add options to an already initialized cursor. - - **`MongoCursorExhaustedError`**: Thrown when an attempt is made to read from a cursor that has been exhausted. + - Thrown when an unexpected state is reached when operating on a GridFSStream. -- #### `MongoStreamError` +- #### `MongoGridFSChunkError` - - Thrown when a stream operation fails to execute. - - Children of this error class include: - - **`MongoChangeStreamError`**: Thrown when an error is encountered when operating on a ChangeStream. - - **`MongoGridFSStreamError`**: Thrown when an unexpected state is reached when operating on a GridFSStream. - - **`MongoGridFSChunkError`**: Thrown when a malformed or invalid chunk is encountered when reading from a GridFSStream. - -- #### `MongoBatchReExecutionError` - - - Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. + - Thrown when a malformed or invalid chunk is encountered when reading from a GridFSStream. - #### `MongoServerSelectionError` - Thrown when the driver fails to select a server to complete an operation. -## `MongoNetworkError` +### `MongoNetworkError` These are errors which prevent the driver from connecting to a mongo server instance. Children of this class include: @@ -160,15 +165,15 @@ These are errors which prevent the driver from connecting to a mongo server inst - Thrown when a timeout expires while attempting to connect to the mongo server -## `MongoServerError` +### `MongoServerError` These are errors which wrap error responses received from the server. -## `MongoSystemError` +### `MongoSystemError` These are errors which originate from faulty environment setup. -# Test Plan +## Test Plan The test plan consists of a series of prose tests. As numerous errors are being introduced, select classes will be tested. @@ -178,7 +183,7 @@ The classes to be tested will be selected based on two characteristics: 2. The **scope** of the error. Errors that tackle a large subset of issues, including but not limited to `MongoServerError` and `MongoSystemError`, will _not_ be a part of the test plan. 3. The **existing coverage** of the error. Errors that are already covered in existing tests will _not_ be a part of the test plan to avoid redundancy. -## `MongoAPIError` +### `MongoAPIError` #### `MongoInvalidArgumentError` @@ -190,7 +195,7 @@ The classes to be tested will be selected based on two characteristics: - Fail to provide credentials when authenticating with the x509 mechanism. - Assert that `MongoMissingCredentialsError` is thrown. -## `MongoRuntimeError` +### `MongoRuntimeError` #### `MongoNotConnectedError` @@ -217,7 +222,7 @@ The classes to be tested will be selected based on two characteristics: - Attempt to continue reading a cursor after it has reached the end of the batch. - Assert that `MongoCursorExhaustedError` is thrown. -## `MongoNetworkError` +### `MongoNetworkError` #### `MongoNetworkTimeoutError` From ab554e99548ea91cf4bcd80250dfde3df81e85e8 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 30 Jul 2021 13:40:28 -0400 Subject: [PATCH 02/13] docs: Update diagrams(wip) --- docs/charts/imgs/MongoAPIError.svg | 5 +---- docs/charts/imgs/MongoError.svg | 5 +---- docs/charts/imgs/MongoRuntimeError_0.svg | 5 +---- docs/charts/imgs/MongoRuntimeError_1.svg | 4 ---- docs/charts/imgs/MongoRuntimeError_2.svg | 4 ---- docs/charts/mermaid/MongoAPIError.mmd | 15 +++++++++++++++ docs/charts/mermaid/MongoRuntimeError_0.mmd | 13 +++++-------- docs/charts/mermaid/MongoRuntimeError_1.mmd | 10 ---------- docs/charts/mermaid/MongoRuntimeError_2.mmd | 9 --------- 9 files changed, 23 insertions(+), 47 deletions(-) delete mode 100644 docs/charts/imgs/MongoRuntimeError_1.svg delete mode 100644 docs/charts/imgs/MongoRuntimeError_2.svg delete mode 100644 docs/charts/mermaid/MongoRuntimeError_1.mmd delete mode 100644 docs/charts/mermaid/MongoRuntimeError_2.mmd diff --git a/docs/charts/imgs/MongoAPIError.svg b/docs/charts/imgs/MongoAPIError.svg index 9d46d069617..71ec32e5387 100644 --- a/docs/charts/imgs/MongoAPIError.svg +++ b/docs/charts/imgs/MongoAPIError.svg @@ -1,4 +1 @@ -
MongoAPIError
MongoInvalidArgumentError
MongoCompatibilityError
MongoMissingCredentialsError
MongoMissingDependencyError
 \ No newline at end of file +
MongoAPIError
MongoInvalidArgumentError
MongoCompatibilityError
MongoMissingCredentialsError
MongoMissingDependencyError
MongoExpiredSessionError
MongoTransactionError
MongoTailableCursorError
MongoCursorExhaustedError
MongoCursorInUseError
MongoServerClosedError
MongoTopologyClosedError
MongoNotConnectedError
MongoBatchReExecutionError
MongoConnectionStringError
MongoConnectionPoolClosedError
MongoMessageStreamParseError
MongoGridFSStreamClosedError
MongoChangeStreamClosedError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoError.svg b/docs/charts/imgs/MongoError.svg index 41f37b7adb0..458ae5a8c7a 100644 --- a/docs/charts/imgs/MongoError.svg +++ b/docs/charts/imgs/MongoError.svg @@ -1,4 +1 @@ -
MongoError
MongoDriverError
MongoNetworkError
MongoServerError
MongoSystemError
MongoAPIError
MongoRuntimeError
 \ No newline at end of file +
MongoError
MongoDriverError
MongoNetworkError
MongoServerError
MongoSystemError
MongoAPIError
MongoRuntimeError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoRuntimeError_0.svg b/docs/charts/imgs/MongoRuntimeError_0.svg index 6a0961223a3..4f49b4c63e1 100644 --- a/docs/charts/imgs/MongoRuntimeError_0.svg +++ b/docs/charts/imgs/MongoRuntimeError_0.svg @@ -1,4 +1 @@ -
MongoRuntimeError
MongoBatchReExecutionError
MongoCursorError
MongoInvalidClassInstantiationError
MongoNotConnectedError
MongoTailableCursorError
MongoCursorInUseError
MongoCursorExhaustedError
 \ No newline at end of file +
MongoRuntimeError
MongoCompressionError
MongoDecompressionError
MongoGridFSChunkError
MongoGridFSStreamError
MongoChangeStreamError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoRuntimeError_1.svg b/docs/charts/imgs/MongoRuntimeError_1.svg deleted file mode 100644 index 41dd25f7a6a..00000000000 --- a/docs/charts/imgs/MongoRuntimeError_1.svg +++ /dev/null @@ -1,4 +0,0 @@ -
MongoRuntimeError
MongoURIError
MongoServerSelectionError
MongoStreamError
MongoCompressionError
MongoDecompressionError
MongoChangeStreamError
MongoGridFSStreamError
MongoGridFSChunkError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoRuntimeError_2.svg b/docs/charts/imgs/MongoRuntimeError_2.svg deleted file mode 100644 index 7d796039bcc..00000000000 --- a/docs/charts/imgs/MongoRuntimeError_2.svg +++ /dev/null @@ -1,4 +0,0 @@ -
MongoRuntimeError
MongoTransactionError
MongoExpiredSessionError
MongoKerberosError
MongoResourceClosedError
MongoServerClosedError
MongoStreamClosedError
MongoTopologyClosedError
 \ No newline at end of file diff --git a/docs/charts/mermaid/MongoAPIError.mmd b/docs/charts/mermaid/MongoAPIError.mmd index 7275b04dc46..0ff96cb6f43 100644 --- a/docs/charts/mermaid/MongoAPIError.mmd +++ b/docs/charts/mermaid/MongoAPIError.mmd @@ -3,3 +3,18 @@ graph TD MongoAPIError --> MongoCompatibilityError MongoAPIError --> MongoMissingCredentialsError MongoAPIError --> MongoMissingDependencyError + + MongoAPIError --> MongoExpiredSessionError + MongoAPIError --> MongoTransactionError + MongoAPIError --> MongoTailableCursorError + MongoAPIError --> MongoCursorExhaustedError + MongoAPIError --> MongoCursorInUseError + MongoAPIError --> MongoServerClosedError + MongoAPIError --> MongoTopologyClosedError + MongoAPIError --> MongoNotConnectedError + MongoAPIError --> MongoBatchReExecutionError + MongoAPIError --> MongoConnectionStringError + MongoAPIError --> MongoConnectionPoolClosedError + MongoAPIError --> MongoMessageStreamParseError + MongoAPIError --> MongoGridFSStreamClosedError + MongoAPIError --> MongoChangeStreamClosedError diff --git a/docs/charts/mermaid/MongoRuntimeError_0.mmd b/docs/charts/mermaid/MongoRuntimeError_0.mmd index 2646b76d906..cd5ac025f01 100644 --- a/docs/charts/mermaid/MongoRuntimeError_0.mmd +++ b/docs/charts/mermaid/MongoRuntimeError_0.mmd @@ -1,9 +1,6 @@ graph TD - MongoRuntimeError --> MongoBatchReExecutionError - MongoRuntimeError --> MongoCursorError - MongoRuntimeError --> MongoInvalidClassInstantiationError - MongoRuntimeError --> MongoNotConnectedError - - MongoCursorError --> MongoTailableCursorError - MongoCursorError --> MongoCursorInUseError - MongoCursorError --> MongoCursorExhaustedError + MongoRuntimeError --> MongoCompressionError + MongoRuntimeError --> MongoDecompressionError + MongoRuntimeError --> MongoGridFSChunkError + MongoRuntimeError --> MongoGridFSStreamError + MongoRuntimeError --> MongoChangeStreamError diff --git a/docs/charts/mermaid/MongoRuntimeError_1.mmd b/docs/charts/mermaid/MongoRuntimeError_1.mmd deleted file mode 100644 index 7dfd97740ac..00000000000 --- a/docs/charts/mermaid/MongoRuntimeError_1.mmd +++ /dev/null @@ -1,10 +0,0 @@ -graph TD - MongoRuntimeError --> MongoURIError - MongoRuntimeError --> MongoServerSelectionError - MongoRuntimeError --> MongoStreamError - MongoRuntimeError --> MongoCompressionError - MongoRuntimeError --> MongoDecompressionError - - MongoStreamError --> MongoChangeStreamError - MongoStreamError --> MongoGridFSStreamError - MongoStreamError --> MongoGridFSChunkError diff --git a/docs/charts/mermaid/MongoRuntimeError_2.mmd b/docs/charts/mermaid/MongoRuntimeError_2.mmd deleted file mode 100644 index 632d3326916..00000000000 --- a/docs/charts/mermaid/MongoRuntimeError_2.mmd +++ /dev/null @@ -1,9 +0,0 @@ -graph TD - MongoRuntimeError --> MongoTransactionError - MongoRuntimeError --> MongoExpiredSessionError - MongoRuntimeError --> MongoKerberosError - MongoRuntimeError --> MongoResourceClosedError - - MongoResourceClosedError --> MongoServerClosedError - MongoResourceClosedError --> MongoStreamClosedError - MongoResourceClosedError --> MongoTopologyClosedError From 9a9dc0624dbede6971718d827135cf7984e83f71 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 3 Aug 2021 14:20:50 -0400 Subject: [PATCH 03/13] wip: updating docs --- docs/charts/imgs/MongoAPIError.svg | 2 +- docs/charts/imgs/MongoAPIError_1.svg | 1 + docs/charts/imgs/MongoAPIError_2.svg | 1 + docs/charts/imgs/MongoError.svg | 2 +- docs/charts/imgs/MongoRuntimeError_0.svg | 2 +- docs/charts/mermaid/MongoAPIError.mmd | 13 --- docs/charts/mermaid/MongoAPIError_1.mmd | 7 ++ docs/charts/mermaid/MongoAPIError_2.mmd | 7 ++ docs/errors.md | 124 ++++++----------------- 9 files changed, 52 insertions(+), 107 deletions(-) create mode 100644 docs/charts/imgs/MongoAPIError_1.svg create mode 100644 docs/charts/imgs/MongoAPIError_2.svg create mode 100644 docs/charts/mermaid/MongoAPIError_1.mmd create mode 100644 docs/charts/mermaid/MongoAPIError_2.mmd diff --git a/docs/charts/imgs/MongoAPIError.svg b/docs/charts/imgs/MongoAPIError.svg index 71ec32e5387..98bdc1e0620 100644 --- a/docs/charts/imgs/MongoAPIError.svg +++ b/docs/charts/imgs/MongoAPIError.svg @@ -1 +1 @@ -
MongoAPIError
MongoInvalidArgumentError
MongoCompatibilityError
MongoMissingCredentialsError
MongoMissingDependencyError
MongoExpiredSessionError
MongoTransactionError
MongoTailableCursorError
MongoCursorExhaustedError
MongoCursorInUseError
MongoServerClosedError
MongoTopologyClosedError
MongoNotConnectedError
MongoBatchReExecutionError
MongoConnectionStringError
MongoConnectionPoolClosedError
MongoMessageStreamParseError
MongoGridFSStreamClosedError
MongoChangeStreamClosedError
 \ No newline at end of file +
MongoAPIError
MongoInvalidArgumentError
MongoCompatibilityError
MongoMissingCredentialsError
MongoMissingDependencyError
MongoExpiredSessionError
MongoTransactionError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoAPIError_1.svg b/docs/charts/imgs/MongoAPIError_1.svg new file mode 100644 index 00000000000..721569c59ab --- /dev/null +++ b/docs/charts/imgs/MongoAPIError_1.svg @@ -0,0 +1 @@ +
MongoAPIError
MongoTailableCursorError
MongoCursorExhaustedError
MongoCursorInUseError
MongoServerClosedError
MongoTopologyClosedError
MongoNotConnectedError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoAPIError_2.svg b/docs/charts/imgs/MongoAPIError_2.svg new file mode 100644 index 00000000000..7701b604246 --- /dev/null +++ b/docs/charts/imgs/MongoAPIError_2.svg @@ -0,0 +1 @@ +
MongoAPIError
MongoBatchReExecutionError
MongoConnectionStringError
MongoConnectionPoolClosedError
MongoMessageStreamParseError
MongoGridFSStreamClosedError
MongoChangeStreamClosedError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoError.svg b/docs/charts/imgs/MongoError.svg index 458ae5a8c7a..aa1707ec0f8 100644 --- a/docs/charts/imgs/MongoError.svg +++ b/docs/charts/imgs/MongoError.svg @@ -1 +1 @@ -
MongoError
MongoDriverError
MongoNetworkError
MongoServerError
MongoSystemError
MongoAPIError
MongoRuntimeError
 \ No newline at end of file +
MongoError
MongoDriverError
MongoNetworkError
MongoServerError
MongoSystemError
MongoAPIError
MongoRuntimeError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoRuntimeError_0.svg b/docs/charts/imgs/MongoRuntimeError_0.svg index 4f49b4c63e1..2e1cb98ad2d 100644 --- a/docs/charts/imgs/MongoRuntimeError_0.svg +++ b/docs/charts/imgs/MongoRuntimeError_0.svg @@ -1 +1 @@ -
MongoRuntimeError
MongoCompressionError
MongoDecompressionError
MongoGridFSChunkError
MongoGridFSStreamError
MongoChangeStreamError
 \ No newline at end of file +
MongoRuntimeError
MongoCompressionError
MongoDecompressionError
MongoGridFSChunkError
MongoGridFSStreamError
MongoChangeStreamError
 \ No newline at end of file diff --git a/docs/charts/mermaid/MongoAPIError.mmd b/docs/charts/mermaid/MongoAPIError.mmd index 0ff96cb6f43..f8f6c6ac6e0 100644 --- a/docs/charts/mermaid/MongoAPIError.mmd +++ b/docs/charts/mermaid/MongoAPIError.mmd @@ -3,18 +3,5 @@ graph TD MongoAPIError --> MongoCompatibilityError MongoAPIError --> MongoMissingCredentialsError MongoAPIError --> MongoMissingDependencyError - MongoAPIError --> MongoExpiredSessionError MongoAPIError --> MongoTransactionError - MongoAPIError --> MongoTailableCursorError - MongoAPIError --> MongoCursorExhaustedError - MongoAPIError --> MongoCursorInUseError - MongoAPIError --> MongoServerClosedError - MongoAPIError --> MongoTopologyClosedError - MongoAPIError --> MongoNotConnectedError - MongoAPIError --> MongoBatchReExecutionError - MongoAPIError --> MongoConnectionStringError - MongoAPIError --> MongoConnectionPoolClosedError - MongoAPIError --> MongoMessageStreamParseError - MongoAPIError --> MongoGridFSStreamClosedError - MongoAPIError --> MongoChangeStreamClosedError diff --git a/docs/charts/mermaid/MongoAPIError_1.mmd b/docs/charts/mermaid/MongoAPIError_1.mmd new file mode 100644 index 00000000000..dc6ce79d708 --- /dev/null +++ b/docs/charts/mermaid/MongoAPIError_1.mmd @@ -0,0 +1,7 @@ +graph TD + MongoAPIError --> MongoTailableCursorError + MongoAPIError --> MongoCursorExhaustedError + MongoAPIError --> MongoCursorInUseError + MongoAPIError --> MongoServerClosedError + MongoAPIError --> MongoTopologyClosedError + MongoAPIError --> MongoNotConnectedError diff --git a/docs/charts/mermaid/MongoAPIError_2.mmd b/docs/charts/mermaid/MongoAPIError_2.mmd new file mode 100644 index 00000000000..e0f03937748 --- /dev/null +++ b/docs/charts/mermaid/MongoAPIError_2.mmd @@ -0,0 +1,7 @@ +graph TD + MongoAPIError --> MongoBatchReExecutionError + MongoAPIError --> MongoConnectionStringError + MongoAPIError --> MongoConnectionPoolClosedError + MongoAPIError --> MongoMessageStreamParseError + MongoAPIError --> MongoGridFSStreamClosedError + MongoAPIError --> MongoChangeStreamClosedError diff --git a/docs/errors.md b/docs/errors.md index e10f9f82c37..43c1ce8dcb4 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -58,104 +58,46 @@ Its children are the main classes of errors that most users will interact with: This class represents errors which originate from misuse of the driver API and will generally be thrown before making contact with the server. This class should **never** be directly instantiated. -![(MongoAPIError hierarchy tree)](charts/imgs/MongoAPIError.svg) -Children of `MongoAPIError` include: -- #### `MongoInvalidArgumentError` - - - Thrown when the user supplies malformed, unexpected arguments or failed to provide a required argument or field. - -- #### `MongoCompatibilityError` - - - Thrown when a feature that is not enabled or allowed for the current server configuration is used. - -- #### `MongoMissingCredentialsError` - - - Thrown when a user fails to provide authentication credentials before attempting to connect to the mongo server. - -- #### `MongoMissingDependencyError` - - - Thrown when a required module or dependency is not present. - -- #### `MongoTransactionError` - - - Thrown when the user makes a mistake in the usage of transactions (e.g.: attempting to commit a transaction with a readPreference other than primary). - -- #### `MongoNotConnectedError` - - - Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance. - -- #### `MongoExpiredSessionError` - - - Thrown when the user attempts to operate on a session that has expired or has been closed. - -- #### `MongoServerClosedError` - - - Thrown when an attempt is made to operate on a closed server. - -- #### `MongoTopologyClosedError` - - - Thrown when an attempt is made to operate on a dropped, or otherwise unavailable, database. - -- #### `MongoTailableCursorError` - - - Thrown when the user calls a function or method that is not supported on a tailable cursor. - -- #### `MongoCursorInUseError` - - - Thrown when the user attempts to add options to an already initialized cursor. - -- #### `MongoCursorExhaustedError` - - - Thrown when an attempt is made to read from a cursor that has been exhausted. - -- #### `MongoBatchReExecutionError` - - - Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. +**Children of MongoAPIError** + +| Error Name | Description | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **MongoInvalidArgumentError** | Thrown when the user supplies malformed, unexpected arguments or failed to provide a required argument or field. | +| **MongoCompatibilityError** | Thrown when a feature that is not enabled or allowed for the current server configuration is used. | +| **MongoMissingCredentialsError** | Thrown when a user fails to provide authentication credentials before attempting to connect to the mongo server. | +| **MongoMissingDependencyError** | Thrown when a required module or dependency is not present. | +| **MongoExpiredSessionError** | Thrown when the user attempts to operate on a session that has expired or has been closed. | +| **MongoTransactionError** | Thrown when the user makes a mistake in the usage of transactions (e.g.: attempting to commit a transaction with a readPreference other than primary). | +| **MongoTailableCursorError** | Thrown when the user calls a function or method that is not supported on a tailable cursor. | +| **MongoCursorExhaustedError** | Thrown when an attempt is made to read from a cursor that has been exhausted. | +| **MongoCursorInUseError** | Thrown when the user attempts to add options to an already initialized cursor. | +| **MongoServerClosedError** | Thrown when an attempt is made to operate on a closed server. | +| **MongoTopologyClosedError** | Thrown when an attempt is made to operate on a dropped, or otherwise unavailable, database. | +| **MongoNotConnectedError** | Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance. | +| **MongoBatchReExecutionError** | Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. | +| **MongoConnectionStringError** | Thrown when a user supplies an incorrect URI to the driver. | +| **MongoConnectionPoolClosedError** | | +| **MongoMessageStreamParseError** | | +| **MongoGridFSStreamClosedError** | | +| **MongoChangeStreamClosedError** | | ### `MongoRuntimeError` This class represents errors which occur when the driver encounters unexpected input or reaches an unexpected/invalid internal state. This class should **never** be directly instantiated. -_MongoRuntimeError children (pt 1)_ -![(MongoRuntimeError hierarchy tree part 1)](charts/imgs/MongoRuntimeError_0.svg) - -_MongoRuntimeError children (pt 2)_ -![(MongoRuntimeError hierarchy tree part 2)](charts/imgs/MongoRuntimeError_1.svg) - -_MongoRuntimeError children (pt 3)_ -![(MongoRuntimeError hierarchy tree part 3)](charts/imgs/MongoRuntimeError_2.svg) - -Children of `MongoRuntimeError` include: - -- #### `MongoCompressionError` - - - Thrown when the driver fails to compress data before sending it to the server. - -- #### `MongoDecompressionError` - - - Thrown when the driver fails to decompress data received from the server - -- #### `MongoURIError` - - - Thrown when a user supplies an incorrect URI to the driver. - -- #### `MongoChangeStreamError` - - - Thrown when an error is encountered when operating on a ChangeStream. - -- #### `MongoGridFSStreamError` - - - Thrown when an unexpected state is reached when operating on a GridFSStream. - -- #### `MongoGridFSChunkError` - - - Thrown when a malformed or invalid chunk is encountered when reading from a GridFSStream. - -- #### `MongoServerSelectionError` - - - Thrown when the driver fails to select a server to complete an operation. +**Children of MongoRuntimeError** + +| Error Name | Description | +| ----------------------------- | ----------------------------------------------------------------------------------------- | +| **MongoCompressionError** | Thrown when the driver fails to compress data before sending it to the server | +| **MongoDecompressionError** | Thrown when the driver fails to decompress data received from the server | +| **MongoChangeStreamError** | Thrown when an error is encountered when operating on a ChangeStream | +| **MongoGridFSStreamError** | Thrown when an unexpected state is reached when operating on a GridFS Stream | +| **MongoGridFSChunkError** | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream | +| **MongoServerSelectionError** | Thrown when the driver fails to select a server to complete an operation | +| **MongoURIError** | Thrown when a user supplies an incorrect URI to the driver | ### `MongoNetworkError` From 20b0aa3eb81768dd133234647423776bc52693e4 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 6 Aug 2021 13:56:43 -0400 Subject: [PATCH 04/13] docs: Update testing plan --- docs/errors.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/errors.md b/docs/errors.md index 43c1ce8dcb4..c9df257920d 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -21,12 +21,12 @@ - [`MongoAPIError`](#MongoAPIError-1) - [`MongoInvalidArgumentError`](#MongoInvalidArgumentError-1) - [`MongoMissingCredentialsError`](#MongoMissingCredentialsError-1) - - [`MongoRuntimeError`](#MongoRuntimeError-1) - [`MongoNotConnectedError`](#MongoNotConnectedError-1) - - [`MongoServerClosedError`](#MongoServerClosedError-1) - - [`MongoStreamClosedError`](#MongoStreamClosedError-1) - [`MongoTopologyClosedError`](#MongoTopologyClosedError-1) - [`MongoCursorExhaustedError`](#MongoCursorExhaustedError-1) + - [`MongoServerClosedError`](#MongoServerClosedError-1) + - [`MongoStreamClosedError`](#MongoStreamClosedError-1) + - [`MongoRuntimeError`](#MongoRuntimeError-1) - [`MongoNetworkError`](#MongoNetworkError-1) - [`MongoNetworkTimeoutError`](#MongoNetworkTimeoutError-1) @@ -77,7 +77,7 @@ This class should **never** be directly instantiated. | **MongoNotConnectedError** | Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance. | | **MongoBatchReExecutionError** | Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. | | **MongoConnectionStringError** | Thrown when a user supplies an incorrect URI to the driver. | -| **MongoConnectionPoolClosedError** | | +| **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that has expired or has been closed | | **MongoMessageStreamParseError** | | | **MongoGridFSStreamClosedError** | | | **MongoChangeStreamClosedError** | | @@ -137,13 +137,21 @@ The classes to be tested will be selected based on two characteristics: - Fail to provide credentials when authenticating with the x509 mechanism. - Assert that `MongoMissingCredentialsError` is thrown. -### `MongoRuntimeError` - #### `MongoNotConnectedError` - Attempt to access a database without establishing a connection to a MongoDB server. - Assert that `MongoNotConnectedError` is thrown. +#### `MongoTopologyClosedError` + +- Attempt to execute `createCollection()` against a database that has been closed. + - Assert that `MongoTopologyClosedError` is thrown. + +#### `MongoCursorExhaustedError` + +- Attempt to continue reading a cursor after it has reached the end of the batch. + - Assert that `MongoCursorExhaustedError` is thrown. + #### `MongoServerClosedError` - Attempt to execute a query against a server that has closed. @@ -154,15 +162,7 @@ The classes to be tested will be selected based on two characteristics: - Attempt to execute `tryNext()` on a `ChangeStream` object that is closed. - Assert that `MongoStreamClosedError` is thrown. -#### `MongoTopologyClosedError` - -- Attempt to execute `createCollection()` against a database that has been closed. - - Assert that `MongoTopologyClosedError` is thrown. - -#### `MongoCursorExhaustedError` - -- Attempt to continue reading a cursor after it has reached the end of the batch. - - Assert that `MongoCursorExhaustedError` is thrown. +### `MongoRuntimeError` ### `MongoNetworkError` From b9dd6f54dd9e9667bb3810303d4e6cd7ada1ff90 Mon Sep 17 00:00:00 2001 From: Warren James Date: Mon, 16 Aug 2021 17:01:28 -0400 Subject: [PATCH 05/13] docs: Remove unused errors --- docs/errors.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/errors.md b/docs/errors.md index c9df257920d..20c61387735 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -78,9 +78,6 @@ This class should **never** be directly instantiated. | **MongoBatchReExecutionError** | Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. | | **MongoConnectionStringError** | Thrown when a user supplies an incorrect URI to the driver. | | **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that has expired or has been closed | -| **MongoMessageStreamParseError** | | -| **MongoGridFSStreamClosedError** | | -| **MongoChangeStreamClosedError** | | ### `MongoRuntimeError` From 6953e28ea654ff4e2ef5f6a68ddfffdbf77d0565 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 17 Aug 2021 13:25:26 -0400 Subject: [PATCH 06/13] docs: remove charts and update documentation --- docs/charts/README.md | 7 ------ docs/charts/build_images.sh | 13 ---------- docs/charts/imgs/MongoAPIError.svg | 1 - docs/charts/imgs/MongoAPIError_1.svg | 1 - docs/charts/imgs/MongoAPIError_2.svg | 1 - docs/charts/imgs/MongoError.svg | 1 - docs/charts/imgs/MongoRuntimeError_0.svg | 1 - docs/charts/mermaid/MongoAPIError.mmd | 7 ------ docs/charts/mermaid/MongoAPIError_1.mmd | 7 ------ docs/charts/mermaid/MongoAPIError_2.mmd | 7 ------ docs/charts/mermaid/MongoError.mmd | 8 ------ docs/charts/mermaid/MongoRuntimeError_0.mmd | 6 ----- docs/errors.md | 28 ++++++++------------- 13 files changed, 10 insertions(+), 78 deletions(-) delete mode 100644 docs/charts/README.md delete mode 100755 docs/charts/build_images.sh delete mode 100644 docs/charts/imgs/MongoAPIError.svg delete mode 100644 docs/charts/imgs/MongoAPIError_1.svg delete mode 100644 docs/charts/imgs/MongoAPIError_2.svg delete mode 100644 docs/charts/imgs/MongoError.svg delete mode 100644 docs/charts/imgs/MongoRuntimeError_0.svg delete mode 100644 docs/charts/mermaid/MongoAPIError.mmd delete mode 100644 docs/charts/mermaid/MongoAPIError_1.mmd delete mode 100644 docs/charts/mermaid/MongoAPIError_2.mmd delete mode 100644 docs/charts/mermaid/MongoError.mmd delete mode 100644 docs/charts/mermaid/MongoRuntimeError_0.mmd diff --git a/docs/charts/README.md b/docs/charts/README.md deleted file mode 100644 index f2598110661..00000000000 --- a/docs/charts/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Charts and mermaid code - -The `mermaid` directory contains the [mermaid](https://mermaid-js.github.io/mermaid/#/) files which serve as the source code for the svg files included in the `../errors.md` - -To generate these files, there is an included script, `build_images.sh` which builds images for all the mermaid files in the `mermaid` directory. - -To use this script, the [mermaid cli](https://github.com/mermaid-js/mermaid-cli) must be installed and be accessible via your $PATH variable. diff --git a/docs/charts/build_images.sh b/docs/charts/build_images.sh deleted file mode 100755 index 4a9a34f7dcf..00000000000 --- a/docs/charts/build_images.sh +++ /dev/null @@ -1,13 +0,0 @@ -#! /bin/bash - -echo "Building svgs..." -cd mermaid -for f in *.mmd -do - echo "Processing $f" - outname="${f%%.*}" - mmdc -i $f -o ../imgs/$outname.svg & -done -wait - -echo "Done" diff --git a/docs/charts/imgs/MongoAPIError.svg b/docs/charts/imgs/MongoAPIError.svg deleted file mode 100644 index 98bdc1e0620..00000000000 --- a/docs/charts/imgs/MongoAPIError.svg +++ /dev/null @@ -1 +0,0 @@ -
MongoAPIError
MongoInvalidArgumentError
MongoCompatibilityError
MongoMissingCredentialsError
MongoMissingDependencyError
MongoExpiredSessionError
MongoTransactionError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoAPIError_1.svg b/docs/charts/imgs/MongoAPIError_1.svg deleted file mode 100644 index 721569c59ab..00000000000 --- a/docs/charts/imgs/MongoAPIError_1.svg +++ /dev/null @@ -1 +0,0 @@ -
MongoAPIError
MongoTailableCursorError
MongoCursorExhaustedError
MongoCursorInUseError
MongoServerClosedError
MongoTopologyClosedError
MongoNotConnectedError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoAPIError_2.svg b/docs/charts/imgs/MongoAPIError_2.svg deleted file mode 100644 index 7701b604246..00000000000 --- a/docs/charts/imgs/MongoAPIError_2.svg +++ /dev/null @@ -1 +0,0 @@ -
MongoAPIError
MongoBatchReExecutionError
MongoConnectionStringError
MongoConnectionPoolClosedError
MongoMessageStreamParseError
MongoGridFSStreamClosedError
MongoChangeStreamClosedError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoError.svg b/docs/charts/imgs/MongoError.svg deleted file mode 100644 index aa1707ec0f8..00000000000 --- a/docs/charts/imgs/MongoError.svg +++ /dev/null @@ -1 +0,0 @@ -
MongoError
MongoDriverError
MongoNetworkError
MongoServerError
MongoSystemError
MongoAPIError
MongoRuntimeError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoRuntimeError_0.svg b/docs/charts/imgs/MongoRuntimeError_0.svg deleted file mode 100644 index 2e1cb98ad2d..00000000000 --- a/docs/charts/imgs/MongoRuntimeError_0.svg +++ /dev/null @@ -1 +0,0 @@ -
MongoRuntimeError
MongoCompressionError
MongoDecompressionError
MongoGridFSChunkError
MongoGridFSStreamError
MongoChangeStreamError
 \ No newline at end of file diff --git a/docs/charts/mermaid/MongoAPIError.mmd b/docs/charts/mermaid/MongoAPIError.mmd deleted file mode 100644 index f8f6c6ac6e0..00000000000 --- a/docs/charts/mermaid/MongoAPIError.mmd +++ /dev/null @@ -1,7 +0,0 @@ -graph TD - MongoAPIError --> MongoInvalidArgumentError - MongoAPIError --> MongoCompatibilityError - MongoAPIError --> MongoMissingCredentialsError - MongoAPIError --> MongoMissingDependencyError - MongoAPIError --> MongoExpiredSessionError - MongoAPIError --> MongoTransactionError diff --git a/docs/charts/mermaid/MongoAPIError_1.mmd b/docs/charts/mermaid/MongoAPIError_1.mmd deleted file mode 100644 index dc6ce79d708..00000000000 --- a/docs/charts/mermaid/MongoAPIError_1.mmd +++ /dev/null @@ -1,7 +0,0 @@ -graph TD - MongoAPIError --> MongoTailableCursorError - MongoAPIError --> MongoCursorExhaustedError - MongoAPIError --> MongoCursorInUseError - MongoAPIError --> MongoServerClosedError - MongoAPIError --> MongoTopologyClosedError - MongoAPIError --> MongoNotConnectedError diff --git a/docs/charts/mermaid/MongoAPIError_2.mmd b/docs/charts/mermaid/MongoAPIError_2.mmd deleted file mode 100644 index e0f03937748..00000000000 --- a/docs/charts/mermaid/MongoAPIError_2.mmd +++ /dev/null @@ -1,7 +0,0 @@ -graph TD - MongoAPIError --> MongoBatchReExecutionError - MongoAPIError --> MongoConnectionStringError - MongoAPIError --> MongoConnectionPoolClosedError - MongoAPIError --> MongoMessageStreamParseError - MongoAPIError --> MongoGridFSStreamClosedError - MongoAPIError --> MongoChangeStreamClosedError diff --git a/docs/charts/mermaid/MongoError.mmd b/docs/charts/mermaid/MongoError.mmd deleted file mode 100644 index 5ed6b9fe5fb..00000000000 --- a/docs/charts/mermaid/MongoError.mmd +++ /dev/null @@ -1,8 +0,0 @@ -graph TD - MongoError --> MongoDriverError - MongoError --> MongoNetworkError - MongoError --> MongoServerError - MongoError --> MongoSystemError - MongoDriverError --> MongoAPIError - MongoDriverError --> MongoRuntimeError - diff --git a/docs/charts/mermaid/MongoRuntimeError_0.mmd b/docs/charts/mermaid/MongoRuntimeError_0.mmd deleted file mode 100644 index cd5ac025f01..00000000000 --- a/docs/charts/mermaid/MongoRuntimeError_0.mmd +++ /dev/null @@ -1,6 +0,0 @@ -graph TD - MongoRuntimeError --> MongoCompressionError - MongoRuntimeError --> MongoDecompressionError - MongoRuntimeError --> MongoGridFSChunkError - MongoRuntimeError --> MongoGridFSStreamError - MongoRuntimeError --> MongoChangeStreamError diff --git a/docs/errors.md b/docs/errors.md index 20c61387735..4c3f990d789 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -25,8 +25,6 @@ - [`MongoTopologyClosedError`](#MongoTopologyClosedError-1) - [`MongoCursorExhaustedError`](#MongoCursorExhaustedError-1) - [`MongoServerClosedError`](#MongoServerClosedError-1) - - [`MongoStreamClosedError`](#MongoStreamClosedError-1) - - [`MongoRuntimeError`](#MongoRuntimeError-1) - [`MongoNetworkError`](#MongoNetworkError-1) - [`MongoNetworkTimeoutError`](#MongoNetworkTimeoutError-1) @@ -86,15 +84,13 @@ This class should **never** be directly instantiated. **Children of MongoRuntimeError** -| Error Name | Description | -| ----------------------------- | ----------------------------------------------------------------------------------------- | -| **MongoCompressionError** | Thrown when the driver fails to compress data before sending it to the server | -| **MongoDecompressionError** | Thrown when the driver fails to decompress data received from the server | -| **MongoChangeStreamError** | Thrown when an error is encountered when operating on a ChangeStream | -| **MongoGridFSStreamError** | Thrown when an unexpected state is reached when operating on a GridFS Stream | -| **MongoGridFSChunkError** | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream | -| **MongoServerSelectionError** | Thrown when the driver fails to select a server to complete an operation | -| **MongoURIError** | Thrown when a user supplies an incorrect URI to the driver | +| Error Name | Description | +| --------------------------- | ----------------------------------------------------------------------------------------- | +| **MongoDecompressionError** | Thrown when the driver fails to decompress data received from the server | +| **MongoChangeStreamError** | Thrown when an error is encountered when operating on a ChangeStream | +| **MongoGridFSStreamError** | Thrown when an unexpected state is reached when operating on a GridFS Stream | +| **MongoGridFSChunkError** | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream | +| **MongoURIError** | Thrown when a user supplies an incorrect URI to the driver | ### `MongoNetworkError` @@ -112,6 +108,9 @@ These are errors which wrap error responses received from the server. These are errors which originate from faulty environment setup. +- #### MongoServerSelectionError + - Thrown when the driver fails to select a server to complete an operation + ## Test Plan The test plan consists of a series of prose tests. @@ -154,13 +153,6 @@ The classes to be tested will be selected based on two characteristics: - Attempt to execute a query against a server that has closed. - Assert that `MongoServerClosedError` is thrown. -#### `MongoStreamClosedError` - -- Attempt to execute `tryNext()` on a `ChangeStream` object that is closed. - - Assert that `MongoStreamClosedError` is thrown. - -### `MongoRuntimeError` - ### `MongoNetworkError` #### `MongoNetworkTimeoutError` From ee14487e676ba03262ac22c45724c3a0a417f193 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 17 Aug 2021 17:27:15 -0400 Subject: [PATCH 07/13] docs: Remove reference to MongoURIError --- docs/errors.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/errors.md b/docs/errors.md index 4c3f990d789..814f92419d0 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -90,7 +90,6 @@ This class should **never** be directly instantiated. | **MongoChangeStreamError** | Thrown when an error is encountered when operating on a ChangeStream | | **MongoGridFSStreamError** | Thrown when an unexpected state is reached when operating on a GridFS Stream | | **MongoGridFSChunkError** | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream | -| **MongoURIError** | Thrown when a user supplies an incorrect URI to the driver | ### `MongoNetworkError` From d65c759fa4899687a1825750549038a337809a4b Mon Sep 17 00:00:00 2001 From: Warren James Date: Wed, 18 Aug 2021 15:05:44 -0400 Subject: [PATCH 08/13] docs: Fix grammar --- docs/errors.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/errors.md b/docs/errors.md index 814f92419d0..8b9551ba0eb 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -49,7 +49,7 @@ Children of `MongoError` include: ### `MongoDriverError` -This class represents errors which originate in the driver itself or in the user's use of the driver. This class should **never** be directly instantiated. +This class represents errors which originate in the driver itself or when the user incorrectly uses the driver. This class should **never** be directly instantiated. Its children are the main classes of errors that most users will interact with: [**`MongoAPIError`**](#MongoAPIError) and [**`MongoRuntimeError`**](#MongoRuntimeError). ### `MongoAPIError` @@ -61,21 +61,21 @@ This class should **never** be directly instantiated. | Error Name | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **MongoInvalidArgumentError** | Thrown when the user supplies malformed, unexpected arguments or failed to provide a required argument or field. | +| **MongoInvalidArgumentError** | Thrown when the user supplies malformed or unexpected arguments or failed to provide a required argument or field. | | **MongoCompatibilityError** | Thrown when a feature that is not enabled or allowed for the current server configuration is used. | -| **MongoMissingCredentialsError** | Thrown when a user fails to provide authentication credentials before attempting to connect to the mongo server. | +| **MongoMissingCredentialsError** | Thrown when a user fails to provide authentication credentials before attempting to connect. | | **MongoMissingDependencyError** | Thrown when a required module or dependency is not present. | -| **MongoExpiredSessionError** | Thrown when the user attempts to operate on a session that has expired or has been closed. | +| **MongoExpiredSessionError** | Thrown when the user attempts to operate on a session that is expired or closed. | | **MongoTransactionError** | Thrown when the user makes a mistake in the usage of transactions (e.g.: attempting to commit a transaction with a readPreference other than primary). | | **MongoTailableCursorError** | Thrown when the user calls a function or method that is not supported on a tailable cursor. | -| **MongoCursorExhaustedError** | Thrown when an attempt is made to read from a cursor that has been exhausted. | +| **MongoCursorExhaustedError** | Thrown when an attempt is made to read from a cursor that is exhausted. | | **MongoCursorInUseError** | Thrown when the user attempts to add options to an already initialized cursor. | | **MongoServerClosedError** | Thrown when an attempt is made to operate on a closed server. | | **MongoTopologyClosedError** | Thrown when an attempt is made to operate on a dropped, or otherwise unavailable, database. | -| **MongoNotConnectedError** | Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance. | -| **MongoBatchReExecutionError** | Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. | +| **MongoNotConnectedError** | Thrown when the user attempts to perform operations on a client that has not yet connected. | +| **MongoBatchReExecutionError** | Thrown when a user attempts to re-execute a batch command when one of the constituent commands has failed. | | **MongoConnectionStringError** | Thrown when a user supplies an incorrect URI to the driver. | -| **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that has expired or has been closed | +| **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that is expired or closed | ### `MongoRuntimeError` From c3b781298b210ce116bd6469beebbf472b2b8520 Mon Sep 17 00:00:00 2001 From: Warren James Date: Thu, 19 Aug 2021 10:38:42 -0400 Subject: [PATCH 09/13] docs: restore MongoError diagram --- docs/charts/README.md | 7 +++++++ docs/charts/build_images.sh | 13 +++++++++++++ docs/charts/imgs/MongoError.svg | 1 + docs/charts/mermaid/MongoError.mmd | 8 ++++++++ 4 files changed, 29 insertions(+) create mode 100644 docs/charts/README.md create mode 100755 docs/charts/build_images.sh create mode 100644 docs/charts/imgs/MongoError.svg create mode 100644 docs/charts/mermaid/MongoError.mmd diff --git a/docs/charts/README.md b/docs/charts/README.md new file mode 100644 index 00000000000..f2598110661 --- /dev/null +++ b/docs/charts/README.md @@ -0,0 +1,7 @@ +# Charts and mermaid code + +The `mermaid` directory contains the [mermaid](https://mermaid-js.github.io/mermaid/#/) files which serve as the source code for the svg files included in the `../errors.md` + +To generate these files, there is an included script, `build_images.sh` which builds images for all the mermaid files in the `mermaid` directory. + +To use this script, the [mermaid cli](https://github.com/mermaid-js/mermaid-cli) must be installed and be accessible via your $PATH variable. diff --git a/docs/charts/build_images.sh b/docs/charts/build_images.sh new file mode 100755 index 00000000000..4a9a34f7dcf --- /dev/null +++ b/docs/charts/build_images.sh @@ -0,0 +1,13 @@ +#! /bin/bash + +echo "Building svgs..." +cd mermaid +for f in *.mmd +do + echo "Processing $f" + outname="${f%%.*}" + mmdc -i $f -o ../imgs/$outname.svg & +done +wait + +echo "Done" diff --git a/docs/charts/imgs/MongoError.svg b/docs/charts/imgs/MongoError.svg new file mode 100644 index 00000000000..90be44e9840 --- /dev/null +++ b/docs/charts/imgs/MongoError.svg @@ -0,0 +1 @@ +
MongoError
MongoDriverError
MongoNetworkError
MongoServerError
MongoSystemError
MongoAPIError
MongoRuntimeError
 \ No newline at end of file diff --git a/docs/charts/mermaid/MongoError.mmd b/docs/charts/mermaid/MongoError.mmd new file mode 100644 index 00000000000..5ed6b9fe5fb --- /dev/null +++ b/docs/charts/mermaid/MongoError.mmd @@ -0,0 +1,8 @@ +graph TD + MongoError --> MongoDriverError + MongoError --> MongoNetworkError + MongoError --> MongoServerError + MongoError --> MongoSystemError + MongoDriverError --> MongoAPIError + MongoDriverError --> MongoRuntimeError + From 7ab3713b733ab65ca82e47745f98b077aaa0fa3d Mon Sep 17 00:00:00 2001 From: Warren James Date: Thu, 19 Aug 2021 13:42:39 -0400 Subject: [PATCH 10/13] docs: Make diagram more readable for dark and light mode --- docs/charts/imgs/MongoError.svg | 2 +- docs/charts/mermaid/MongoError.mmd | 28 +++++++++++++++++++++------- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/charts/imgs/MongoError.svg b/docs/charts/imgs/MongoError.svg index 90be44e9840..13d86e58c0f 100644 --- a/docs/charts/imgs/MongoError.svg +++ b/docs/charts/imgs/MongoError.svg @@ -1 +1 @@ -
MongoError
MongoDriverError
MongoNetworkError
MongoServerError
MongoSystemError
MongoAPIError
MongoRuntimeError
 \ No newline at end of file +
MongoError
MongoDriverError
MongoNetworkError
MongoServerError
MongoSystemError
MongoAPIError
MongoRuntimeError
 \ No newline at end of file diff --git a/docs/charts/mermaid/MongoError.mmd b/docs/charts/mermaid/MongoError.mmd index 5ed6b9fe5fb..0592b5c5649 100644 --- a/docs/charts/mermaid/MongoError.mmd +++ b/docs/charts/mermaid/MongoError.mmd @@ -1,8 +1,22 @@ graph TD - MongoError --> MongoDriverError - MongoError --> MongoNetworkError - MongoError --> MongoServerError - MongoError --> MongoSystemError - MongoDriverError --> MongoAPIError - MongoDriverError --> MongoRuntimeError - + MongoError --- MongoDriverError + MongoError --- MongoNetworkError + MongoError --- MongoServerError + MongoError --- MongoSystemError + MongoDriverError --- MongoAPIError + MongoDriverError --- MongoRuntimeError + +linkStyle 0 stroke:#116149 +linkStyle 1 stroke:#116149 +linkStyle 2 stroke:#116149 +linkStyle 3 stroke:#116149 +linkStyle 4 stroke:#116149 +linkStyle 5 stroke:#116149 + +style MongoError fill:#13aa52,stroke:#21313c,color:#FAFBFC +style MongoSystemError fill:#13aa52,stroke:#21313c,color:#FAFBFC +style MongoNetworkError fill:#13aa52,stroke:#21313c,color:#FAFBFC +style MongoServerError fill:#13aa52,stroke:#21313c,color:#FAFBFC +style MongoDriverError fill:#13aa52,stroke:#21313c,color:#FAFBFC +style MongoAPIError fill:#13aa52,stroke:#21313c,color:#FAFBFC +style MongoRuntimeError fill:#13aa52,stroke:#21313c,color:#FAFBFC From 3b39d6abb57730290beb547371166e27e8f6b47f Mon Sep 17 00:00:00 2001 From: Warren James Date: Thu, 19 Aug 2021 14:45:33 -0400 Subject: [PATCH 11/13] docs: Add note about mermaid installation --- docs/charts/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/charts/README.md b/docs/charts/README.md index f2598110661..c2086d8c71f 100644 --- a/docs/charts/README.md +++ b/docs/charts/README.md @@ -4,4 +4,8 @@ The `mermaid` directory contains the [mermaid](https://mermaid-js.github.io/merm To generate these files, there is an included script, `build_images.sh` which builds images for all the mermaid files in the `mermaid` directory. -To use this script, the [mermaid cli](https://github.com/mermaid-js/mermaid-cli) must be installed and be accessible via your $PATH variable. +To use this script, the [mermaid cli](https://github.com/mermaid-js/mermaid-cli) must be installed and be accessible via your $PATH variable. + +**Note on mermaid installation** + +It is preferable to install mermaid via npm rather than brew since brew will install node as a dependency which could interfere with nvm. From 1a3115c8b493cede4d1465e94956a299eb95bb55 Mon Sep 17 00:00:00 2001 From: Warren James Date: Thu, 19 Aug 2021 16:21:37 -0400 Subject: [PATCH 12/13] docs: Ensure Error descriptions end with periods --- docs/errors.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/errors.md b/docs/errors.md index 8b9551ba0eb..7735f35a9ae 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -75,7 +75,7 @@ This class should **never** be directly instantiated. | **MongoNotConnectedError** | Thrown when the user attempts to perform operations on a client that has not yet connected. | | **MongoBatchReExecutionError** | Thrown when a user attempts to re-execute a batch command when one of the constituent commands has failed. | | **MongoConnectionStringError** | Thrown when a user supplies an incorrect URI to the driver. | -| **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that is expired or closed | +| **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that is expired or closed. | ### `MongoRuntimeError` @@ -84,12 +84,12 @@ This class should **never** be directly instantiated. **Children of MongoRuntimeError** -| Error Name | Description | -| --------------------------- | ----------------------------------------------------------------------------------------- | -| **MongoDecompressionError** | Thrown when the driver fails to decompress data received from the server | -| **MongoChangeStreamError** | Thrown when an error is encountered when operating on a ChangeStream | -| **MongoGridFSStreamError** | Thrown when an unexpected state is reached when operating on a GridFS Stream | -| **MongoGridFSChunkError** | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream | +| Error Name | Description | +| --------------------------- | ------------------------------------------------------------------------------------------ | +| **MongoDecompressionError** | Thrown when the driver fails to decompress data received from the server. | +| **MongoChangeStreamError** | Thrown when an error is encountered when operating on a ChangeStream. | +| **MongoGridFSStreamError** | Thrown when an unexpected state is reached when operating on a GridFS Stream. | +| **MongoGridFSChunkError** | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream. | ### `MongoNetworkError` From ef8d0ef201594bbfe1cdd8d32c1ae34b0b85bfa7 Mon Sep 17 00:00:00 2001 From: Warren James Date: Thu, 19 Aug 2021 16:26:19 -0400 Subject: [PATCH 13/13] docs: Fix minor error --- docs/errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/errors.md b/docs/errors.md index 7735f35a9ae..e841b4b14b5 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -114,7 +114,7 @@ These are errors which originate from faulty environment setup. The test plan consists of a series of prose tests. As numerous errors are being introduced, select classes will be tested. -The classes to be tested will be selected based on two characteristics: +The classes to be tested will be selected based on three characteristics: 1. The **frequency** with which users may encounter this error. Errors that users will likely run into, including but not limited to `MongoInvalidArgumentError` and `MongoNetworkTimeoutError`, are a part of the test plan. _Note:_ Error classes that should never be instantiated, such as `MongoAPIError` and `MongoRuntimeError`, will not be tested as the user should not encounter them. 2. The **scope** of the error. Errors that tackle a large subset of issues, including but not limited to `MongoServerError` and `MongoSystemError`, will _not_ be a part of the test plan.