@lossless.org/client 0.1.0

package/ts/nosqldb/classes.mongoadministration.ts

@@ -0,0 +1,867 @@
+import * as plugins from './plugins.js';
+
+import type { SmartdataDb } from './classes.db.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+
+export interface ISmartdataMongoOperationOptions {
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface ISmartdataMongoReplicaSetExpectation
+extends ISmartdataMongoOperationOptions {
+  expectedSetName: string;
+  expectedMemberHost: string;
+}
+
+export interface ISmartdataMongoReplicaSetMember {
+  host: string;
+  health: number;
+  state: string;
+}
+
+export type TSmartdataMongoReplicaSetState =
+  | 'replication_disabled'
+  | 'uninitialized'
+  | 'exact_primary'
+  | 'exact_non_primary'
+  | 'divergent'
+  | 'unavailable';
+
+export interface ISmartdataMongoReplicaSetInspection {
+  state: TSmartdataMongoReplicaSetState;
+  durationMs: number;
+  observedSetName?: string;
+  observedMembers?: ISmartdataMongoReplicaSetMember[];
+}
+
+export interface ISmartdataMongoReplicaSetInitializationResult {
+  status: 'initiated' | 'already_configured';
+  topology: ISmartdataMongoReplicaSetInspection;
+}
+
+export type TSmartdataMongoTransactionReadinessFailureReason =
+  | 'aborted'
+  | 'timeout'
+  | 'unsupported_topology'
+  | 'unavailable'
+  | 'cleanup_failed';
+
+export type TSmartdataMongoTransactionReadinessResult =
+  | {
+      ready: true;
+      status: 'ready';
+      durationMs: number;
+    }
+  | {
+      ready: false;
+      status: 'unavailable';
+      reason: TSmartdataMongoTransactionReadinessFailureReason;
+      durationMs: number;
+    };
+
+export interface ISmartdataMongoDatabaseUserOptions
+extends ISmartdataMongoOperationOptions {
+  expectedDatabaseName: string;
+  username: string;
+  password: string;
+}
+
+export interface ISmartdataMongoDatabaseUserRemovalOptions
+extends ISmartdataMongoOperationOptions {
+  expectedDatabaseName: string;
+  username: string;
+}
+
+export interface ISmartdataMongoDatabaseDropOptions
+extends ISmartdataMongoOperationOptions {
+  expectedDatabaseName: string;
+  confirmationDatabaseName: string;
+}
+
+const mongoAdministrationDefaultTimeoutMs = 5_000;
+const mongoAdministrationMaximumTimeoutMs = 30_000;
+const transactionCapabilityCollectionName = '__smartdata_transaction_capability';
+
+interface ITransactionCapabilityProbe extends plugins.mongodb.BSON.Document {
+  _id: string;
+  probeId: string;
+  part: number;
+}
+
+const replicaSetNameRegex = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const replicaSetMemberRegex = /^([A-Za-z0-9][A-Za-z0-9.-]{0,252}):([0-9]{1,5})$/;
+const databaseNameRegex = /^[^/\\.\s"$*<>:|?\u0000]{1,63}$/;
+const databaseUsernameRegex = /^[^\u0000\r\n]{1,128}$/;
+
+const assertExactDataObject = (
+  valueArg: unknown,
+  expectedKeysArg: readonly string[],
+  descriptionArg: string,
+): Record<string, unknown> => {
+  if (
+    valueArg === null
+    || typeof valueArg !== 'object'
+    || Array.isArray(valueArg)
+    || Object.getPrototypeOf(valueArg) !== Object.prototype
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${descriptionArg} must be a plain object.`,
+    );
+  }
+  const keys = Reflect.ownKeys(valueArg);
+  if (keys.some((keyArg) => (
+    typeof keyArg !== 'string' || !expectedKeysArg.includes(keyArg)
+  ))) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${descriptionArg} has an invalid shape.`,
+    );
+  }
+  for (const key of keys as string[]) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (!descriptor || !('value' in descriptor)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${descriptionArg} must contain data properties only.`,
+      );
+    }
+  }
+  return valueArg as Record<string, unknown>;
+};
+
+const isAbortSignal = (valueArg: unknown): valueArg is AbortSignal => (
+  valueArg !== null
+  && typeof valueArg === 'object'
+  && typeof (valueArg as AbortSignal).aborted === 'boolean'
+  && typeof (valueArg as AbortSignal).addEventListener === 'function'
+);
+
+const assertOperationOptions = (
+  optionsArg: Record<string, unknown>,
+): Required<Pick<ISmartdataMongoOperationOptions, 'timeoutMs'>>
+& Pick<ISmartdataMongoOperationOptions, 'signal'> => {
+  const timeoutMs = optionsArg.timeoutMs ?? mongoAdministrationDefaultTimeoutMs;
+  if (
+    !Number.isSafeInteger(timeoutMs)
+    || (timeoutMs as number) <= 0
+    || (timeoutMs as number) > mongoAdministrationMaximumTimeoutMs
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `Mongo administration timeoutMs must be a positive safe integer no greater than ${mongoAdministrationMaximumTimeoutMs}.`,
+    );
+  }
+  if (optionsArg.signal !== undefined && !isAbortSignal(optionsArg.signal)) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Mongo administration signal must be an AbortSignal.',
+    );
+  }
+  return {
+    timeoutMs: timeoutMs as number,
+    signal: optionsArg.signal as AbortSignal | undefined,
+  };
+};
+
+const assertReplicaSetExpectation = (
+  optionsArg: ISmartdataMongoReplicaSetExpectation,
+): ISmartdataMongoReplicaSetExpectation & { timeoutMs: number } => {
+  const options = assertExactDataObject(
+    optionsArg,
+    ['expectedSetName', 'expectedMemberHost', 'timeoutMs', 'signal'],
+    'Mongo replica-set expectation',
+  );
+  if (
+    typeof options.expectedSetName !== 'string'
+    || !replicaSetNameRegex.test(options.expectedSetName)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Mongo expectedSetName must be a canonical replica-set name.',
+    );
+  }
+  if (typeof options.expectedMemberHost !== 'string') {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Mongo expectedMemberHost must be a canonical hostname and port.',
+    );
+  }
+  const memberMatch = replicaSetMemberRegex.exec(options.expectedMemberHost);
+  const port = memberMatch ? Number(memberMatch[2]) : 0;
+  if (!memberMatch || port < 1 || port > 65_535) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Mongo expectedMemberHost must be a canonical hostname and port.',
+    );
+  }
+  return {
+    expectedSetName: options.expectedSetName,
+    expectedMemberHost: options.expectedMemberHost,
+    ...assertOperationOptions(options),
+  };
+};
+
+const isMongoServerError = (
+  errorArg: unknown,
+  codeArg: number,
+  codeNameArg: string,
+): boolean => errorArg instanceof plugins.mongodb.MongoServerError
+  && (errorArg.code === codeArg || errorArg.codeName === codeNameArg);
+
+const isMongoTimeoutError = (errorArg: unknown): boolean => (
+  errorArg instanceof plugins.mongodb.MongoOperationTimeoutError
+);
+
+const isUnsupportedTransactionTopologyError = (errorArg: unknown): boolean => (
+  isMongoServerError(errorArg, 20, 'IllegalOperation')
+  || isMongoServerError(errorArg, 263, 'OperationNotSupportedInTransaction')
+);
+
+const isUserAlreadyExistsError = (errorArg: unknown): boolean => (
+  isMongoServerError(errorArg, 51_003, 'UserAlreadyExists')
+  || isMongoServerError(errorArg, 51_003, 'Location51003')
+);
+
+const isUserNotFoundError = (errorArg: unknown): boolean => (
+  isMongoServerError(errorArg, 11, 'UserNotFound')
+);
+
+export class SmartdataMongoAdministration {
+  private readonly owner: SmartdataDb;
+  private readonly expectedMongoDb: plugins.mongodb.Db;
+  private readonly expectedMongoDbClient: plugins.mongodb.MongoClient;
+
+  constructor(ownerArg: SmartdataDb) {
+    if (
+      ownerArg.status !== 'connected'
+      || !ownerArg.mongoDb
+      || !ownerArg.mongoDbClient
+      || ownerArg.mongoDb.client !== ownerArg.mongoDbClient
+    ) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Mongo administration requires a connected SmartData database.',
+      );
+    }
+    this.owner = ownerArg;
+    this.expectedMongoDb = ownerArg.mongoDb;
+    this.expectedMongoDbClient = ownerArg.mongoDbClient;
+  }
+
+  public async inspectReplicaSet(
+    optionsArg: ISmartdataMongoReplicaSetExpectation,
+  ): Promise<ISmartdataMongoReplicaSetInspection> {
+    const options = assertReplicaSetExpectation(optionsArg);
+    const startedAt = performance.now();
+    const context = this.getConnectedContext();
+    if (options.signal?.aborted) {
+      return {
+        state: 'unavailable',
+        durationMs: performance.now() - startedAt,
+      };
+    }
+
+    let status: plugins.mongodb.BSON.Document;
+    try {
+      status = await context.mongoDb.admin().command(
+        { replSetGetStatus: 1 },
+        {
+          timeoutMS: options.timeoutMs,
+          signal: options.signal,
+        },
+      );
+    } catch (errorArg) {
+      if (!this.contextIsCurrent(context)) {
+        return this.createTopologyResult('unavailable', startedAt);
+      }
+      if (isMongoServerError(errorArg, 76, 'NoReplicationEnabled')) {
+        return this.createTopologyResult('replication_disabled', startedAt);
+      }
+      if (isMongoServerError(errorArg, 94, 'NotYetInitialized')) {
+        return this.createTopologyResult('uninitialized', startedAt);
+      }
+      return this.createTopologyResult('unavailable', startedAt);
+    }
+
+    if (!this.contextIsCurrent(context)) {
+      return this.createTopologyResult('unavailable', startedAt);
+    }
+    const observedSetName = typeof status.set === 'string' ? status.set : undefined;
+    const rawMembers = Array.isArray(status.members) ? status.members : [];
+    const observedMembers: ISmartdataMongoReplicaSetMember[] = [];
+    let membersWellFormed = Array.isArray(status.members);
+    for (const memberArg of rawMembers) {
+      if (!memberArg || typeof memberArg !== 'object' || Array.isArray(memberArg)) {
+        membersWellFormed = false;
+        continue;
+      }
+      const member = memberArg as Record<string, unknown>;
+      if (
+        typeof member.name !== 'string'
+        || typeof member.stateStr !== 'string'
+        || typeof member.health !== 'number'
+        || !Number.isFinite(member.health)
+      ) {
+        membersWellFormed = false;
+        continue;
+      }
+      observedMembers.push({
+        host: member.name,
+        health: member.health,
+        state: member.stateStr,
+      });
+    }
+    const exactConfiguration = membersWellFormed
+      && rawMembers.length === observedMembers.length
+      && observedSetName === options.expectedSetName
+      && observedMembers.length === 1
+      && observedMembers[0].host === options.expectedMemberHost;
+    if (!exactConfiguration) {
+      return {
+        state: 'divergent',
+        observedSetName,
+        observedMembers,
+        durationMs: performance.now() - startedAt,
+      };
+    }
+    const exactPrimary = status.myState === 1
+      && observedMembers[0].state === 'PRIMARY'
+      && observedMembers[0].health === 1;
+    return {
+      state: exactPrimary ? 'exact_primary' : 'exact_non_primary',
+      observedSetName,
+      observedMembers,
+      durationMs: performance.now() - startedAt,
+    };
+  }
+
+  public async initializeSingleMemberReplicaSet(
+    optionsArg: ISmartdataMongoReplicaSetExpectation,
+  ): Promise<ISmartdataMongoReplicaSetInitializationResult> {
+    const options = assertReplicaSetExpectation(optionsArg);
+    const topology = await this.inspectReplicaSet(options);
+    if (topology.state === 'exact_primary' || topology.state === 'exact_non_primary') {
+      return {
+        status: 'already_configured',
+        topology,
+      };
+    }
+    if (topology.state === 'divergent') {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Mongo replica-set configuration differs from the exact expected topology.',
+      );
+    }
+    if (topology.state === 'replication_disabled') {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Mongo replication must be enabled before replica-set initialization.',
+      );
+    }
+    if (topology.state !== 'uninitialized') {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Mongo replica-set topology is unavailable for initialization.',
+      );
+    }
+
+    const context = this.getConnectedContext();
+    let initializationStatus: ISmartdataMongoReplicaSetInitializationResult['status'] = 'initiated';
+    try {
+      const response = await context.mongoDb.admin().command(
+        {
+          replSetInitiate: {
+            _id: options.expectedSetName,
+            members: [{
+              _id: 0,
+              host: options.expectedMemberHost,
+            }],
+          },
+        },
+        {
+          timeoutMS: options.timeoutMs,
+          signal: options.signal,
+        },
+      );
+      if (response.ok !== 1 || !this.contextIsCurrent(context)) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          'Mongo did not acknowledge replica-set initialization.',
+        );
+      }
+    } catch (errorArg) {
+      if (isMongoServerError(errorArg, 23, 'AlreadyInitialized')) {
+        initializationStatus = 'already_configured';
+      } else {
+        if (errorArg instanceof SmartdataPersistenceError) throw errorArg;
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          'Mongo replica-set initialization failed.',
+        );
+      }
+    }
+
+    const initializedTopology = await this.inspectReplicaSet(options);
+    if (initializedTopology.state === 'divergent') {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Mongo initialized a replica-set topology that differs from the expectation.',
+      );
+    }
+    if (
+      initializedTopology.state !== 'exact_primary'
+      && initializedTopology.state !== 'exact_non_primary'
+    ) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Mongo replica-set initialization could not prove the exact expected topology.',
+      );
+    }
+    return {
+      status: initializationStatus,
+      topology: initializedTopology,
+    };
+  }
+
+  public async checkTransactionReadiness(
+    optionsArg: ISmartdataMongoOperationOptions = {},
+  ): Promise<TSmartdataMongoTransactionReadinessResult> {
+    const options = assertExactDataObject(
+      optionsArg,
+      ['timeoutMs', 'signal'],
+      'Mongo transaction-readiness options',
+    );
+    const boundedOptions = assertOperationOptions(options);
+    const startedAt = performance.now();
+    const context = this.getConnectedContext();
+    const probeId = globalThis.crypto.randomUUID();
+    const collection = context.mongoDb.collection<ITransactionCapabilityProbe>(
+      transactionCapabilityCollectionName,
+    );
+    let session: plugins.mongodb.ClientSession | undefined;
+    let failure: unknown;
+    let cleanupFailed = false;
+
+    try {
+      try {
+        await context.mongoDb.command(
+          { create: transactionCapabilityCollectionName },
+          {
+            timeoutMS: boundedOptions.timeoutMs,
+            signal: boundedOptions.signal,
+          },
+        );
+      } catch (errorArg) {
+        if (!isMongoServerError(errorArg, 48, 'NamespaceExists')) throw errorArg;
+      }
+      session = context.mongoDbClient.startSession();
+      session.startTransaction({
+        readConcern: { level: 'snapshot' },
+        writeConcern: { w: 'majority' },
+      });
+      const insertResponse = await context.mongoDb.command(
+        {
+          insert: transactionCapabilityCollectionName,
+          documents: [
+            { _id: `${probeId}:1`, probeId, part: 1 },
+            { _id: `${probeId}:2`, probeId, part: 2 },
+          ],
+          ordered: true,
+        },
+        {
+          session,
+          timeoutMS: boundedOptions.timeoutMs,
+          signal: boundedOptions.signal,
+        },
+      );
+      if (insertResponse.ok !== 1 || insertResponse.n !== 2) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          'Mongo transaction probe did not acknowledge both writes.',
+        );
+      }
+      const abortResponse = await context.mongoDb.admin().command(
+        {
+          abortTransaction: 1,
+          writeConcern: {
+            w: 'majority',
+            wtimeout: boundedOptions.timeoutMs,
+          },
+        },
+        {
+          session,
+          timeoutMS: boundedOptions.timeoutMs,
+          signal: boundedOptions.signal,
+        },
+      );
+      if (abortResponse.ok !== 1 || !this.contextIsCurrent(context)) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          'Mongo transaction probe did not acknowledge its abort.',
+        );
+      }
+      // The acknowledged raw command proves the server-side abort. Calling the
+      // public driver method afterwards advances its local transaction state;
+      // that method intentionally ignores most server-side abort errors.
+      await session.abortTransaction({ timeoutMS: boundedOptions.timeoutMs });
+      const remainingCount = await collection.countDocuments(
+        { probeId },
+        {
+          limit: 2,
+          timeoutMS: boundedOptions.timeoutMs,
+          signal: boundedOptions.signal,
+        },
+      );
+      if (remainingCount !== 0 || !this.contextIsCurrent(context)) {
+        cleanupFailed = remainingCount !== 0;
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          'Mongo transaction probe did not abort cleanly.',
+        );
+      }
+      return {
+        ready: true,
+        status: 'ready',
+        durationMs: performance.now() - startedAt,
+      };
+    } catch (errorArg) {
+      failure = errorArg;
+      if (session?.inTransaction()) {
+        try {
+          await session.abortTransaction({ timeoutMS: boundedOptions.timeoutMs });
+        } catch {
+          cleanupFailed = true;
+        }
+      }
+      try {
+        await collection.deleteMany(
+          { probeId },
+          { timeoutMS: boundedOptions.timeoutMs },
+        );
+      } catch {
+        cleanupFailed = true;
+      }
+    } finally {
+      await session?.endSession().catch(() => undefined);
+    }
+
+    let reason: TSmartdataMongoTransactionReadinessFailureReason;
+    if (cleanupFailed) {
+      reason = 'cleanup_failed';
+    } else if (boundedOptions.signal?.aborted) {
+      reason = 'aborted';
+    } else if (isMongoTimeoutError(failure)) {
+      reason = 'timeout';
+    } else if (isUnsupportedTransactionTopologyError(failure)) {
+      reason = 'unsupported_topology';
+    } else {
+      reason = 'unavailable';
+    }
+    return {
+      ready: false,
+      status: 'unavailable',
+      reason,
+      durationMs: performance.now() - startedAt,
+    };
+  }
+
+  public async ensureReadWriteDatabaseUser(
+    optionsArg: ISmartdataMongoDatabaseUserOptions,
+  ): Promise<{ status: 'created' | 'updated' }> {
+    const options = this.assertDatabaseUserOptions(optionsArg, true);
+    const context = this.getConnectedContext(options.expectedDatabaseName);
+    const usersInfo = await this.runAdministrationCommand(
+      context,
+      {
+        usersInfo: {
+          user: options.username,
+          db: options.expectedDatabaseName,
+        },
+      },
+      options,
+      'Mongo database-user inspection failed.',
+    );
+    if (!Array.isArray(usersInfo.users) || usersInfo.users.length > 1) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Mongo database-user inspection returned an invalid result.',
+      );
+    }
+    const updateCommand = {
+      updateUser: options.username,
+      pwd: options.password,
+      roles: [{ role: 'readWrite', db: options.expectedDatabaseName }],
+    };
+    if (usersInfo.users.length === 1) {
+      await this.runAdministrationCommand(
+        context,
+        updateCommand,
+        options,
+        'Mongo database-user reconciliation failed.',
+      );
+      return { status: 'updated' };
+    }
+
+    try {
+      await this.executeAdministrationCommand(
+        context,
+        {
+          createUser: options.username,
+          pwd: options.password,
+          roles: [{ role: 'readWrite', db: options.expectedDatabaseName }],
+        },
+        options,
+      );
+      return { status: 'created' };
+    } catch (errorArg) {
+      if (!isUserAlreadyExistsError(errorArg)) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          'Mongo database-user reconciliation failed.',
+        );
+      }
+    }
+
+    await this.runAdministrationCommand(
+      context,
+      updateCommand,
+      options,
+      'Mongo database-user reconciliation failed.',
+    );
+    return { status: 'updated' };
+  }
+
+  public async removeDatabaseUser(
+    optionsArg: ISmartdataMongoDatabaseUserRemovalOptions,
+  ): Promise<{ removed: boolean }> {
+    const options = this.assertDatabaseUserOptions(optionsArg, false);
+    const context = this.getConnectedContext(options.expectedDatabaseName);
+    const usersInfo = await this.runAdministrationCommand(
+      context,
+      {
+        usersInfo: {
+          user: options.username,
+          db: options.expectedDatabaseName,
+        },
+      },
+      options,
+      'Mongo database-user inspection failed.',
+    );
+    if (!Array.isArray(usersInfo.users) || usersInfo.users.length > 1) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Mongo database-user inspection returned an invalid result.',
+      );
+    }
+    if (usersInfo.users.length === 0) return { removed: false };
+    try {
+      await this.executeAdministrationCommand(
+        context,
+        { dropUser: options.username },
+        options,
+      );
+    } catch (errorArg) {
+      if (isUserNotFoundError(errorArg)) return { removed: false };
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Mongo database-user removal failed.',
+      );
+    }
+    return { removed: true };
+  }
+
+  public async dropDatabase(
+    optionsArg: ISmartdataMongoDatabaseDropOptions,
+  ): Promise<{ dropped: boolean }> {
+    const options = assertExactDataObject(
+      optionsArg,
+      ['expectedDatabaseName', 'confirmationDatabaseName', 'timeoutMs', 'signal'],
+      'Mongo database-drop options',
+    );
+    if (
+      typeof options.expectedDatabaseName !== 'string'
+      || !databaseNameRegex.test(options.expectedDatabaseName)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Mongo expectedDatabaseName must be a canonical database name.',
+      );
+    }
+    if (
+      options.confirmationDatabaseName !== options.expectedDatabaseName
+      || ['admin', 'config', 'local'].includes(options.expectedDatabaseName)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Mongo database-drop confirmation must exactly match a non-system database.',
+      );
+    }
+    const context = this.getConnectedContext(options.expectedDatabaseName);
+    await this.runAdministrationCommand(
+      context,
+      { dropDatabase: 1 },
+      assertOperationOptions(options),
+      'Mongo database removal failed.',
+    );
+    return { dropped: true };
+  }
+
+  private getConnectedContext(expectedDatabaseNameArg?: string): {
+    mongoDb: plugins.mongodb.Db;
+    mongoDbClient: plugins.mongodb.MongoClient;
+  } {
+    if (
+      this.owner.status !== 'connected'
+      || !this.owner.mongoDb
+      || !this.owner.mongoDbClient
+      || this.owner.mongoDb.client !== this.owner.mongoDbClient
+      || this.owner.mongoDb !== this.expectedMongoDb
+      || this.owner.mongoDbClient !== this.expectedMongoDbClient
+    ) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Mongo administration requires a connected SmartData database.',
+      );
+    }
+    if (
+      expectedDatabaseNameArg !== undefined
+      && (
+        this.owner.mongoDb.databaseName !== expectedDatabaseNameArg
+        || this.owner.smartdataOptions.mongoDbName !== expectedDatabaseNameArg
+      )
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Mongo expectedDatabaseName does not match the connected database.',
+      );
+    }
+    return {
+      mongoDb: this.owner.mongoDb,
+      mongoDbClient: this.owner.mongoDbClient,
+    };
+  }
+
+  private contextIsCurrent(contextArg: {
+    mongoDb: plugins.mongodb.Db;
+    mongoDbClient: plugins.mongodb.MongoClient;
+  }): boolean {
+    return this.owner.status === 'connected'
+      && this.owner.mongoDb === contextArg.mongoDb
+      && this.owner.mongoDbClient === contextArg.mongoDbClient;
+  }
+
+  private createTopologyResult(
+    stateArg: TSmartdataMongoReplicaSetState,
+    startedAtArg: number,
+  ): ISmartdataMongoReplicaSetInspection {
+    return {
+      state: stateArg,
+      durationMs: performance.now() - startedAtArg,
+    };
+  }
+
+  private assertDatabaseUserOptions<THasPassword extends boolean>(
+    optionsArg: THasPassword extends true
+      ? ISmartdataMongoDatabaseUserOptions
+      : ISmartdataMongoDatabaseUserRemovalOptions,
+    hasPasswordArg: THasPassword,
+  ): {
+    expectedDatabaseName: string;
+    username: string;
+    password: THasPassword extends true ? string : undefined;
+    timeoutMs: number;
+    signal?: AbortSignal;
+  } {
+    const allowedKeys = hasPasswordArg
+      ? ['expectedDatabaseName', 'username', 'password', 'timeoutMs', 'signal']
+      : ['expectedDatabaseName', 'username', 'timeoutMs', 'signal'];
+    const options = assertExactDataObject(
+      optionsArg,
+      allowedKeys,
+      'Mongo database-user options',
+    );
+    if (
+      typeof options.expectedDatabaseName !== 'string'
+      || !databaseNameRegex.test(options.expectedDatabaseName)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Mongo expectedDatabaseName must be a canonical database name.',
+      );
+    }
+    if (
+      typeof options.username !== 'string'
+      || !databaseUsernameRegex.test(options.username)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Mongo database username must be a bounded string without control characters.',
+      );
+    }
+    if (
+      hasPasswordArg
+      && (
+        typeof options.password !== 'string'
+        || options.password.length < 16
+        || options.password.length > 1024
+        || /[\u0000\r\n]/.test(options.password)
+      )
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Mongo database-user password must be a bounded nonempty secret without control characters.',
+      );
+    }
+    return {
+      expectedDatabaseName: options.expectedDatabaseName,
+      username: options.username,
+      password: (hasPasswordArg ? options.password : undefined) as (
+        THasPassword extends true ? string : undefined
+      ),
+      ...assertOperationOptions(options),
+    };
+  }
+
+  private async runAdministrationCommand(
+    contextArg: {
+      mongoDb: plugins.mongodb.Db;
+      mongoDbClient: plugins.mongodb.MongoClient;
+    },
+    commandArg: plugins.mongodb.BSON.Document,
+    optionsArg: { timeoutMs: number; signal?: AbortSignal },
+    failureMessageArg: string,
+  ): Promise<plugins.mongodb.BSON.Document> {
+    try {
+      return await this.executeAdministrationCommand(
+        contextArg,
+        commandArg,
+        optionsArg,
+      );
+    } catch {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        failureMessageArg,
+      );
+    }
+  }
+
+  private async executeAdministrationCommand(
+    contextArg: {
+      mongoDb: plugins.mongodb.Db;
+      mongoDbClient: plugins.mongodb.MongoClient;
+    },
+    commandArg: plugins.mongodb.BSON.Document,
+    optionsArg: { timeoutMs: number; signal?: AbortSignal },
+  ): Promise<plugins.mongodb.BSON.Document> {
+    const response = await contextArg.mongoDb.command(commandArg, {
+      timeoutMS: optionsArg.timeoutMs,
+      signal: optionsArg.signal,
+    });
+    if (response.ok !== 1 || !this.contextIsCurrent(contextArg)) {
+      throw new Error('Mongo administration acknowledgement was unavailable.');
+    }
+    return response;
+  }
+}