mongodb-data-service 22.23.2 → 22.23.5

package/lib/data-service.js

@@ -68,6 +68,11 @@ const maybePickNs = ([ns]) => {
 const isPromiseLike = (val) => {
     return 'then' in val && typeof val.then === 'function';
 };
+/**
+ * Translates the error message to something human readable.
+ * @param error - The error.
+ * @returns The error with message translated.
+ */
 const translateErrorMessage = (error) => {
     if (typeof error === 'string') {
         error = { message: error };
@@ -77,6 +82,13 @@ const translateErrorMessage = (error) => {
     }
     return error;
 };
+/**
+ * Decorator to do standard op handling that is applied to every public method
+ * of the data service
+ *
+ * - transform error message before throwing
+ * - log method success / failure
+ */
 function op(logId, pickLogAttrs = maybePickNs) {
     return function (target, context) {
         const opName = String(context.name);
@@ -166,6 +178,10 @@ let DataServiceImpl = (() => {
                 this._isConnecting = false;
                 this._useCRUDClient = true;
                 this._reauthenticationHandlers = new Set();
+                /**
+                 * Stores the most recent topology description from the server's SDAM events:
+                 * https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst#events
+                 */
                 this._lastSeenTopology = null;
                 this._isWritable = false;
                 this._emitter = new events_1.EventEmitter();
@@ -215,6 +231,9 @@ let DataServiceImpl = (() => {
                 return this;
             }
             getMongoClientConnectionOptions() {
+                // `notifyDeviceFlow` is a function which cannot be serialized for inclusion
+                // in the shell, `signal` is an abortSignal, and `allowedFlows` is turned
+                // into a function by the connection code.
                 return (0, lodash_1.omit)(this._mongoClientConnectionOptions, 'options.oidc.notifyDeviceFlow', 'options.oidc.signal', 'options.oidc.allowedFlows', 'options.oidc.customHttpOptions.agent');
             }
             getConnectionOptions() {
@@ -277,6 +296,7 @@ let DataServiceImpl = (() => {
                         },
                         {
                             $addFields: {
+                                // `avgObjSize` is the average of per-shard `avgObjSize` weighted by `count`
                                 avgObjSize: {
                                     $cond: {
                                         if: { $ne: ['$count', 0] },
@@ -298,6 +318,8 @@ let DataServiceImpl = (() => {
                 }
                 catch (error) {
                     const message = error.message;
+                    // We ignore errors for fetching collStats when requesting on an
+                    // unsupported collection type: either a view or a ADF
                     if (message.includes('not valid for Data Lake') ||
                         message.includes('is a view, not a collection')) {
                         return this._buildCollectionStats(databaseName, collectionName, {});
@@ -346,6 +368,8 @@ let DataServiceImpl = (() => {
             async _listCollections(databaseName, filter = {}, { nameOnly } = {}) {
                 try {
                     const cursor = this._database(databaseName, 'CRUD').listCollections(filter, { nameOnly });
+                    // Iterate instead of using .toArray() so we can emit
+                    // collection info update events as they come in.
                     const results = [];
                     for await (const result of cursor) {
                         if (!nameOnly) {
@@ -356,6 +380,15 @@ let DataServiceImpl = (() => {
                     return results;
                 }
                 catch (err) {
+                    // Currently Compass should not fail if listCollections failed for
+                    // any possible reason to preserve current behavior. We probably
+                    // want this to check at least that what we got back is a server
+                    // error and not a weird runtime issue on our side that can be
+                    // swallowed in this case, ideally we know exactly what server
+                    // errors we want to handle here and only avoid throwing in these
+                    // cases
+                    //
+                    // TODO: https://jira.mongodb.org/browse/COMPASS-5275
                     this._logger.warn((0, logger_1.mongoLogId)(1001000099), 'Failed to run listCollections', { message: err.message });
                     return [];
                 }
@@ -363,15 +396,29 @@ let DataServiceImpl = (() => {
             async listCollections(databaseName, filter = {}, { nameOnly, privileges = null, } = {}) {
                 const getCollectionsFromPrivileges = async () => {
                     const databases = (0, instance_detail_helper_2.getPrivilegesByDatabaseAndCollection)(await this._getPrivilegesOrFallback(privileges), ['find']);
-                    return Object.keys(databases[databaseName] || {})
-                        .filter(Boolean)
+                    return Object.keys(
+                    // Privileges might not have a database we are looking for
+                    databases[databaseName] || {})
+                        .filter(
+                    // Privileges can have collection name '' that indicates
+                    // privileges on all collections in the database, we don't want
+                    // those registered as "real" collection names
+                    Boolean)
                         .map((name) => ({ name }));
                 };
                 const [listedCollections, collectionsFromPrivileges] = await Promise.all([
                     this._listCollections(databaseName, filter, { nameOnly }),
+                    // If the filter is not empty, we can't meaningfully derive collections
+                    // from privileges and filter them as the criteria might include any key
+                    // from the listCollections result object and there is no such info in
+                    // privileges. Because of that we are ignoring privileges completely if
+                    // listCollections was called with a filter.
                     isEmptyObject(filter) ? getCollectionsFromPrivileges() : [],
                 ]);
-                const collections = uniqueBy([...collectionsFromPrivileges, ...listedCollections], 'name').map((coll) => (0, instance_detail_helper_2.adaptCollectionInfo)({ db: databaseName, ...coll }));
+                const collections = uniqueBy(
+                // NB: Order is important, we want listed collections to take precedence
+                // if they were fetched successfully
+                [...collectionsFromPrivileges, ...listedCollections], 'name').map((coll) => (0, instance_detail_helper_2.adaptCollectionInfo)({ db: databaseName, ...coll }));
                 return collections;
             }
             async listDatabases({ nameOnly, privileges = null, roles = null, } = {}) {
@@ -385,6 +432,14 @@ let DataServiceImpl = (() => {
                         return databases;
                     }
                     catch (err) {
+                        // Currently Compass should not fail if listDatabase failed for any
+                        // possible reason to preserve current behavior. We probably want this
+                        // to check at least that what we got back is a server error and not a
+                        // weird runtime issue on our side that can be swallowed in this case,
+                        // ideally we know exactly what server errors we want to handle here
+                        // and only avoid throwing in these cases
+                        //
+                        // TODO: https://jira.mongodb.org/browse/COMPASS-5275
                         this._logger.warn((0, logger_1.mongoLogId)(1001000098), 'Failed to run listDatabases', { message: err.message });
                         return [];
                     }
@@ -392,11 +447,24 @@ let DataServiceImpl = (() => {
                 const getDatabasesFromPrivileges = async () => {
                     const databases = (0, instance_detail_helper_2.getPrivilegesByDatabaseAndCollection)(await this._getPrivilegesOrFallback(privileges), ['find']);
                     return Object.keys(databases)
-                        .filter(Boolean)
+                        .filter(
+                    // For the roles created in admin database, the database name
+                    // can be '' meaning that it applies to all databases. We can't
+                    // meaningfully handle this in the UI so we are filtering these
+                    // out
+                    Boolean)
                         .map((name) => ({ name }));
                 };
                 const getDatabasesFromRoles = async () => {
-                    const databases = (0, instance_detail_helper_2.getDatabasesByRoles)(await this._getRolesOrFallback(roles), ['read', 'readWrite', 'dbAdmin', 'dbOwner']);
+                    const databases = (0, instance_detail_helper_2.getDatabasesByRoles)(await this._getRolesOrFallback(roles), 
+                    // https://jira.mongodb.org/browse/HELP-32199
+                    // Atlas shared tier MongoDB server version v5+ does not return
+                    // `authenticatedUserPrivileges` as part of the `connectionStatus`.
+                    // As a workaround we show the databases the user has
+                    // certain general built-in roles for.
+                    // This does not cover custom user roles which can
+                    // have custom privileges that we can't currently fetch.
+                    ['read', 'readWrite', 'dbAdmin', 'dbOwner']);
                     return databases.map((name) => ({ name }));
                 };
                 const [listedDatabases, databasesFromPrivileges, databasesFromRoles] = await Promise.all([
@@ -404,7 +472,10 @@ let DataServiceImpl = (() => {
                     getDatabasesFromPrivileges(),
                     getDatabasesFromRoles(),
                 ]);
-                const databases = uniqueBy([...databasesFromRoles, ...databasesFromPrivileges, ...listedDatabases], 'name').map((db) => {
+                const databases = uniqueBy(
+                // NB: Order is important, we want listed collections to take precedence
+                // if they were fetched successfully
+                [...databasesFromRoles, ...databasesFromPrivileges, ...listedDatabases], 'name').map((db) => {
                     return { _id: db.name, name: db.name, ...(0, instance_detail_helper_2.adaptDatabaseInfo)(db) };
                 });
                 return databases;
@@ -549,6 +620,7 @@ let DataServiceImpl = (() => {
                         .toArray();
                 }
                 catch {
+                    // ignore
                 }
                 const options = {};
                 const encryptedFieldsInfo = result?.options?.encryptedFields;
@@ -600,6 +672,8 @@ let DataServiceImpl = (() => {
             aggregateCursor(ns, pipeline, options = {}) {
                 return this._collection(ns, 'CRUD').aggregate(pipeline, options);
             }
+            // @ts-expect-error generic in the method trips up TS here resulting in
+            // Promise<unknown> is not assignable to Promise<Document[]>
             aggregate(ns, pipeline, options = {}, executionOptions) {
                 let cursor;
                 return this._cancellableOperation(async (session) => {
@@ -644,7 +718,7 @@ let DataServiceImpl = (() => {
                 return await coll.replaceOne(filter, replacement, options);
             }
             explainFind(ns, filter, options = {}, executionOptions) {
-                const verbosity = executionOptions?.explainVerbosity || mongodb_1.ExplainVerbosity.allPlansExecution;
+                const verbosity = executionOptions?.explainVerbosity || mongodb_1.ExplainVerbosity.executionStats;
                 let cursor;
                 return this._cancellableOperation(async (session) => {
                     cursor = this._collection(ns, 'CRUD').find(filter, {
@@ -657,7 +731,7 @@ let DataServiceImpl = (() => {
                 }, () => cursor?.close(), executionOptions?.abortSignal);
             }
             explainAggregate(ns, pipeline, options, executionOptions) {
-                const verbosity = executionOptions?.explainVerbosity || mongodb_1.ExplainVerbosity.queryPlanner;
+                const verbosity = executionOptions?.explainVerbosity || mongodb_1.ExplainVerbosity.executionStats;
                 let cursor;
                 return this._cancellableOperation(async (session) => {
                     cursor = this._collection(ns, 'CRUD').aggregate(pipeline, {
@@ -737,6 +811,7 @@ let DataServiceImpl = (() => {
             async instance() {
                 return {
                     ...(await (0, instance_detail_helper_2.getInstance)(this._initializedClient('META'), this._connectionOptions.connectionString)),
+                    // Need to get the CSFLE flag from the CRUD client, not the META one
                     csfleMode: this.getCSFLEMode(),
                 };
             }
@@ -748,13 +823,21 @@ let DataServiceImpl = (() => {
                 const coll = this._collection(ns, 'CRUD');
                 return await coll.insertMany(docs, options);
             }
-            async updateCollection(ns, flags = {}) {
+            async updateCollection(ns, 
+            // Collection name to update that will be passed to the collMod command will
+            // be derived from the provided namespace, this is why we are explicitly
+            // prohibiting to pass collMod flag here
+            flags = {}) {
                 const collectionName = this._collectionName(ns);
                 const db = this._database(ns, 'CRUD');
                 const result = await (0, run_command_1.runCommand)(db, {
+                    // Order of arguments is important here, collMod is a command name and it
+                    // should always be the first one in the object
                     collMod: collectionName,
                     ...flags,
                 });
+                // Reset the CSFLE-enabled client (if any) to clear any collection
+                // metadata caches that might still be active.
                 await this._resetCRUDClient();
                 return result;
             }
@@ -807,6 +890,7 @@ let DataServiceImpl = (() => {
                         size: size === 0 ? 0 : size || 1000,
                     },
                 });
+                // add $project stage if projection (fields) was specified
                 if (fields && Object.keys(fields).length > 0) {
                     pipeline.push({
                         $project: fields,
@@ -836,6 +920,9 @@ let DataServiceImpl = (() => {
                 });
             }
             isConnected() {
+                // This is better than just returning internal `_isConnecting` as this
+                // actually shows when the client is available on the NativeClient instance
+                // and connected
                 return !!this._metadataClient;
             }
             async _cancellableOperation(start, stop = () => Promise.resolve(), abortSignal) {
@@ -843,6 +930,7 @@ let DataServiceImpl = (() => {
                     return await start();
                 }
                 if (abortSignal.aborted) {
+                    // AbortSignal.reason is supported from node v17.2.0.
                     throw abortSignal.reason ?? (0, compass_utils_1.createCancelError)();
                 }
                 const session = this._startSession('CRUD');
@@ -904,10 +992,15 @@ let DataServiceImpl = (() => {
                         this._lastSeenTopology = evt.newDescription;
                         this._emitter.emit('topologyDescriptionChanged', evt);
                     });
+                    // Heartbeat events are fairly noisy. We put some effort into
+                    // making sure that we only log events that actually contain
+                    // meaningful information.
                     const heartbeatStatusMap = new Map();
                     const isSignificantDurationChange = (before, after) => {
+                        // Changes in pings below 200ms are not particularly concerning here.
                         before = Math.max(before, 200);
                         after = Math.max(after, 200);
+                        // Check if changes is at least 2× (in either direction).
                         return Math.abs(Math.log2(before / after)) >= 1;
                     };
                     client.on('serverHeartbeatSucceeded', (evt) => {
@@ -1007,6 +1100,8 @@ let DataServiceImpl = (() => {
                                 .find(filter, {
                                 session,
                                 maxTimeMS: remainingTimeoutMS(),
+                                // by using promoteValues: false we can spot BSON type changes
+                                // when diffing. ie. new Double(1) -> new Int32(1)
                                 promoteValues: false,
                             })
                                 .sort({ _id: 1 })
@@ -1038,8 +1133,14 @@ let DataServiceImpl = (() => {
                     }
                     catch (err) {
                         if (isTransactionAbortError(err)) {
+                            // The transaction was aborted while it was still calculating the
+                            // preview. Just return something here rather than erroring. No
+                            // reason to abort the transaction or end the session again because
+                            // we only got here because that already happened.
                             return { changes: [] };
                         }
+                        // The only way this if statement would be true is if aborting the
+                        // transaction and ending the session itself failed above. Unlikely.
                         if (session.inTransaction()) {
                             await session.abortTransaction();
                             await session.endSession();
@@ -1047,8 +1148,19 @@ let DataServiceImpl = (() => {
                         throw err;
                     }
                 }, async () => {
+                    // Rely on the session being killed when we cancel the operation. It can
+                    // take a few seconds before the driver reacts, but the Promise.race()
+                    // against the abort signal should cause the UI to immediately be
+                    // notified that the operation was cancelled. We don't abort the
+                    // transaction or end the session as well because the code we run inside
+                    // session.withTransaction() above would experience race conditions.
                 }, abortSignal);
             }
+            /**
+             * @param databaseName - The name of the database.
+             * @param collectionName - The name of the collection.
+             * @param data - The result of the collStats command.
+             */
             _buildCollectionStats(databaseName, collectionName, data) {
                 return {
                     ns: databaseName + '.' + collectionName,
@@ -1064,20 +1176,47 @@ let DataServiceImpl = (() => {
                     index_size: data.totalIndexSize ?? 0,
                 };
             }
+            /**
+             * Get the collection to operate on.
+             *
+             * @param ns - The namespace.
+             */
             _collection(ns, type) {
                 return this._initializedClient(type)
                     .db(this._databaseName(ns))
                     .collection(this._collectionName(ns));
             }
+            /**
+             * Get the database to operate on.
+             *
+             * @param ns - The namespace.
+             */
             _database(ns, type) {
                 return this._initializedClient(type).db(this._databaseName(ns));
             }
+            /**
+             * Get the collection name from a namespace.
+             *
+             * @param ns - The namespace in database.collection format.
+             */
             _collectionName(ns) {
                 return (0, mongodb_ns_1.default)(ns).collection;
             }
+            /**
+             * Get the database name from a namespace.
+             *
+             * @param ns - The namespace in database.collection format.
+             */
             _databaseName(ns) {
                 return (0, mongodb_ns_1.default)(ns).database;
             }
+            /**
+             * Determine if the hello response indicates a writable server.
+             *
+             * @param evt - The topology description changed event.
+             *
+             * @returns If the server is writable.
+             */
             _checkIsWritable(evt) {
                 return [...evt.newDescription.servers.values()].some((server) => server.isWritable);
             }
@@ -1095,10 +1234,12 @@ let DataServiceImpl = (() => {
             }
             async _resetCRUDClient() {
                 if (this.getCSFLEMode() === 'unavailable') {
+                    // No separate client in use, don't do anything
                     return;
                 }
                 const crudClient = this._crudClient;
                 if (!crudClient) {
+                    // In disconnected state, don't do anything
                     return;
                 }
                 const newClient = await crudClient[connect_mongo_client_1.createClonedClient]();
@@ -1107,6 +1248,9 @@ let DataServiceImpl = (() => {
                     await crudClient.close();
                 }
                 else {
+                    // If _crudClient has changed between start and end of
+                    // connection establishment, don't do anything, just
+                    // close and discard the new client.
                     await newClient.close();
                 }
             }
@@ -1255,15 +1399,13 @@ let DataServiceImpl = (() => {
             _explainFind_decorators = [op((0, logger_1.mongoLogId)(1001000046), ([ns, , , executionOptions]) => {
                     return {
                         ns,
-                        verbosity: executionOptions?.explainVerbosity ||
-                            mongodb_1.ExplainVerbosity.allPlansExecution,
+                        verbosity: executionOptions?.explainVerbosity || mongodb_1.ExplainVerbosity.executionStats,
                     };
                 })];
             _explainAggregate_decorators = [op((0, logger_1.mongoLogId)(1001000177), ([ns, , , executionOptions]) => {
                     return {
                         ns,
-                        verbosity: executionOptions?.explainVerbosity ||
-                            mongodb_1.ExplainVerbosity.allPlansExecution,
+                        verbosity: executionOptions?.explainVerbosity || mongodb_1.ExplainVerbosity.executionStats,
                     };
                 })];
             _indexes_decorators = [op((0, logger_1.mongoLogId)(1001000047))];
@@ -1368,7 +1510,12 @@ let DataServiceImpl = (() => {
             __esDecorate(_a, null, _dropStreamProcessor_decorators, { kind: "method", name: "dropStreamProcessor", static: false, private: false, access: { has: obj => "dropStreamProcessor" in obj, get: obj => obj.dropStreamProcessor } }, null, _instanceExtraInitializers);
         })(),
         (() => {
-            const assertNoExtraProps = (_cls) => {
+            const assertNoExtraProps = (
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            _cls) => {
+                // Checking that we are not exposing anything unexpected on our data service
+                // implementation. This file will not compile if there are more public methods
+                // on the DataServiceImpl than DataService interface allows
             };
             assertNoExtraProps(_a);
         })(),