mongodb 6.5.0 → 6.6.0

package/src/sdam/monitor.ts

@@ -8,8 +8,14 @@ import { LEGACY_HELLO_COMMAND } from '../constants';
 import { MongoError, MongoErrorLabel, MongoNetworkTimeoutError } from '../error';
 import { MongoLoggableComponent } from '../mongo_logger';
 import { CancellationToken, TypedEventEmitter } from '../mongo_types';
-import type { Callback, EventEmitterWithState } from '../utils';
-import { calculateDurationInMs, makeStateMachine, now, ns } from '../utils';
+import {
+  calculateDurationInMs,
+  type Callback,
+  type EventEmitterWithState,
+  makeStateMachine,
+  now,
+  ns
+} from '../utils';
 import { ServerType, STATE_CLOSED, STATE_CLOSING } from './common';
 import {
   ServerHeartbeatFailedEvent,
@@ -25,8 +31,6 @@ const kServer = Symbol('server');
 const kMonitorId = Symbol('monitorId');
 /** @internal */
 const kCancellationToken = Symbol('cancellationToken');
-/** @internal */
-const kRoundTripTime = Symbol('roundTripTime');
 
 const STATE_IDLE = 'idle';
 const STATE_MONITORING = 'monitoring';
@@ -100,6 +104,8 @@ export class Monitor extends TypedEventEmitter<MonitorEvents> {
   rttPinger?: RTTPinger;
   /** @internal */
   override component = MongoLoggableComponent.TOPOLOGY;
+  /** @internal */
+  private rttSampler: RTTSampler;
 
   constructor(server: Server, options: MonitorOptions) {
     super();
@@ -121,6 +127,7 @@ export class Monitor extends TypedEventEmitter<MonitorEvents> {
     });
     this.isRunningInFaasEnv = getFAASEnv() != null;
     this.mongoLogger = this[kServer].topology.client?.mongoLogger;
+    this.rttSampler = new RTTSampler(10);
 
     const cancellationToken = this[kCancellationToken];
     // TODO: refactor this to pull it directly from the pool, requires new ConnectionPool integration
@@ -203,6 +210,26 @@ export class Monitor extends TypedEventEmitter<MonitorEvents> {
     this.emit('close');
     stateTransition(this, STATE_CLOSED);
   }
+
+  get roundTripTime(): number {
+    return this.rttSampler.average();
+  }
+
+  get minRoundTripTime(): number {
+    return this.rttSampler.min();
+  }
+
+  get latestRtt(): number {
+    return this.rttSampler.last ?? 0; // FIXME: Check if this is acceptable
+  }
+
+  addRttSample(rtt: number) {
+    this.rttSampler.addSample(rtt);
+  }
+
+  clearRttSamples() {
+    this.rttSampler.clear();
+  }
 }
 
 function resetMonitorState(monitor: Monitor) {
@@ -216,6 +243,8 @@ function resetMonitorState(monitor: Monitor) {
 
   monitor.connection?.destroy();
   monitor.connection = null;
+
+  monitor.clearRttSamples();
 }
 
 function useStreamingProtocol(monitor: Monitor, topologyVersion: TopologyVersion | null): boolean {
@@ -249,7 +278,6 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
   function onHeartbeatFailed(err: Error) {
     monitor.connection?.destroy();
     monitor.connection = null;
-
     monitor.emitAndLogHeartbeat(
       Server.SERVER_HEARTBEAT_FAILED,
       monitor[kServer].topology.s.id,
@@ -275,11 +303,15 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
       hello.isWritablePrimary = hello[LEGACY_HELLO_COMMAND];
     }
 
+    // NOTE: here we use the latestRtt as this measurement corresponds with the value
+    // obtained for this successful heartbeat
     const duration =
       isAwaitable && monitor.rttPinger
-        ? monitor.rttPinger.roundTripTime
+        ? monitor.rttPinger.latestRtt ?? calculateDurationInMs(start)
         : calculateDurationInMs(start);
 
+    monitor.addRttSample(duration);
+
     monitor.emitAndLogHeartbeat(
       Server.SERVER_HEARTBEAT_SUCCEEDED,
       monitor[kServer].topology.s.id,
@@ -328,13 +360,7 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
       : { socketTimeoutMS: connectTimeoutMS };
 
     if (isAwaitable && monitor.rttPinger == null) {
-      monitor.rttPinger = new RTTPinger(
-        monitor[kCancellationToken],
-        Object.assign(
-          { heartbeatFrequencyMS: monitor.options.heartbeatFrequencyMS },
-          monitor.connectOptions
-        )
-      );
+      monitor.rttPinger = new RTTPinger(monitor);
     }
 
     // Record new start time before sending handshake
@@ -351,6 +377,7 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
     awaited = false;
     connection
       .command(ns('admin.$cmd'), cmd, options)
+      // eslint-disable-next-line github/no-then
       .then(onHeartbeatSucceeded, onHeartbeatFailed);
 
     return;
@@ -369,12 +396,15 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
       connection.destroy();
       throw error;
     }
+    // eslint-disable-next-line github/no-then
   })().then(
     connection => {
       if (isInCloseState(monitor)) {
         connection.destroy();
         return;
       }
+      const duration = calculateDurationInMs(start);
+      monitor.addRttSample(duration);
 
       monitor.connection = connection;
       monitor.emitAndLogHeartbeat(
@@ -383,7 +413,7 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
         connection.hello?.connectionId,
         new ServerHeartbeatSucceededEvent(
           monitor.address,
-          calculateDurationInMs(start),
+          duration,
           connection.hello,
           useStreamingProtocol(monitor, connection.hello?.topologyVersion)
         )
@@ -456,23 +486,30 @@ export class RTTPinger {
   /** @internal */
   [kCancellationToken]: CancellationToken;
   /** @internal */
-  [kRoundTripTime]: number;
-  /** @internal */
   [kMonitorId]: NodeJS.Timeout;
+  /** @internal */
+  monitor: Monitor;
   closed: boolean;
+  /** @internal */
+  latestRtt?: number;
 
-  constructor(cancellationToken: CancellationToken, options: RTTPingerOptions) {
+  constructor(monitor: Monitor) {
     this.connection = undefined;
-    this[kCancellationToken] = cancellationToken;
-    this[kRoundTripTime] = 0;
+    this[kCancellationToken] = monitor[kCancellationToken];
     this.closed = false;
+    this.monitor = monitor;
+    this.latestRtt = monitor.latestRtt;
 
-    const heartbeatFrequencyMS = options.heartbeatFrequencyMS;
-    this[kMonitorId] = setTimeout(() => measureRoundTripTime(this, options), heartbeatFrequencyMS);
+    const heartbeatFrequencyMS = monitor.options.heartbeatFrequencyMS;
+    this[kMonitorId] = setTimeout(() => this.measureRoundTripTime(), heartbeatFrequencyMS);
   }
 
   get roundTripTime(): number {
-    return this[kRoundTripTime];
+    return this.monitor.roundTripTime;
+  }
+
+  get minRoundTripTime(): number {
+    return this.monitor.minRoundTripTime;
   }
 
   close(): void {
@@ -482,59 +519,60 @@ export class RTTPinger {
     this.connection?.destroy();
     this.connection = undefined;
   }
-}
-
-function measureRoundTripTime(rttPinger: RTTPinger, options: RTTPingerOptions) {
-  const start = now();
-  options.cancellationToken = rttPinger[kCancellationToken];
-  const heartbeatFrequencyMS = options.heartbeatFrequencyMS;
-
-  if (rttPinger.closed) {
-    return;
-  }
 
-  function measureAndReschedule(conn?: Connection) {
-    if (rttPinger.closed) {
+  private measureAndReschedule(start?: number, conn?: Connection) {
+    if (start == null) {
+      start = now();
+    }
+    if (this.closed) {
       conn?.destroy();
       return;
     }
 
-    if (rttPinger.connection == null) {
-      rttPinger.connection = conn;
+    if (this.connection == null) {
+      this.connection = conn;
     }
 
-    rttPinger[kRoundTripTime] = calculateDurationInMs(start);
-    rttPinger[kMonitorId] = setTimeout(
-      () => measureRoundTripTime(rttPinger, options),
-      heartbeatFrequencyMS
+    this.latestRtt = calculateDurationInMs(start);
+    this[kMonitorId] = setTimeout(
+      () => this.measureRoundTripTime(),
+      this.monitor.options.heartbeatFrequencyMS
     );
   }
 
-  const connection = rttPinger.connection;
-  if (connection == null) {
-    connect(options).then(
-      connection => {
-        measureAndReschedule(connection);
-      },
+  private measureRoundTripTime() {
+    const start = now();
+
+    if (this.closed) {
+      return;
+    }
+
+    const connection = this.connection;
+    if (connection == null) {
+      // eslint-disable-next-line github/no-then
+      connect(this.monitor.connectOptions).then(
+        connection => {
+          this.measureAndReschedule(start, connection);
+        },
+        () => {
+          this.connection = undefined;
+        }
+      );
+      return;
+    }
+
+    const commandName =
+      connection.serverApi?.version || connection.helloOk ? 'hello' : LEGACY_HELLO_COMMAND;
+    // eslint-disable-next-line github/no-then
+    connection.command(ns('admin.$cmd'), { [commandName]: 1 }, undefined).then(
+      () => this.measureAndReschedule(),
       () => {
-        rttPinger.connection = undefined;
-        rttPinger[kRoundTripTime] = 0;
+        this.connection?.destroy();
+        this.connection = undefined;
+        return;
       }
     );
-    return;
   }
-
-  const commandName =
-    connection.serverApi?.version || connection.helloOk ? 'hello' : LEGACY_HELLO_COMMAND;
-  connection.command(ns('admin.$cmd'), { [commandName]: 1 }, undefined).then(
-    () => measureAndReschedule(),
-    () => {
-      rttPinger.connection?.destroy();
-      rttPinger.connection = undefined;
-      rttPinger[kRoundTripTime] = 0;
-      return;
-    }
-  );
 }
 
 /**
@@ -662,3 +700,82 @@ export class MonitorInterval {
     });
   };
 }
+
+/** @internal
+ * This class implements the RTT sampling logic specified for [CSOT](https://github.com/mongodb/specifications/blob/bbb335e60cd7ea1e0f7cd9a9443cb95fc9d3b64d/source/client-side-operations-timeout/client-side-operations-timeout.md#drivers-use-minimum-rtt-to-short-circuit-operations)
+ *
+ * This is implemented as a [circular buffer](https://en.wikipedia.org/wiki/Circular_buffer) keeping
+ * the most recent `windowSize` samples
+ * */
+export class RTTSampler {
+  /** Index of the next slot to be overwritten */
+  private writeIndex: number;
+  private length: number;
+  private rttSamples: Float64Array;
+
+  constructor(windowSize = 10) {
+    this.rttSamples = new Float64Array(windowSize);
+    this.length = 0;
+    this.writeIndex = 0;
+  }
+
+  /**
+   * Adds an rtt sample to the end of the circular buffer
+   * When `windowSize` samples have been collected, `addSample` overwrites the least recently added
+   * sample
+   */
+  addSample(sample: number) {
+    this.rttSamples[this.writeIndex++] = sample;
+    if (this.length < this.rttSamples.length) {
+      this.length++;
+    }
+
+    this.writeIndex %= this.rttSamples.length;
+  }
+
+  /**
+   * When \< 2 samples have been collected, returns 0
+   * Otherwise computes the minimum value samples contained in the buffer
+   */
+  min(): number {
+    if (this.length < 2) return 0;
+    let min = this.rttSamples[0];
+    for (let i = 1; i < this.length; i++) {
+      if (this.rttSamples[i] < min) min = this.rttSamples[i];
+    }
+
+    return min;
+  }
+
+  /**
+   * Returns mean of samples contained in the buffer
+   */
+  average(): number {
+    if (this.length === 0) return 0;
+    let sum = 0;
+    for (let i = 0; i < this.length; i++) {
+      sum += this.rttSamples[i];
+    }
+
+    return sum / this.length;
+  }
+
+  /**
+   * Returns most recently inserted element in the buffer
+   * Returns null if the buffer is empty
+   * */
+  get last(): number | null {
+    if (this.length === 0) return null;
+    return this.rttSamples[this.writeIndex === 0 ? this.length - 1 : this.writeIndex - 1];
+  }
+
+  /**
+   * Clear the buffer
+   * NOTE: this does not overwrite the data held in the internal array, just the pointers into
+   * this array
+   */
+  clear() {
+    this.length = 0;
+    this.writeIndex = 0;
+  }
+}

package/src/sdam/server.ts

@@ -7,6 +7,7 @@ import {
   type ConnectionPoolOptions
 } from '../cmap/connection_pool';
 import { PoolClearedError } from '../cmap/errors';
+import { type MongoDBResponseConstructor } from '../cmap/wire_protocol/responses';
 import {
   APM_EVENTS,
   CLOSED,
@@ -175,7 +176,8 @@ export class Server extends TypedEventEmitter<ServerEvents> {
       this.emit(
         Server.DESCRIPTION_RECEIVED,
         new ServerDescription(this.description.hostAddress, event.reply, {
-          roundTripTime: calculateRoundTripTime(this.description.roundTripTime, event.duration)
+          roundTripTime: this.monitor?.roundTripTime,
+          minRoundTripTime: this.monitor?.minRoundTripTime
         })
       );
 
@@ -261,11 +263,25 @@ export class Server extends TypedEventEmitter<ServerEvents> {
     }
   }
 
-  /**
-   * Execute a command
-   * @internal
-   */
-  async command(ns: MongoDBNamespace, cmd: Document, options: CommandOptions): Promise<Document> {
+  public async command<T extends MongoDBResponseConstructor>(
+    ns: MongoDBNamespace,
+    command: Document,
+    options: CommandOptions | undefined,
+    responseType: T | undefined
+  ): Promise<typeof responseType extends undefined ? Document : InstanceType<T>>;
+
+  public async command(
+    ns: MongoDBNamespace,
+    command: Document,
+    options?: CommandOptions
+  ): Promise<Document>;
+
+  public async command(
+    ns: MongoDBNamespace,
+    cmd: Document,
+    options: CommandOptions,
+    responseType?: MongoDBResponseConstructor
+  ): Promise<Document> {
     if (ns.db == null || typeof ns === 'string') {
       throw new MongoInvalidArgumentError('Namespace must not be a string');
     }
@@ -307,7 +323,7 @@ export class Server extends TypedEventEmitter<ServerEvents> {
 
     try {
       try {
-        return await conn.command(ns, cmd, finalOptions);
+        return await conn.command(ns, cmd, finalOptions, responseType);
       } catch (commandError) {
         throw this.decorateCommandError(conn, cmd, finalOptions, commandError);
       }
@@ -318,7 +334,7 @@ export class Server extends TypedEventEmitter<ServerEvents> {
       ) {
         await this.pool.reauthenticate(conn);
         try {
-          return await conn.command(ns, cmd, finalOptions);
+          return await conn.command(ns, cmd, finalOptions, responseType);
         } catch (commandError) {
           throw this.decorateCommandError(conn, cmd, finalOptions, commandError);
         }
@@ -357,7 +373,7 @@ export class Server extends TypedEventEmitter<ServerEvents> {
       // clear for the specific service id.
       if (!this.loadBalanced) {
         error.addErrorLabel(MongoErrorLabel.ResetPool);
-        markServerUnknown(this, error as MongoServerError);
+        markServerUnknown(this, error);
       } else if (connection) {
         this.pool.clear({ serviceId: connection.serviceId });
       }
@@ -373,7 +389,7 @@ export class Server extends TypedEventEmitter<ServerEvents> {
             if (shouldClearPool) {
               error.addErrorLabel(MongoErrorLabel.ResetPool);
             }
-            markServerUnknown(this, error as MongoServerError);
+            markServerUnknown(this, error);
             process.nextTick(() => this.requestCheck());
           }
         }
@@ -467,16 +483,7 @@ export class Server extends TypedEventEmitter<ServerEvents> {
   }
 }
 
-function calculateRoundTripTime(oldRtt: number, duration: number): number {
-  if (oldRtt === -1) {
-    return duration;
-  }
-
-  const alpha = 0.2;
-  return alpha * duration + (1 - alpha) * oldRtt;
-}
-
-function markServerUnknown(server: Server, error?: MongoServerError) {
+function markServerUnknown(server: Server, error?: MongoError) {
   // Load balancer servers can never be marked unknown.
   if (server.loadBalanced) {
     return;

package/src/sdam/server_description.ts

@@ -1,5 +1,5 @@
 import { type Document, Long, type ObjectId } from '../bson';
-import { type MongoError, MongoRuntimeError, type MongoServerError } from '../error';
+import { type MongoError, MongoRuntimeError } from '../error';
 import { arrayStrictEqual, compareObjectId, errorStrictEqual, HostAddress, now } from '../utils';
 import type { ClusterTime } from './common';
 import { ServerType } from './common';
@@ -31,10 +31,12 @@ export type TagSet = { [key: string]: string };
 /** @internal */
 export interface ServerDescriptionOptions {
   /** An Error used for better reporting debugging */
-  error?: MongoServerError;
+  error?: MongoError;
 
-  /** The round trip time to ping this server (in ms) */
+  /** The average round trip time to ping this server (in ms) */
   roundTripTime?: number;
+  /** The minimum round trip time to ping this server over the past 10 samples(in ms) */
+  minRoundTripTime?: number;
 
   /** If the client is in load balancing mode. */
   loadBalanced?: boolean;
@@ -58,6 +60,8 @@ export class ServerDescription {
   minWireVersion: number;
   maxWireVersion: number;
   roundTripTime: number;
+  /** The minimum measurement of the last 10 measurements of roundTripTime that have been collected */
+  minRoundTripTime: number;
   lastUpdateTime: number;
   lastWriteDate: number;
   me: string | null;
@@ -98,6 +102,7 @@ export class ServerDescription {
     this.minWireVersion = hello?.minWireVersion ?? 0;
     this.maxWireVersion = hello?.maxWireVersion ?? 0;
     this.roundTripTime = options?.roundTripTime ?? -1;
+    this.minRoundTripTime = options?.minRoundTripTime ?? 0;
     this.lastUpdateTime = now();
     this.lastWriteDate = hello?.lastWrite?.lastWriteDate ?? 0;
     this.error = options.error ?? null;

package/src/sdam/server_selection.ts

@@ -223,9 +223,8 @@ function latencyWindowReducer(
   servers: ServerDescription[]
 ): ServerDescription[] {
   const low = servers.reduce(
-    (min: number, server: ServerDescription) =>
-      min === -1 ? server.roundTripTime : Math.min(server.roundTripTime, min),
-    -1
+    (min: number, server: ServerDescription) => Math.min(server.roundTripTime, min),
+    Infinity
   );
 
   const high = low + topologyDescription.localThresholdMS;

package/src/sdam/srv_polling.ts

@@ -3,7 +3,7 @@ import { clearTimeout, setTimeout } from 'timers';
 
 import { MongoRuntimeError } from '../error';
 import { TypedEventEmitter } from '../mongo_types';
-import { HostAddress, matchesParentDomain } from '../utils';
+import { HostAddress, matchesParentDomain, squashError } from '../utils';
 
 /**
  * @internal
@@ -95,7 +95,8 @@ export class SrvPoller extends TypedEventEmitter<SrvPollerEvents> {
     }
 
     this._timeout = setTimeout(() => {
-      this._poll().catch(() => null);
+      // eslint-disable-next-line github/no-then
+      this._poll().then(undefined, squashError);
     }, this.intervalMS);
   }