feat(NODE-5484)!: mark MongoError for internal use and remove Node14 cause assignment logic (#3800)

Co-authored-by: Bailey Pearson <bailey.pearson@mongodb.com>

Author: W-A-James

etc/notes/errors.md

@@ -18,6 +18,7 @@
   - [`MongoNetworkError`](#MongoNetworkError)
   - [`MongoServerError`](#MongoServerError)
   - [`MongoSystemError`](#MongoSystemError)
+  - [`MongoCryptError`](#MongoCryptError)
 - [Test Plan](#Test-Plan)
   - [`MongoAPIError`](#MongoAPIError-1)
     - [`MongoInvalidArgumentError`](#MongoInvalidArgumentError-1)
@@ -32,37 +33,27 @@
 ## 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 five main error classes which stem from `MongoError`: `MongoDriverError`,
+`MongoNetworkError`, `MongoServerError`, `MongoCryptError` and `MongoSystemError`.
 
 ### `MongoError`
 
 The base class from which all errors in the Node driver subclass.
 `MongoError` should **never** be be directly instantiated.
 
 ```mermaid
+
 graph TD
-    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
+    MongoError:::node --- MongoDriverError
+    MongoError:::node --- MongoNetworkError
+    MongoError:::node --- MongoServerError
+    MongoError:::node --- MongoSystemError
+    MongoError:::node --- MongoCryptError
+    MongoDriverError:::node --- MongoAPIError
+    MongoDriverError:::node --- MongoRuntimeError
+
+linkStyle 0,1,2,3,4,5,6 stroke:#116149
+classDef node fill:#13aa52,stroke:#21313c,color:#FAFBFC
 ```
 
 Children of `MongoError` include:
@@ -71,6 +62,7 @@ Children of `MongoError` include:
 - [`MongoNetworkError`](#MongoNetworkError)
 - [`MongoServerError`](#MongoServerError)
 - [`MongoSystemError`](#MongoSystemError)
+- [`MongoCryptError`](#MongoCryptError)
 
 ### `MongoDriverError`
 
@@ -144,6 +136,21 @@ These are errors which originate from faulty environment setup.
 - #### MongoServerSelectionError
   - Thrown when the driver fails to select a server to complete an operation
 
+### `MongoCryptError`
+
+These are errors thrown from the driver's client side encryption logic.
+
+- #### MongoCryptInvalidArgumentError
+  - Thrown when an invalid argument has been provided to an encryption API
+- #### MongoCryptInvalidCreateDataKeyError
+  - Thrown when the driver fails to create data keys for an encrypted collection
+- #### MongoCryptInvalidCreateEncryptedCollectionError
+  - Thrown when the driver fails to create an encrypted collection
+- #### MongoCryptInvalidCreateAzureKMSRequestError
+  - Thrown when the driver encounters an error when fetching Azure KMS credentials
+- #### MongoCryptKMSRequestNetworkTimeoutError
+  - Thrown when the HTTP request to the IDMS server times out when fetching Azure KMS credentials
+
 ## Test Plan
 
 The test plan consists of a series of prose tests.

src/bulk/common.ts

@@ -598,7 +598,17 @@ export class MongoBulkWriteError extends MongoServerError {
   writeErrors: OneOrMore<WriteError> = [];
   err?: WriteConcernError;
 
-  /** Creates a new MongoBulkWriteError */
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(
     error:
       | { message: string; code: number; writeErrors?: WriteError[] }

src/client-side-encryption/auto_encrypter.ts

@@ -422,7 +422,8 @@ export class AutoEncrypter {
       ) {
         callback(
           new MongoRuntimeError(
-            'Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn'
+            'Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn',
+            { cause: err }
           )
         );
         return;

src/client-side-encryption/errors.ts

@@ -1,11 +1,22 @@
 import { type Document } from '../bson';
+import { MongoError } from '../error';
 
 /**
  * @public
  * An error indicating that something went wrong specifically with MongoDB Client Encryption
  */
-export class MongoCryptError extends Error {
-  /** @internal */
+export class MongoCryptError extends MongoError {
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(message: string, options: { cause?: Error } = {}) {
     super(message, options);
   }
@@ -21,7 +32,17 @@ export class MongoCryptError extends Error {
  * An error indicating an invalid argument was provided to an encryption API.
  */
 export class MongoCryptInvalidArgumentError extends MongoCryptError {
-  /** @internal */
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(message: string) {
     super(message);
   }
@@ -36,7 +57,17 @@ export class MongoCryptInvalidArgumentError extends MongoCryptError {
  */
 export class MongoCryptCreateDataKeyError extends MongoCryptError {
   encryptedFields: Document;
-  /** @internal */
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(encryptedFields: Document, { cause }: { cause: Error }) {
     super(`Unable to complete creating data keys: ${cause.message}`, { cause });
     this.encryptedFields = encryptedFields;
@@ -53,7 +84,17 @@ export class MongoCryptCreateDataKeyError extends MongoCryptError {
  */
 export class MongoCryptCreateEncryptedCollectionError extends MongoCryptError {
   encryptedFields: Document;
-  /** @internal */
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(encryptedFields: Document, { cause }: { cause: Error }) {
     super(`Unable to create collection: ${cause.message}`, { cause });
     this.encryptedFields = encryptedFields;
@@ -71,7 +112,17 @@ export class MongoCryptCreateEncryptedCollectionError extends MongoCryptError {
 export class MongoCryptAzureKMSRequestError extends MongoCryptError {
   /** The body of the http response that failed, if present. */
   body?: Document;
-  /** @internal */
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(message: string, body?: Document) {
     super(message);
     this.body = body;

src/cmap/connect.ts

@@ -502,7 +502,7 @@ function makeSocks5Connection(options: MakeConnectionOptions, callback: Callback
 function connectionFailureError(type: ErrorHandlerEventName, err: Error) {
   switch (type) {
     case 'error':
-      return new MongoNetworkError(err);
+      return new MongoNetworkError(MongoError.buildErrorMessage(err), { cause: err });
     case 'timeout':
       return new MongoNetworkTimeoutError('connection timed out');
     case 'close':

src/cmap/errors.ts

@@ -9,6 +9,17 @@ export class PoolClosedError extends MongoDriverError {
   /** The address of the connection pool */
   address: string;
 
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(pool: ConnectionPool) {
     super('Attempted to check out a connection from closed connection pool');
     this.address = pool.address;
@@ -27,11 +38,22 @@ export class PoolClearedError extends MongoNetworkError {
   /** The address of the connection pool */
   address: string;
 
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(pool: ConnectionPool, message?: string) {
     const errorMessage = message
       ? message
       : `Connection pool for ${pool.address} was cleared because another operation failed with: "${pool.serverError?.message}"`;
-    super(errorMessage);
+    super(errorMessage, pool.serverError ? { cause: pool.serverError } : undefined);
     this.address = pool.address;
 
     this.addErrorLabel(MongoErrorLabel.RetryableWriteError);
@@ -47,6 +69,17 @@ export class PoolClearedError extends MongoNetworkError {
  * @category Error
  */
 export class PoolClearedOnNetworkError extends PoolClearedError {
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(pool: ConnectionPool) {
     super(pool, `Connection to ${pool.address} interrupted due to server monitor timeout`);
   }
@@ -64,6 +97,17 @@ export class WaitQueueTimeoutError extends MongoDriverError {
   /** The address of the connection pool */
   address: string;
 
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
   constructor(message: string, address: string) {
     super(message);
     this.address = address;