feat(NODE-5484)!: mark MongoError for internal use and remove Node14 …

…cause assignment logic (#3800)

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

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;