feat(shell-api): add shell helpers for checkMetadataConsistency MONGOSH-1432 (#1489)

* Add shell helpers foir checkMetadataConsistency

* properly typed cursors

* fixes

* missing help & autocomplete tests

Author: lerouxb

packages/autocomplete/src/index.spec.ts

@@ -281,8 +281,10 @@ describe('completer.completer', () => {
         .filter(c =>
           ![
             'count', 'update', 'remove', 'insert', 'save', 'findAndModify', 'reIndex', 'mapReduce',
-            // search index helpers are 6.0+
-            'getSearchIndexes', 'createSearchIndex', 'createSearchIndexes', 'dropSearchIndex', 'updateSearchIndex'
+            // 6.0+
+            'getSearchIndexes', 'createSearchIndex', 'createSearchIndexes', 'dropSearchIndex', 'updateSearchIndex',
+            // 7.0+
+            'checkMetadataConsistency'
           ].includes(c)
         )
         .map(c => `${i}${c}`);

packages/i18n/src/locales/en_US.ts

@@ -699,6 +699,11 @@ const translations: Catalog = {
               description: 'Starts or stops collecting metrics about reads and writes against an unsharded or sharded collection.',
               example: 'db.coll.configureQueryAnalyzer(options)'
             },
+            checkMetadataConsistency: {
+              link: 'https://docs.mongodb.com/manual/reference/method/db.collection.checkMetadataConsistency',
+              description: 'Returns a cursor with information about metadata inconsistencies',
+              example: 'db.coll.checkMetadataConsistency(<options>)'
+            },
             getSearchIndexes: {
               link: 'https://docs.mongodb.com/manual/reference/method/db.collection.getSearchIndexes',
               description: 'Returns an array that holds a list of documents that identify and describe the existing search indexes on the collection.',
@@ -1346,6 +1351,11 @@ const translations: Catalog = {
             },
             setSecondaryOk: {
               description: 'This method is deprecated. Use db.getMongo().setReadPref() instead'
+            },
+            checkMetadataConsistency: {
+              link: 'https://docs.mongodb.com/manual/reference/method/db.checkMetadataConsistency',
+              description: 'Returns a cursor with information about metadata inconsistencies',
+              example: 'db.checkMetadataConsistency(<options>)'
             }
           }
         }
@@ -1441,6 +1451,66 @@ const translations: Catalog = {
           description: 'Explainable Cursor. See the Cursor class help methods for more information'
         }
       },
+      RunCommandCursor: {
+        help: {
+          description: 'RunCommandCursor Class',
+          attributes: {
+            batchSize: {
+              description: 'Specifies the number of documents to return in each batch of the response from the MongoDB instance.',
+            },
+            close: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.close',
+              description: 'Instructs the server to close a cursor and free associated server resources. The server will automatically close cursors that have no remaining results, as well as cursors that have been idle for a period of time and lack the cursor.noCursorTimeout() option.',
+            },
+            forEach: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.forEach',
+              description: 'Iterates the cursor to apply a JavaScript function to each document from the cursor.',
+            },
+            hasNext: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.hasNext',
+              description: 'cursor.hasNext() returns true if the cursor returned by the db.collection.aggregate() can iterate further to return more documents. NOTE: if the cursor is tailable with awaitData then hasNext will block until a document is returned. To check if a document is in the cursor\'s batch without waiting, use tryNext instead',
+            },
+            isClosed: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.isClosed',
+              description: 'Returns true if the cursor is closed.',
+            },
+            isExhausted: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.isExhausted',
+              description: 'cursor.isExhausted() returns true if the cursor is closed and there are no remaining objects in the batch.',
+            },
+            itcount: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.itcount',
+              description: 'Counts the number of documents remaining in a cursor. itcount() is similar to cursor.count(), but actually executes the query on an existing iterator, exhausting its contents in the process.',
+            },
+            map: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.map',
+              description: 'Applies the first argument, a function, to each document visited by the cursor and collects the return values from successive application into an array.',
+            },
+            maxTimeMS: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.maxTimeMS',
+              description: 'Specifies a cumulative time limit in milliseconds for processing operations on a cursor.',
+            },
+            next: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.next',
+              description: 'The next document in the cursor returned by the db.collection.aggregate() method. NOTE: if the cursor is tailable with awaitData then next will block until a document is returned. To check if a document is in the cursor\'s batch without waiting, use tryNext instead',
+            },
+            objsLeftInBatch: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.objsLeftInBatch',
+              description: 'cursor.objsLeftInBatch() returns the number of documents remaining in the current batch.',
+            },
+            pretty: {
+              description: 'Deprecated. The shell provides auto-formatting so this method is no longer useful'
+            },
+            toArray: {
+              link: 'https://docs.mongodb.com/manual/reference/method/cursor.toArray',
+              description: 'The toArray() method returns an array that contains all the documents from a cursor. The method iterates completely the cursor, loading all the documents into RAM and exhausting the cursor.',
+            },
+            tryNext: {
+              description: 'If a document is in the cursor\'s batch it will be returned, otherwise null will be returned'
+            }
+          }
+        }
+      },
       ReplicaSet: {
         help: {
           description: 'Replica Set Class',
@@ -1710,6 +1780,11 @@ const translations: Catalog = {
               description: 'Re-enable auto-merge on one collection',
               example: 'sh.enableAutoMerger(ns)',
             },
+            checkMetadataConsistency: {
+              link: 'https://docs.mongodb.com/manual/reference/method/sh.checkMetadataConsistency',
+              description: 'Returns a cursor with information about metadata inconsistencies',
+              example: 'sh.checkMetadataConsistency(<options>)'
+            }
           }
         }
       },

