feat: add listShards helper

Author: nirinchev

packages/i18n/src/locales/en_US.ts

@@ -2148,6 +2148,12 @@ const translations: Catalog = {
                 'Abort the current unshardCollection operation on a given collection',
               example: 'sh.abortUnshardCollection(ns)',
             },
+            listShards: {
+              link: 'https://docs.mongodb.com/manual/reference/method/sh.listShards',
+              description:
+                'Returns a list of the configured shards in a sharded cluster',
+              example: 'sh.listShards()',
+            },
             isConfigShardEnabled: {
               link: 'https://docs.mongodb.com/manual/reference/method/sh.isConfigShardEnabled',
               description:

packages/shell-api/src/helpers.ts

@@ -683,21 +683,23 @@ export async function getPrintableShardStatus(
   return result;
 }
 
+export type ShardInfo = {
+  _id: string;
+  host: string;
+  state: number;
+  tags?: string[];
+  topologyTime: Timestamp;
+  replSetConfigVersion: Long;
+};
+
 export type ShardingStatusResult = {
   shardingVersion: {
     _id: number;
     clusterId: ObjectId;
     /** This gets deleted when it is returned from getPrintableShardStatus */
     currentVersion?: number;
   };
-  shards: {
-    _id: string;
-    host: string;
-    state: number;
-    tags: string[];
-    topologyTime: Timestamp;
-    replSetConfigVersion: Long;
-  }[];
+  shards: ShardInfo[];
   [mongoses: `${string} mongoses`]:
     | 'none'
     | {

packages/shell-api/src/shard.spec.ts

@@ -2109,6 +2109,75 @@ describe('Shard', function () {
       });
     });
 
+    describe('listShards', function () {
+      this.beforeEach(function () {
+        serviceProvider.runCommandWithCheck.resolves({
+          ok: 1,
+          msg: 'isdbgrid',
+        });
+      });
+
+      it('calls serviceProvider.runCommandWithCheck', async function () {
+        await shard.listShards();
+
+        expect(serviceProvider.runCommandWithCheck).to.have.been.calledWith(
+          ADMIN_DB,
+          {
+            listShards: 1,
+          }
+        );
+      });
+
+      it('returns the shards returned by runCommandWithCheck', async function () {
+        serviceProvider.runCommandWithCheck.resolves({
+          ok: 1,
+          msg: 'isdbgrid',
+          shards: [
+            {
+              _id: 'shard1',
+              host: 'shard1/foo.bar:27017',
+            },
+            {
+              _id: 'shard2',
+              host: 'shard2/foo.bar:27018',
+            },
+          ],
+        });
+        const result = await shard.listShards();
+        expect(result).to.deep.equal([
+          {
+            _id: 'shard1',
+            host: 'shard1/foo.bar:27017',
+          },
+          {
+            _id: 'shard2',
+            host: 'shard2/foo.bar:27018',
+          },
+        ]);
+      });
+
+      it('returns empty array when shards field is not present', async function () {
+        const result = await shard.listShards();
+        expect(result).to.deep.equal([]);
+      });
+
+      it('throws if serviceProvider.runCommandWithCheck rejects', async function () {
+        const expectedError = new Error('unreachable');
+        serviceProvider.runCommandWithCheck.rejects(expectedError);
+        const caughtError = await shard.listShards().catch((e) => e);
+        expect(caughtError).to.equal(expectedError);
+      });
+
+      it('throws if not mongos', async function () {
+        serviceProvider.runCommandWithCheck.resolves({
+          ok: 1,
+          msg: 'not dbgrid',
+        });
+        await shard.listShards();
+        expect(warnSpy.calledOnce).to.be.true;
+      });
+    });
+
     describe('isConfigShardEnabled', function () {
       this.beforeEach(function () {
         serviceProvider.runCommandWithCheck.resolves({
@@ -2193,6 +2262,7 @@ describe('Shard', function () {
             },
           ],
         });
+
         const result = await shard.isConfigShardEnabled();
         expect(result).to.deep.equal({
           enabled: true,
@@ -2207,13 +2277,14 @@ describe('Shard', function () {
         const caughtError = await shard.isConfigShardEnabled().catch((e) => e);
         expect(caughtError).to.equal(expectedError);
       });
+
       it('throws if not mongos', async function () {
         serviceProvider.runCommandWithCheck.resolves({
           ok: 1,
           msg: 'not dbgrid',
         });
         await shard.isConfigShardEnabled();
-        expect(warnSpy.calledOnce).to.equal(true);
+        expect(warnSpy.calledOnce).to.be.true;
       });
     });
   });
@@ -2463,15 +2534,11 @@ describe('Shard', function () {
     describe('tags', function () {
       it('creates a zone', async function () {
         expect((await sh.addShardTag(`${shardId}-1`, 'zone1')).ok).to.equal(1);
-        expect((await sh.status()).value.shards[1]?.tags).to.deep.equal([
-          'zone1',
-        ]);
+        expect((await sh.listShards())[1]?.tags).to.deep.equal(['zone1']);
         expect((await sh.addShardToZone(`${shardId}-0`, 'zone0')).ok).to.equal(
           1
         );
-        expect((await sh.status()).value.shards[0]?.tags).to.deep.equal([
-          'zone0',
-        ]);
+        expect((await sh.listShards())[0]?.tags).to.deep.equal(['zone0']);
       });
       it('sets a zone key range', async function () {
         expect(
@@ -2516,11 +2583,11 @@ describe('Shard', function () {
         expect(
           (await sh.removeShardFromZone(`${shardId}-1`, 'zone1')).ok
         ).to.equal(1);
-        expect((await sh.status()).value.shards[1].tags).to.deep.equal([]);
+        expect((await sh.listShards())[1].tags).to.deep.equal([]);
         expect((await sh.removeShardTag(`${shardId}-0`, 'zone0')).ok).to.equal(
           1
         );
-        expect((await sh.status()).value.shards[0].tags).to.deep.equal([]);
+        expect((await sh.listShards())[0].tags).to.deep.equal([]);
       });
       it('shows a full tag list when there are 20 or less tags', async function () {
         const db = instanceState.currentDb.getSiblingDB(dbName);
@@ -3281,6 +3348,27 @@ describe('Shard', function () {
         expect(await cursor.toArray()).to.deep.equal([]);
       });
     });
+
+    describe('listShards', function () {
+      it('returns the list of shards', async function () {
+        const result = await sh.listShards();
+        expect(result).to.be.an('array');
+        expect(result).to.have.lengthOf(2);
+
+        expect(result[0]._id).to.equal(`${shardId}-0`);
+        expect(result[0].host).to.contain(`${shardId}-0`);
+
+        expect(result[1]._id).to.equal(`${shardId}-1`);
+        expect(result[1].host).to.contain(`${shardId}-1`);
+      });
+
+      it('matches the output of status().shards', async function () {
+        const listShardsResult = await sh.listShards();
+        const statusResultShards = (await sh.status()).value.shards;
+
+        expect(listShardsResult).to.deep.equal(statusResultShards);
+      });
+    });
   });
 
   describe('integration chunks', function () {

packages/shell-api/src/shard.ts

@@ -12,7 +12,7 @@ import type {
   Document,
   CheckMetadataConsistencyOptions,
 } from '@mongosh/service-provider-core';
-import type { ShardingStatusResult } from './helpers';
+import type { ShardInfo, ShardingStatusResult } from './helpers';
 import {
   assertArgsDefinedType,
   getConfigDB,
@@ -812,16 +812,24 @@ export default class Shard extends ShellApiWithMongoClass {
     });
   }
 
+  @apiVersions([])
+  @returnsPromise
+  async listShards(): Promise<ShardInfo[]> {
+    this._emitShardApiCall('listShards', {});
+    await getConfigDB(this._database);
+
+    return (await this._database.adminCommand({ listShards: 1 })).shards ?? [];
+  }
+
   @serverVersions(['8.0.0', ServerVersions.latest])
   @apiVersions([])
   @returnsPromise
   async isConfigShardEnabled(): Promise<Document> {
     this._emitShardApiCall('isConfigShardEnabled', {});
     await getConfigDB(this._database);
 
-    const shards = (await this._database.adminCommand({ listShards: 1 }))[
-      'shards'
-    ] as Document[] | undefined;
+    const shards = (await this._database.adminCommand({ listShards: 1 }))
+      .shards as Document[] | undefined;
     const configShard = shards?.find((s) => s._id === 'config');
     if (!configShard) {
       return { enabled: false };