mongodb 6.10.0 → 6.11.0-dev.20241123.sha.32f7ac63

package/src/timeout.ts

@@ -1,16 +1,20 @@
 import { clearTimeout, setTimeout } from 'timers';
 
-import { MongoInvalidArgumentError } from './error';
-import { noop } from './utils';
+import { type Document } from './bson';
+import { MongoInvalidArgumentError, MongoOperationTimeoutError, MongoRuntimeError } from './error';
+import { type ClientSession } from './sessions';
+import { csotMin, noop } from './utils';
 
 /** @internal */
 export class TimeoutError extends Error {
+  duration: number;
   override get name(): 'TimeoutError' {
     return 'TimeoutError';
   }
 
-  constructor(message: string, options?: { cause?: Error }) {
+  constructor(message: string, options: { cause?: Error; duration: number }) {
     super(message, options);
+    this.duration = options.duration;
   }
 
   static is(error: unknown): error is TimeoutError {
@@ -29,25 +33,38 @@ type Reject = Parameters<ConstructorParameters<typeof Promise<never>>[0]>[1];
  * if interacted with exclusively through its public API
  * */
 export class Timeout extends Promise<never> {
-  get [Symbol.toStringTag](): 'MongoDBTimeout' {
-    return 'MongoDBTimeout';
-  }
-
   private id?: NodeJS.Timeout;
 
   public readonly start: number;
   public ended: number | null = null;
   public duration: number;
-  public timedOut = false;
+  private timedOut = false;
+  public cleared = false;
+
+  get remainingTime(): number {
+    if (this.timedOut) return 0;
+    if (this.duration === 0) return Infinity;
+    return this.start + this.duration - Math.trunc(performance.now());
+  }
+
+  get timeElapsed(): number {
+    return Math.trunc(performance.now()) - this.start;
+  }
 
   /** Create a new timeout that expires in `duration` ms */
-  private constructor(executor: Executor = () => null, duration: number, unref = false) {
-    let reject!: Reject;
+  private constructor(
+    executor: Executor = () => null,
+    options?: { duration: number; unref?: true; rejection?: Error }
+  ) {
+    const duration = options?.duration ?? 0;
+    const unref = !!options?.unref;
+    const rejection = options?.rejection;
 
     if (duration < 0) {
       throw new MongoInvalidArgumentError('Cannot create a Timeout with a negative duration');
     }
 
+    let reject!: Reject;
     super((_, promiseReject) => {
       reject = promiseReject;
 
@@ -57,16 +74,20 @@ export class Timeout extends Promise<never> {
     this.duration = duration;
     this.start = Math.trunc(performance.now());
 
-    if (this.duration > 0) {
+    if (rejection == null && this.duration > 0) {
       this.id = setTimeout(() => {
         this.ended = Math.trunc(performance.now());
         this.timedOut = true;
-        reject(new TimeoutError(`Expired after ${duration}ms`));
+        reject(new TimeoutError(`Expired after ${duration}ms`, { duration }));
       }, this.duration);
       if (typeof this.id.unref === 'function' && unref) {
         // Ensure we do not keep the Node.js event loop running
         this.id.unref();
       }
+    } else if (rejection != null) {
+      this.ended = Math.trunc(performance.now());
+      this.timedOut = true;
+      reject(rejection);
     }
   }
 
@@ -76,20 +97,303 @@ export class Timeout extends Promise<never> {
   clear(): void {
     clearTimeout(this.id);
     this.id = undefined;
+    this.timedOut = false;
+    this.cleared = true;
   }
 
-  public static expires(durationMS: number, unref?: boolean): Timeout {
-    return new Timeout(undefined, durationMS, unref);
+  throwIfExpired(): void {
+    if (this.timedOut) throw new TimeoutError('Timed out', { duration: this.duration });
   }
 
-  static is(timeout: unknown): timeout is Timeout {
-    return (
-      typeof timeout === 'object' &&
-      timeout != null &&
-      Symbol.toStringTag in timeout &&
-      timeout[Symbol.toStringTag] === 'MongoDBTimeout' &&
-      'then' in timeout &&
-      typeof timeout.then === 'function'
-    );
+  public static expires(duration: number, unref?: true): Timeout {
+    return new Timeout(undefined, { duration, unref });
+  }
+
+  static override reject(rejection?: Error): Timeout {
+    return new Timeout(undefined, { duration: 0, unref: true, rejection });
+  }
+}
+
+/** @internal */
+export type TimeoutContextOptions = (LegacyTimeoutContextOptions | CSOTTimeoutContextOptions) & {
+  session?: ClientSession;
+};
+
+/** @internal */
+export type LegacyTimeoutContextOptions = {
+  serverSelectionTimeoutMS: number;
+  waitQueueTimeoutMS: number;
+  socketTimeoutMS?: number;
+};
+
+/** @internal */
+export type CSOTTimeoutContextOptions = {
+  timeoutMS: number;
+  serverSelectionTimeoutMS: number;
+  socketTimeoutMS?: number;
+};
+
+function isLegacyTimeoutContextOptions(v: unknown): v is LegacyTimeoutContextOptions {
+  return (
+    v != null &&
+    typeof v === 'object' &&
+    'serverSelectionTimeoutMS' in v &&
+    typeof v.serverSelectionTimeoutMS === 'number' &&
+    'waitQueueTimeoutMS' in v &&
+    typeof v.waitQueueTimeoutMS === 'number'
+  );
+}
+
+function isCSOTTimeoutContextOptions(v: unknown): v is CSOTTimeoutContextOptions {
+  return (
+    v != null &&
+    typeof v === 'object' &&
+    'serverSelectionTimeoutMS' in v &&
+    typeof v.serverSelectionTimeoutMS === 'number' &&
+    'timeoutMS' in v &&
+    typeof v.timeoutMS === 'number'
+  );
+}
+
+/** @internal */
+export abstract class TimeoutContext {
+  static create(options: TimeoutContextOptions): TimeoutContext {
+    if (options.session?.timeoutContext != null) return options.session?.timeoutContext;
+    if (isCSOTTimeoutContextOptions(options)) return new CSOTTimeoutContext(options);
+    else if (isLegacyTimeoutContextOptions(options)) return new LegacyTimeoutContext(options);
+    else throw new MongoRuntimeError('Unrecognized options');
+  }
+
+  abstract get maxTimeMS(): number | null;
+
+  abstract get serverSelectionTimeout(): Timeout | null;
+
+  abstract get connectionCheckoutTimeout(): Timeout | null;
+
+  abstract get clearServerSelectionTimeout(): boolean;
+
+  abstract get timeoutForSocketWrite(): Timeout | null;
+
+  abstract get timeoutForSocketRead(): Timeout | null;
+
+  abstract csotEnabled(): this is CSOTTimeoutContext;
+
+  abstract refresh(): void;
+
+  abstract clear(): void;
+
+  /** Returns a new instance of the TimeoutContext, with all timeouts refreshed and restarted. */
+  abstract refreshed(): TimeoutContext;
+
+  abstract addMaxTimeMSToCommand(command: Document, options: { omitMaxTimeMS?: boolean }): void;
+
+  abstract getSocketTimeoutMS(): number | undefined;
+}
+
+/** @internal */
+export class CSOTTimeoutContext extends TimeoutContext {
+  timeoutMS: number;
+  serverSelectionTimeoutMS: number;
+  socketTimeoutMS?: number;
+
+  clearServerSelectionTimeout: boolean;
+
+  private _serverSelectionTimeout?: Timeout | null;
+  private _connectionCheckoutTimeout?: Timeout | null;
+  public minRoundTripTime = 0;
+  public start: number;
+
+  constructor(options: CSOTTimeoutContextOptions) {
+    super();
+    this.start = Math.trunc(performance.now());
+
+    this.timeoutMS = options.timeoutMS;
+
+    this.serverSelectionTimeoutMS = options.serverSelectionTimeoutMS;
+
+    this.socketTimeoutMS = options.socketTimeoutMS;
+
+    this.clearServerSelectionTimeout = false;
+  }
+
+  get maxTimeMS(): number {
+    return this.remainingTimeMS - this.minRoundTripTime;
+  }
+
+  get remainingTimeMS() {
+    const timePassed = Math.trunc(performance.now()) - this.start;
+    return this.timeoutMS <= 0 ? Infinity : this.timeoutMS - timePassed;
+  }
+
+  csotEnabled(): this is CSOTTimeoutContext {
+    return true;
+  }
+
+  get serverSelectionTimeout(): Timeout | null {
+    // check for undefined
+    if (typeof this._serverSelectionTimeout !== 'object' || this._serverSelectionTimeout?.cleared) {
+      const { remainingTimeMS, serverSelectionTimeoutMS } = this;
+      if (remainingTimeMS <= 0)
+        return Timeout.reject(
+          new MongoOperationTimeoutError(`Timed out in server selection after ${this.timeoutMS}ms`)
+        );
+      const usingServerSelectionTimeoutMS =
+        serverSelectionTimeoutMS !== 0 &&
+        csotMin(remainingTimeMS, serverSelectionTimeoutMS) === serverSelectionTimeoutMS;
+      if (usingServerSelectionTimeoutMS) {
+        this._serverSelectionTimeout = Timeout.expires(serverSelectionTimeoutMS);
+      } else {
+        if (remainingTimeMS > 0 && Number.isFinite(remainingTimeMS)) {
+          this._serverSelectionTimeout = Timeout.expires(remainingTimeMS);
+        } else {
+          this._serverSelectionTimeout = null;
+        }
+      }
+    }
+
+    return this._serverSelectionTimeout;
+  }
+
+  get connectionCheckoutTimeout(): Timeout | null {
+    if (
+      typeof this._connectionCheckoutTimeout !== 'object' ||
+      this._connectionCheckoutTimeout?.cleared
+    ) {
+      if (typeof this._serverSelectionTimeout === 'object') {
+        // null or Timeout
+        this._connectionCheckoutTimeout = this._serverSelectionTimeout;
+      } else {
+        throw new MongoRuntimeError(
+          'Unreachable. If you are seeing this error, please file a ticket on the NODE driver project on Jira'
+        );
+      }
+    }
+    return this._connectionCheckoutTimeout;
+  }
+
+  get timeoutForSocketWrite(): Timeout | null {
+    const { remainingTimeMS } = this;
+    if (!Number.isFinite(remainingTimeMS)) return null;
+    if (remainingTimeMS > 0) return Timeout.expires(remainingTimeMS);
+    return Timeout.reject(new MongoOperationTimeoutError('Timed out before socket write'));
+  }
+
+  get timeoutForSocketRead(): Timeout | null {
+    const { remainingTimeMS } = this;
+    if (!Number.isFinite(remainingTimeMS)) return null;
+    if (remainingTimeMS > 0) return Timeout.expires(remainingTimeMS);
+    return Timeout.reject(new MongoOperationTimeoutError('Timed out before socket read'));
+  }
+
+  refresh(): void {
+    this.start = Math.trunc(performance.now());
+    this.minRoundTripTime = 0;
+    this._serverSelectionTimeout?.clear();
+    this._connectionCheckoutTimeout?.clear();
+  }
+
+  clear(): void {
+    this._serverSelectionTimeout?.clear();
+    this._connectionCheckoutTimeout?.clear();
+  }
+
+  /**
+   * @internal
+   * Throws a MongoOperationTimeoutError if the context has expired.
+   * If the context has not expired, returns the `remainingTimeMS`
+   **/
+  getRemainingTimeMSOrThrow(message?: string): number {
+    const { remainingTimeMS } = this;
+    if (remainingTimeMS <= 0)
+      throw new MongoOperationTimeoutError(message ?? `Expired after ${this.timeoutMS}ms`);
+    return remainingTimeMS;
+  }
+
+  /**
+   * @internal
+   * This method is intended to be used in situations where concurrent operation are on the same deadline, but cannot share a single `TimeoutContext` instance.
+   * Returns a new instance of `CSOTTimeoutContext` constructed with identical options, but setting the `start` property to `this.start`.
+   */
+  clone(): CSOTTimeoutContext {
+    const timeoutContext = new CSOTTimeoutContext({
+      timeoutMS: this.timeoutMS,
+      serverSelectionTimeoutMS: this.serverSelectionTimeoutMS
+    });
+    timeoutContext.start = this.start;
+    return timeoutContext;
+  }
+
+  override refreshed(): CSOTTimeoutContext {
+    return new CSOTTimeoutContext(this);
+  }
+
+  override addMaxTimeMSToCommand(command: Document, options: { omitMaxTimeMS?: boolean }): void {
+    if (options.omitMaxTimeMS) return;
+    const maxTimeMS = this.remainingTimeMS - this.minRoundTripTime;
+    if (maxTimeMS > 0 && Number.isFinite(maxTimeMS)) command.maxTimeMS = maxTimeMS;
+  }
+
+  override getSocketTimeoutMS(): number | undefined {
+    return 0;
+  }
+}
+
+/** @internal */
+export class LegacyTimeoutContext extends TimeoutContext {
+  options: LegacyTimeoutContextOptions;
+  clearServerSelectionTimeout: boolean;
+
+  constructor(options: LegacyTimeoutContextOptions) {
+    super();
+    this.options = options;
+    this.clearServerSelectionTimeout = true;
+  }
+
+  csotEnabled(): this is CSOTTimeoutContext {
+    return false;
+  }
+
+  get serverSelectionTimeout(): Timeout | null {
+    if (this.options.serverSelectionTimeoutMS != null && this.options.serverSelectionTimeoutMS > 0)
+      return Timeout.expires(this.options.serverSelectionTimeoutMS);
+    return null;
+  }
+
+  get connectionCheckoutTimeout(): Timeout | null {
+    if (this.options.waitQueueTimeoutMS != null && this.options.waitQueueTimeoutMS > 0)
+      return Timeout.expires(this.options.waitQueueTimeoutMS);
+    return null;
+  }
+
+  get timeoutForSocketWrite(): Timeout | null {
+    return null;
+  }
+
+  get timeoutForSocketRead(): Timeout | null {
+    return null;
+  }
+
+  refresh(): void {
+    return;
+  }
+
+  clear(): void {
+    return;
+  }
+
+  get maxTimeMS() {
+    return null;
+  }
+
+  override refreshed(): LegacyTimeoutContext {
+    return new LegacyTimeoutContext(this.options);
+  }
+
+  override addMaxTimeMSToCommand(_command: Document, _options: { omitMaxTimeMS?: boolean }): void {
+    // No max timeMS is added to commands in legacy timeout mode.
+  }
+
+  override getSocketTimeoutMS(): number | undefined {
+    return this.options.socketTimeoutMS;
   }
 }

package/src/transactions.ts

@@ -60,7 +60,7 @@ const COMMITTED_STATES: Set<TxnState> = new Set([
  * Configuration options for a transaction.
  * @public
  */
-export interface TransactionOptions extends CommandOperationOptions {
+export interface TransactionOptions extends Omit<CommandOperationOptions, 'timeoutMS'> {
   // TODO(NODE-3344): These options use the proper class forms of these settings, it should accept the basic enum values too
   /** A default read concern for commands in this transaction */
   readConcern?: ReadConcernLike;

package/src/utils.ts

@@ -26,7 +26,6 @@ import {
   MongoParseError,
   MongoRuntimeError
 } from './error';
-import type { Explain, ExplainVerbosity } from './explain';
 import type { MongoClient } from './mongo_client';
 import type { CommandOperationOptions, OperationParent } from './operations/command';
 import type { Hint, OperationOptions } from './operations/operation';
@@ -36,6 +35,7 @@ import { ServerType } from './sdam/common';
 import type { Server } from './sdam/server';
 import type { Topology } from './sdam/topology';
 import type { ClientSession } from './sessions';
+import { type TimeoutContextOptions } from './timeout';
 import { WriteConcern } from './write_concern';
 
 /**
@@ -245,32 +245,6 @@ export function decorateWithReadConcern(
   }
 }
 
-/**
- * Applies an explain to a given command.
- * @internal
- *
- * @param command - the command on which to apply the explain
- * @param options - the options containing the explain verbosity
- */
-export function decorateWithExplain(
-  command: Document,
-  explain: Explain
-): {
-  explain: Document;
-  verbosity: ExplainVerbosity;
-  maxTimeMS?: number;
-} {
-  type ExplainCommand = ReturnType<typeof decorateWithExplain>;
-  const { verbosity, maxTimeMS } = explain;
-  const baseCommand: ExplainCommand = { explain: command, verbosity };
-
-  if (typeof maxTimeMS === 'number') {
-    baseCommand.maxTimeMS = maxTimeMS;
-  }
-
-  return baseCommand;
-}
-
 /**
  * @internal
  */
@@ -515,9 +489,25 @@ export function hasAtomicOperators(doc: Document | Document[]): boolean {
   return keys.length > 0 && keys[0][0] === '$';
 }
 
+export function resolveTimeoutOptions<T extends Partial<TimeoutContextOptions>>(
+  client: MongoClient,
+  options: T
+): T &
+  Pick<
+    MongoClient['s']['options'],
+    'timeoutMS' | 'serverSelectionTimeoutMS' | 'waitQueueTimeoutMS' | 'socketTimeoutMS'
+  > {
+  const { socketTimeoutMS, serverSelectionTimeoutMS, waitQueueTimeoutMS, timeoutMS } =
+    client.s.options;
+  return { socketTimeoutMS, serverSelectionTimeoutMS, waitQueueTimeoutMS, timeoutMS, ...options };
+}
 /**
  * Merge inherited properties from parent into options, prioritizing values from options,
  * then values from parent.
+ *
+ * @param parent - An optional owning class of the operation being run. ex. Db/Collection/MongoClient.
+ * @param options - The options passed to the operation method.
+ *
  * @internal
  */
 export function resolveOptions<T extends CommandOperationOptions>(
@@ -526,25 +516,43 @@ export function resolveOptions<T extends CommandOperationOptions>(
 ): T {
   const result: T = Object.assign({}, options, resolveBSONOptions(options, parent));
 
+  const timeoutMS = options?.timeoutMS ?? parent?.timeoutMS;
   // Users cannot pass a readConcern/writeConcern to operations in a transaction
   const session = options?.session;
+
   if (!session?.inTransaction()) {
     const readConcern = ReadConcern.fromOptions(options) ?? parent?.readConcern;
     if (readConcern) {
       result.readConcern = readConcern;
     }
 
-    const writeConcern = WriteConcern.fromOptions(options) ?? parent?.writeConcern;
+    let writeConcern = WriteConcern.fromOptions(options) ?? parent?.writeConcern;
     if (writeConcern) {
+      if (timeoutMS != null) {
+        writeConcern = WriteConcern.fromOptions({
+          ...writeConcern,
+          wtimeout: undefined,
+          wtimeoutMS: undefined
+        });
+      }
       result.writeConcern = writeConcern;
     }
   }
 
+  result.timeoutMS = timeoutMS;
+
   const readPreference = ReadPreference.fromOptions(options) ?? parent?.readPreference;
   if (readPreference) {
     result.readPreference = readPreference;
   }
 
+  const isConvenientTransaction = session?.explicit && session?.timeoutContext != null;
+  if (isConvenientTransaction && options?.timeoutMS != null) {
+    throw new MongoInvalidArgumentError(
+      'An operation cannot be given a timeoutMS setting when inside a withTransaction call that has a timeoutMS setting'
+    );
+  }
+
   return result;
 }
 
@@ -1097,8 +1105,11 @@ export function shuffle<T>(sequence: Iterable<T>, limit = 0): Array<T> {
   return limit % items.length === 0 ? items : items.slice(lowerBound);
 }
 
-// TODO(NODE-4936): read concern eligibility for commands should be codified in command construction
-// @see https://github.com/mongodb/specifications/blob/master/source/read-write-concern/read-write-concern.rst#read-concern
+/**
+ * TODO(NODE-4936): read concern eligibility for commands should be codified in command construction
+ * @internal
+ * @see https://github.com/mongodb/specifications/blob/master/source/read-write-concern/read-write-concern.md#read-concern
+ */
 export function commandSupportsReadConcern(command: Document): boolean {
   if (command.aggregate || command.count || command.distinct || command.find || command.geoNear) {
     return true;
@@ -1398,6 +1409,12 @@ export async function fileIsAccessible(fileName: string, mode?: number) {
   }
 }
 
+export function csotMin(duration1: number, duration2: number): number {
+  if (duration1 === 0) return duration2;
+  if (duration2 === 0) return duration1;
+  return Math.min(duration1, duration2);
+}
+
 export function noop() {
   return;
 }

package/src/write_concern.ts

@@ -15,7 +15,9 @@ export interface WriteConcernOptions {
 export interface WriteConcernSettings {
   /** The write concern */
   w?: W;
-  /** The write concern timeout */
+  /**
+   * The write concern timeout.
+   */
   wtimeoutMS?: number;
   /** The journal write concern */
   journal?: boolean;
@@ -28,7 +30,6 @@ export interface WriteConcernSettings {
   j?: boolean;
   /**
    * The write concern timeout.
-   * @deprecated Will be removed in the next major version. Please use the wtimeoutMS option.
    */
   wtimeout?: number;
   /**
@@ -65,7 +66,9 @@ export class WriteConcern {
   readonly w?: W;
   /** Request acknowledgment that the write operation has been written to the on-disk journal */
   readonly journal?: boolean;
-  /** Specify a time limit to prevent write operations from blocking indefinitely */
+  /**
+   * Specify a time limit to prevent write operations from blocking indefinitely.
+   */
   readonly wtimeoutMS?: number;
   /**
    * Specify a time limit to prevent write operations from blocking indefinitely.