packages/service-provider-core/src/admin.ts

@@ -30,6 +30,13 @@ export interface CreateEncryptedCollectionOptions {
   masterKey?: AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions;
 }
 
+export interface CheckMetadataConsistencyOptions {
+  cursor?: {
+      batchSize: number
+  },
+  checkIndexes?: 1
+}
+
 export default interface Admin {
   /**
    * What platform (Compass/CLI/Browser)

packages/service-provider-core/src/all-transport-types.ts

@@ -21,6 +21,7 @@ export type {
   ClusterTime,
   FindCursor,
   CursorFlag,
+  RunCommandCursor,
   Db,
   DbOptions,
   DeleteOptions,

packages/service-provider-core/src/index.ts

@@ -27,7 +27,7 @@ export * from './all-fle-types';
 
 export { MapReduceOptions, FinalizeFunction } from './map-reduce-options';
 
-export { CreateEncryptedCollectionOptions } from './admin';
+export { CreateEncryptedCollectionOptions, CheckMetadataConsistencyOptions } from './admin';
 
 const bson = {
   ObjectId,

packages/service-provider-core/src/writable.ts

@@ -1,3 +1,4 @@
+import { RunCommandCursor, RunCursorCommandOptions } from 'mongodb';
 import type {
   Document,
   InsertOneOptions,
@@ -58,6 +59,20 @@ export default interface Writable {
     dbOptions?: DbOptions
   ): Promise<Document>;
 
+  /**
+   * @param {String} db - the db name
+   * @param spec
+   * @param options
+   * @param {DbOptions} dbOptions - The database options
+   * @return {Promise<Document>}
+   */
+  runCursorCommand(
+    db: string,
+    spec: Document,
+    options: RunCursorCommandOptions,
+    dbOptions?: DbOptions
+  ): RunCommandCursor;
+
   /**
    * Drop a database
    *

packages/service-provider-server/src/cli-service-provider.spec.ts

@@ -370,6 +370,32 @@ describe('CliServiceProvider', () => {
     });
   });
 
+  describe('#runCursorCommand', () => {
+    let clientStub: any;
+    let dbStub: any;
+    const commandResult = 'a-cursor';
+
+    beforeEach(() => {
+      dbStub = stubInterface<Db>();
+      clientStub = stubInterface<MongoClient>();
+      dbStub.runCursorCommand.returns(commandResult);
+      clientStub.db.returns(dbStub);
+      serviceProvider = new CliServiceProvider(clientStub, bus, dummyOptions);
+    });
+
+    afterEach(() => {
+      dbStub = null;
+      clientStub = null;
+      serviceProvider = null;
+    });
+
+    it('executes the command against the database', () => {
+      const result = serviceProvider.runCursorCommand('admin', { checkMetadataConsistency: 1 });
+      expect(result).to.deep.equal(commandResult);
+      expect(dbStub.runCursorCommand).to.have.been.calledWith({ checkMetadataConsistency: 1 });
+    });
+  });
+
   describe('#updateOne', () => {
     const filter = { name: 'Aphex Twin' };
     const update = { $set: { name: 'Richard James' } };

packages/service-provider-server/src/cli-service-provider.ts

@@ -7,7 +7,9 @@ import {
   ReadPreferenceFromOptions,
   ReadPreferenceLike,
   OperationOptions,
-  BSON
+  BSON,
+  RunCommandCursor,
+  RunCursorCommandOptions
 } from 'mongodb';
 
 import {
@@ -830,6 +832,28 @@ class CliServiceProvider extends ServiceProviderCore implements ServiceProvider
     return result as { ok: 1 };
   }
 
+  /**
+   * Run a command against the database that returns a cursor.
+   *
+   * @param {String} database - The database name.
+   * @param {Object} spec - The command specification.
+   * @param {Object} options - The command  options.
+   * @param {Object} dbOptions - The connection-wide database options.
+   */
+  runCursorCommand(
+    database: string,
+    spec: Document = {},
+    options: RunCursorCommandOptions = {},
+    dbOptions?: DbOptions
+  ): RunCommandCursor {
+    options = { ...this.baseCmdOptions, ...options };
+    const db = this.db(database, dbOptions);
+    return db.runCursorCommand(
+      spec,
+      options
+    );
+  }
+
   /**
    * list databases.
    *

packages/shell-api/src/abstract-cursor.ts

@@ -4,21 +4,20 @@ import {
   returnType,
   ShellApiWithMongoClass,
   returnsPromise,
-  apiVersions
 } from './decorators';
 import type Mongo from './mongo';
 import type {
   Document,
-  ExplainVerbosityLike,
   FindCursor as ServiceProviderCursor,
   AggregationCursor as ServiceProviderAggregationCursor,
+  RunCommandCursor as ServiceProviderRunCommandCursor
 } from '@mongosh/service-provider-core';
 import { asPrintable } from './enums';
 import { CursorIterationResult } from './result';
-import { iterate, validateExplainableVerbosity, markAsExplainOutput } from './helpers';
+import { iterate } from './helpers';
 
 @shellApiClassNoHelp
-export abstract class AbstractCursor<CursorType extends ServiceProviderAggregationCursor | ServiceProviderCursor> extends ShellApiWithMongoClass {
+export abstract class AbstractCursor<CursorType extends ServiceProviderAggregationCursor | ServiceProviderCursor | ServiceProviderRunCommandCursor> extends ShellApiWithMongoClass {
   _mongo: Mongo;
   _cursor: CursorType;
   _transform: ((doc: any) => any) | null;
@@ -147,57 +146,7 @@ export abstract class AbstractCursor<CursorType extends ServiceProviderAggregati
     return result;
   }
 
-  @returnType('this')
-  projection(spec: Document): this {
-    this._cursor.project(spec);
-    return this;
-  }
-
-  @returnType('this')
-  skip(value: number): this {
-    this._cursor.skip(value);
-    return this;
-  }
-
-  @returnType('this')
-  sort(spec: Document): this {
-    this._cursor.sort(spec);
-    return this;
-  }
-
   objsLeftInBatch(): number {
     return this._cursor.bufferedCount();
   }
-
-  @returnsPromise
-  @apiVersions([1])
-  async explain(verbosity?: ExplainVerbosityLike): Promise<any> {
-    // TODO: @maurizio we should probably move this in the Explain class?
-    // NOTE: the node driver always returns the full explain plan
-    // for Cursor and the queryPlanner explain for AggregationCursor.
-    if (verbosity !== undefined) {
-      verbosity = validateExplainableVerbosity(verbosity);
-    }
-    const fullExplain: any = await this._cursor.explain(verbosity);
-
-    const explain: any = {
-      ...fullExplain
-    };
-
-    if (
-      verbosity !== 'executionStats' &&
-      verbosity !== 'allPlansExecution' &&
-      explain.executionStats
-    ) {
-      delete explain.executionStats;
-    }
-
-    if (verbosity === 'executionStats' &&
-      explain.executionStats &&
-      explain.executionStats.allPlansExecution) {
-      delete explain.executionStats.allPlansExecution;
-    }
-
-    return markAsExplainOutput(explain);
-  }
 }

packages/shell-api/src/aggregate-or-find-cursor.ts

@@ -0,0 +1,67 @@
+import {
+  shellApiClassNoHelp,
+  returnType,
+  returnsPromise,
+  apiVersions
+} from './decorators';
+import type {
+  Document,
+  ExplainVerbosityLike,
+  FindCursor as ServiceProviderCursor,
+  AggregationCursor as ServiceProviderAggregationCursor,
+} from '@mongosh/service-provider-core';
+import { validateExplainableVerbosity, markAsExplainOutput } from './helpers';
+import { AbstractCursor } from './abstract-cursor';
+
+@shellApiClassNoHelp
+export abstract class AggregateOrFindCursor<CursorType extends ServiceProviderAggregationCursor | ServiceProviderCursor> extends AbstractCursor<CursorType> {
+  @returnType('this')
+  projection(spec: Document): this {
+    this._cursor.project(spec);
+    return this;
+  }
+
+  @returnType('this')
+  skip(value: number): this {
+    this._cursor.skip(value);
+    return this;
+  }
+
+  @returnType('this')
+  sort(spec: Document): this {
+    this._cursor.sort(spec);
+    return this;
+  }
+
+  @returnsPromise
+  @apiVersions([1])
+  async explain(verbosity?: ExplainVerbosityLike): Promise<any> {
+    // TODO: @maurizio we should probably move this in the Explain class?
+    // NOTE: the node driver always returns the full explain plan
+    // for Cursor and the queryPlanner explain for AggregationCursor.
+    if (verbosity !== undefined) {
+      verbosity = validateExplainableVerbosity(verbosity);
+    }
+    const fullExplain: any = await this._cursor.explain(verbosity);
+
+    const explain: any = {
+      ...fullExplain
+    };
+
+    if (
+      verbosity !== 'executionStats' &&
+      verbosity !== 'allPlansExecution' &&
+      explain.executionStats
+    ) {
+      delete explain.executionStats;
+    }
+
+    if (verbosity === 'executionStats' &&
+      explain.executionStats &&
+      explain.executionStats.allPlansExecution) {
+      delete explain.executionStats.allPlansExecution;
+    }
+
+    return markAsExplainOutput(explain);
+  }
+}