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. diff --git a/docs/charts/imgs/MongoAPIError.svg b/docs/charts/imgs/MongoAPIError.svg deleted file mode 100644 index 9d46d069617..00000000000 --- a/docs/charts/imgs/MongoAPIError.svg +++ /dev/null @@ -1,4 +0,0 @@ -
MongoAPIError
MongoInvalidArgumentError
MongoCompatibilityError
MongoMissingCredentialsError
MongoMissingDependencyError
 \ No newline at end of file diff --git a/docs/charts/imgs/MongoError.svg b/docs/charts/imgs/MongoError.svg index 41f37b7adb0..13d86e58c0f 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 deleted file mode 100644 index 6a0961223a3..00000000000 --- a/docs/charts/imgs/MongoRuntimeError_0.svg +++ /dev/null @@ -1,4 +0,0 @@ -
MongoRuntimeError
MongoBatchReExecutionError
MongoCursorError
MongoInvalidClassInstantiationError
MongoNotConnectedError
MongoTailableCursorError
MongoCursorInUseError
MongoCursorExhaustedError
 \ 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 deleted file mode 100644 index 7275b04dc46..00000000000 --- a/docs/charts/mermaid/MongoAPIError.mmd +++ /dev/null @@ -1,5 +0,0 @@ -graph TD - MongoAPIError --> MongoInvalidArgumentError - MongoAPIError --> MongoCompatibilityError - MongoAPIError --> MongoMissingCredentialsError - MongoAPIError --> MongoMissingDependencyError 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 diff --git a/docs/charts/mermaid/MongoRuntimeError_0.mmd b/docs/charts/mermaid/MongoRuntimeError_0.mmd deleted file mode 100644 index 2646b76d906..00000000000 --- a/docs/charts/mermaid/MongoRuntimeError_0.mmd +++ /dev/null @@ -1,9 +0,0 @@ -graph TD - MongoRuntimeError --> MongoBatchReExecutionError - MongoRuntimeError --> MongoCursorError - MongoRuntimeError --> MongoInvalidClassInstantiationError - MongoRuntimeError --> MongoNotConnectedError - - MongoCursorError --> MongoTailableCursorError - MongoCursorError --> MongoCursorInUseError - MongoCursorError --> MongoCursorExhaustedError 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 diff --git a/docs/errors.md b/docs/errors.md index f008c365651..e841b4b14b5 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) @@ -21,21 +21,20 @@ - [`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) - [`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,111 +47,51 @@ 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 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` 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. +**Children of MongoAPIError** + +| Error Name | Description | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **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. | +| **MongoMissingDependencyError** | Thrown when a required module or dependency is not present. | +| **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 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 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. | ### `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: - -- #### `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. - -- #### `MongoDecompressionError` - - - 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` +**Children of MongoRuntimeError** - - 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. | -- #### `MongoResourceClosedError` - - - 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. - -- #### `MongoCursorError` - - - 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. - -- #### `MongoStreamError` - - - 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. - -- #### `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,25 +99,28 @@ 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 +- #### 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. 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. 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,23 +132,11 @@ 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. -#### `MongoServerClosedError` - -- 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. - #### `MongoTopologyClosedError` - Attempt to execute `createCollection()` against a database that has been closed. @@ -217,7 +147,12 @@ 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` +#### `MongoServerClosedError` + +- Attempt to execute a query against a server that has closed. + - Assert that `MongoServerClosedError` is thrown. + +### `MongoNetworkError` #### `MongoNetworkTimeoutError`