mongodb 6.5.0-dev.20240406.sha.62ea94b → 6.5.0-dev.20240411.sha.ddd1e81

package/src/cmap/connection.ts

@@ -54,7 +54,7 @@ import {
   OpMsgRequest,
   type OpMsgResponse,
   OpQueryRequest,
-  type OpQueryResponse,
+  type OpReply,
   type WriteProtocolMessageType
 } from './commands';
 import type { Stream } from './connect';
@@ -62,6 +62,7 @@ import type { ClientMetadata } from './handshake/client_metadata';
 import { StreamDescription, type StreamDescriptionOptions } from './stream_description';
 import { type CompressorName, decompressResponse } from './wire_protocol/compression';
 import { onData } from './wire_protocol/on_data';
+import { MongoDBResponse, type MongoDBResponseConstructor } from './wire_protocol/responses';
 import { getReadPreference, isSharded } from './wire_protocol/shared';
 
 /** @internal */
@@ -412,7 +413,11 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
     return message;
   }
 
-  private async *sendWire(message: WriteProtocolMessageType, options: CommandOptions) {
+  private async *sendWire(
+    message: WriteProtocolMessageType,
+    options: CommandOptions,
+    responseType?: MongoDBResponseConstructor
+  ): AsyncGenerator<MongoDBResponse> {
     this.throwIfAborted();
 
     if (typeof options.socketTimeoutMS === 'number') {
@@ -428,7 +433,7 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
       });
 
       if (options.noResponse) {
-        yield { ok: 1 };
+        yield MongoDBResponse.empty;
         return;
       }
 
@@ -436,21 +441,9 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
 
       for await (const response of this.readMany()) {
         this.socket.setTimeout(0);
-        response.parse(options);
-
-        const [document] = response.documents;
+        const bson = response.parse();
 
-        if (!Buffer.isBuffer(document)) {
-          const { session } = options;
-          if (session) {
-            updateSessionFromResponse(session, document);
-          }
-
-          if (document.$clusterTime) {
-            this.clusterTime = document.$clusterTime;
-            this.emit(Connection.CLUSTER_TIME_RECEIVED, document.$clusterTime);
-          }
-        }
+        const document = new (responseType ?? MongoDBResponse)(bson, 0, false);
 
         yield document;
         this.throwIfAborted();
@@ -469,7 +462,8 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
   private async *sendCommand(
     ns: MongoDBNamespace,
     command: Document,
-    options: CommandOptions = {}
+    options: CommandOptions,
+    responseType?: MongoDBResponseConstructor
   ) {
     const message = this.prepareCommand(ns.db, command, options);
 
@@ -485,19 +479,41 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
       );
     }
 
-    let document;
+    // If `documentsReturnedIn` not set or raw is not enabled, use input bson options
+    // Otherwise, support raw flag. Raw only works for cursors that hardcode firstBatch/nextBatch fields
+    const bsonOptions =
+      options.documentsReturnedIn == null || !options.raw
+        ? options
+        : {
+            ...options,
+            raw: false,
+            fieldsAsRaw: { [options.documentsReturnedIn]: true }
+          };
+
+    /** MongoDBResponse instance or subclass */
+    let document: MongoDBResponse | undefined = undefined;
+    /** Cached result of a toObject call */
+    let object: Document | undefined = undefined;
     try {
       this.throwIfAborted();
-      for await (document of this.sendWire(message, options)) {
-        if (!Buffer.isBuffer(document) && document.writeConcernError) {
-          throw new MongoWriteConcernError(document.writeConcernError, document);
+      for await (document of this.sendWire(message, options, responseType)) {
+        object = undefined;
+        if (options.session != null) {
+          updateSessionFromResponse(options.session, document);
+        }
+
+        if (document.$clusterTime) {
+          this.clusterTime = document.$clusterTime;
+          this.emit(Connection.CLUSTER_TIME_RECEIVED, document.$clusterTime);
         }
 
-        if (
-          !Buffer.isBuffer(document) &&
-          (document.ok === 0 || document.$err || document.errmsg || document.code)
-        ) {
-          throw new MongoServerError(document);
+        if (document.has('writeConcernError')) {
+          object ??= document.toObject(bsonOptions);
+          throw new MongoWriteConcernError(object.writeConcernError, object);
+        }
+
+        if (document.isError) {
+          throw new MongoServerError((object ??= document.toObject(bsonOptions)));
         }
 
         if (this.shouldEmitAndLogCommand) {
@@ -509,14 +525,19 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
             new CommandSucceededEvent(
               this,
               message,
-              options.noResponse ? undefined : document,
+              options.noResponse ? undefined : (object ??= document.toObject(bsonOptions)),
               started,
               this.description.serverConnectionId
             )
           );
         }
 
-        yield document;
+        if (responseType == null) {
+          yield (object ??= document.toObject(bsonOptions));
+        } else {
+          yield document;
+        }
+
         this.throwIfAborted();
       }
     } catch (error) {
@@ -530,7 +551,7 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
             new CommandSucceededEvent(
               this,
               message,
-              options.noResponse ? undefined : document,
+              options.noResponse ? undefined : (object ??= document?.toObject(bsonOptions)),
               started,
               this.description.serverConnectionId
             )
@@ -555,13 +576,27 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
     }
   }
 
+  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,
     command: Document,
-    options: CommandOptions = {}
+    options: CommandOptions = {},
+    responseType?: MongoDBResponseConstructor
   ): Promise<Document> {
     this.throwIfAborted();
-    for await (const document of this.sendCommand(ns, command, options)) {
+    for await (const document of this.sendCommand(ns, command, options, responseType)) {
       return document;
     }
     throw new MongoUnexpectedServerResponseError('Unable to get response from server');
@@ -622,7 +657,7 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
    *
    * Note that `for-await` loops call `return` automatically when the loop is exited.
    */
-  private async *readMany(): AsyncGenerator<OpMsgResponse | OpQueryResponse> {
+  private async *readMany(): AsyncGenerator<OpMsgResponse | OpReply> {
     try {
       this.dataEvents = onData(this.messageStream);
       for await (const message of this.dataEvents) {
@@ -687,11 +722,24 @@ export class CryptoConnection extends Connection {
     this.autoEncrypter = options.autoEncrypter;
   }
 
-  /** @internal @override */
-  override async command(
+  public override async command<T extends MongoDBResponseConstructor>(
+    ns: MongoDBNamespace,
+    command: Document,
+    options: CommandOptions | undefined,
+    responseType: T
+  ): Promise<InstanceType<T>>;
+
+  public override async command(
+    ns: MongoDBNamespace,
+    command: Document,
+    options?: CommandOptions
+  ): Promise<Document>;
+
+  override async command<T extends MongoDBResponseConstructor>(
     ns: MongoDBNamespace,
     cmd: Document,
-    options: CommandOptions
+    options?: CommandOptions,
+    responseType?: T | undefined
   ): Promise<Document> {
     const { autoEncrypter } = this;
     if (!autoEncrypter) {
@@ -705,7 +753,7 @@ export class CryptoConnection extends Connection {
     const serverWireVersion = maxWireVersion(this);
     if (serverWireVersion === 0) {
       // This means the initial handshake hasn't happened yet
-      return await super.command(ns, cmd, options);
+      return await super.command<T>(ns, cmd, options, responseType);
     }
 
     if (serverWireVersion < 8) {
@@ -739,7 +787,7 @@ export class CryptoConnection extends Connection {
       }
     }
 
-    const response = await super.command(ns, encrypted, options);
+    const response = await super.command<T>(ns, encrypted, options, responseType);
 
     return await autoEncrypter.decrypt(response, options);
   }

package/src/cmap/wire_protocol/compression.ts

@@ -8,7 +8,7 @@ import {
   type MessageHeader,
   OpCompressedRequest,
   OpMsgResponse,
-  OpQueryResponse,
+  OpReply,
   type WriteProtocolMessageType
 } from '../commands';
 import { OP_COMPRESSED, OP_MSG } from './constants';
@@ -163,9 +163,7 @@ export async function compressCommand(
  *
  * This method does not parse the response's BSON.
  */
-export async function decompressResponse(
-  message: Buffer
-): Promise<OpMsgResponse | OpQueryResponse> {
+export async function decompressResponse(message: Buffer): Promise<OpMsgResponse | OpReply> {
   const messageHeader: MessageHeader = {
     length: message.readInt32LE(0),
     requestId: message.readInt32LE(4),
@@ -174,7 +172,7 @@ export async function decompressResponse(
   };
 
   if (messageHeader.opCode !== OP_COMPRESSED) {
-    const ResponseType = messageHeader.opCode === OP_MSG ? OpMsgResponse : OpQueryResponse;
+    const ResponseType = messageHeader.opCode === OP_MSG ? OpMsgResponse : OpReply;
     const messageBody = message.subarray(MESSAGE_HEADER_SIZE);
     return new ResponseType(message, messageHeader, messageBody);
   }
@@ -189,7 +187,7 @@ export async function decompressResponse(
   const compressedBuffer = message.slice(MESSAGE_HEADER_SIZE + 9);
 
   // recalculate based on wrapped opcode
-  const ResponseType = header.opCode === OP_MSG ? OpMsgResponse : OpQueryResponse;
+  const ResponseType = header.opCode === OP_MSG ? OpMsgResponse : OpReply;
   const messageBody = await decompress(compressorID, compressedBuffer);
   if (messageBody.length !== header.length) {
     throw new MongoDecompressionError('Message body and message header must be the same length');

package/src/cmap/wire_protocol/on_demand/document.ts

@@ -23,6 +23,7 @@ const enum BSONElementOffset {
   length = 4
 }
 
+/** @internal */
 export type JSTypeOf = {
   [BSONType.null]: null;
   [BSONType.undefined]: null;

package/src/cmap/wire_protocol/responses.ts

@@ -0,0 +1,109 @@
+import { type BSONSerializeOptions, BSONType, type Document, type Timestamp } from '../../bson';
+import { type ClusterTime } from '../../sdam/common';
+import { OnDemandDocument } from './on_demand/document';
+
+/** @internal */
+export type MongoDBResponseConstructor = {
+  new (bson: Uint8Array, offset?: number, isArray?: boolean): MongoDBResponse;
+};
+
+/** @internal */
+export class MongoDBResponse extends OnDemandDocument {
+  // {ok:1}
+  static empty = new MongoDBResponse(new Uint8Array([13, 0, 0, 0, 16, 111, 107, 0, 1, 0, 0, 0, 0]));
+
+  /** Indicates this document is a server error */
+  public get isError() {
+    let isError = this.ok === 0;
+    isError ||= this.has('errmsg');
+    isError ||= this.has('code');
+    isError ||= this.has('$err'); // The '$err' field is used in OP_REPLY responses
+    return isError;
+  }
+
+  /**
+   * Drivers can safely assume that the `recoveryToken` field is always a BSON document but drivers MUST NOT modify the
+   * contents of the document.
+   */
+  get recoveryToken(): Document | null {
+    return (
+      this.get('recoveryToken', BSONType.object)?.toObject({
+        promoteValues: false,
+        promoteLongs: false,
+        promoteBuffers: false
+      }) ?? null
+    );
+  }
+
+  /**
+   * The server creates a cursor in response to a snapshot find/aggregate command and reports atClusterTime within the cursor field in the response.
+   * For the distinct command the server adds a top-level atClusterTime field to the response.
+   * The atClusterTime field represents the timestamp of the read and is guaranteed to be majority committed.
+   */
+  public get atClusterTime(): Timestamp | null {
+    return (
+      this.get('cursor', BSONType.object)?.get('atClusterTime', BSONType.timestamp) ??
+      this.get('atClusterTime', BSONType.timestamp)
+    );
+  }
+
+  public get operationTime(): Timestamp | null {
+    return this.get('operationTime', BSONType.timestamp);
+  }
+
+  public get ok(): 0 | 1 {
+    return this.getNumber('ok') ? 1 : 0;
+  }
+
+  public get $err(): string | null {
+    return this.get('$err', BSONType.string);
+  }
+
+  public get errmsg(): string | null {
+    return this.get('errmsg', BSONType.string);
+  }
+
+  public get code(): number | null {
+    return this.getNumber('code');
+  }
+
+  private clusterTime?: ClusterTime | null;
+  public get $clusterTime(): ClusterTime | null {
+    if (!('clusterTime' in this)) {
+      const clusterTimeDoc = this.get('$clusterTime', BSONType.object);
+      if (clusterTimeDoc == null) {
+        this.clusterTime = null;
+        return null;
+      }
+      const clusterTime = clusterTimeDoc.get('clusterTime', BSONType.timestamp, true);
+      const signature = clusterTimeDoc.get('signature', BSONType.object)?.toObject();
+      // @ts-expect-error: `signature` is incorrectly typed. It is public API.
+      this.clusterTime = { clusterTime, signature };
+    }
+    return this.clusterTime ?? null;
+  }
+
+  public override toObject(options: BSONSerializeOptions = {}): Record<string, any> {
+    const exactBSONOptions = {
+      useBigInt64: options.useBigInt64,
+      promoteLongs: options.promoteLongs,
+      promoteValues: options.promoteValues,
+      promoteBuffers: options.promoteBuffers,
+      bsonRegExp: options.bsonRegExp,
+      raw: options.raw ?? false,
+      fieldsAsRaw: options.fieldsAsRaw ?? {},
+      validation: this.parseBsonSerializationOptions(options)
+    };
+    return super.toObject(exactBSONOptions);
+  }
+
+  private parseBsonSerializationOptions({ enableUtf8Validation }: BSONSerializeOptions): {
+    utf8: { writeErrors: false } | false;
+  } {
+    if (enableUtf8Validation === false) {
+      return { utf8: false };
+    }
+
+    return { utf8: { writeErrors: false } };
+  }
+}

package/src/collection.ts

@@ -106,6 +106,8 @@ export interface CollectionOptions extends BSONSerializeOptions, WriteConcernOpt
   readConcern?: ReadConcernLike;
   /** The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). */
   readPreference?: ReadPreferenceLike;
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }
 
 /** @internal */

package/src/cursor/abstract_cursor.ts

@@ -109,6 +109,8 @@ export interface AbstractCursorOptions extends BSONSerializeOptions {
    */
   awaitData?: boolean;
   noCursorTimeout?: boolean;
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }
 
 /** @internal */
@@ -184,6 +186,7 @@ export abstract class AbstractCursor<
           : ReadPreference.primary,
       ...pluckBSONSerializeOptions(options)
     };
+    this[kOptions].timeoutMS = options.timeoutMS;
 
     const readConcern = ReadConcern.fromOptions(options);
     if (readConcern) {

package/src/db.ts

@@ -66,7 +66,8 @@ const DB_OPTIONS_ALLOW_LIST = [
   'enableUtf8Validation',
   'promoteValues',
   'compression',
-  'retryWrites'
+  'retryWrites',
+  'timeoutMS'
 ];
 
 /** @internal */
@@ -94,6 +95,8 @@ export interface DbOptions extends BSONSerializeOptions, WriteConcernOptions {
   readConcern?: ReadConcern;
   /** Should retry failed writes */
   retryWrites?: boolean;
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }
 
 /**

package/src/gridfs/download.ts

@@ -28,6 +28,8 @@ export interface GridFSBucketReadStreamOptions {
    * to be returned by the stream. `end` is non-inclusive
    */
   end?: number;
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }
 
 /** @public */

package/src/gridfs/index.ts

@@ -36,6 +36,8 @@ export interface GridFSBucketOptions extends WriteConcernOptions {
   chunkSizeBytes?: number;
   /** Read preference to be passed to read operations */
   readPreference?: ReadPreference;
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }
 
 /** @internal */

package/src/gridfs/upload.ts

@@ -36,6 +36,8 @@ export interface GridFSBucketWriteStreamOptions extends WriteConcernOptions {
    * @deprecated Will be removed in the next major version. Add an aliases field to the metadata document instead.
    */
   aliases?: string[];
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }
 
 /**

package/src/index.ts

@@ -264,8 +264,7 @@ export type {
   OpMsgResponse,
   OpQueryOptions,
   OpQueryRequest,
-  OpQueryResponse,
-  OpResponseOptions,
+  OpReply,
   WriteProtocolMessageType
 } from './cmap/commands';
 export type { HandshakeDocument } from './cmap/connect';
@@ -290,6 +289,8 @@ export type { ClientMetadata, ClientMetadataOptions } from './cmap/handshake/cli
 export type { ConnectionPoolMetrics } from './cmap/metrics';
 export type { StreamDescription, StreamDescriptionOptions } from './cmap/stream_description';
 export type { CompressorName } from './cmap/wire_protocol/compression';
+export type { JSTypeOf, OnDemandDocument } from './cmap/wire_protocol/on_demand/document';
+export type { MongoDBResponse, MongoDBResponseConstructor } from './cmap/wire_protocol/responses';
 export type { CollectionOptions, CollectionPrivate, ModifyResult } from './collection';
 export type {
   COMMAND_FAILED,

package/src/mongo_client.ts

@@ -120,7 +120,7 @@ export type SupportedNodeConnectionOptions = SupportedTLSConnectionOptions &
 export interface MongoClientOptions extends BSONSerializeOptions, SupportedNodeConnectionOptions {
   /** Specifies the name of the replica set, if the mongod is a member of a replica set. */
   replicaSet?: string;
-  /** @internal This option is in development and currently has no behaviour. */
+  /** @internal TODO(NODE-5688): This option is in development and currently has no behaviour.  */
   timeoutMS?: number;
   /** Enables or disables TLS/SSL for the connection. */
   tls?: boolean;
@@ -897,4 +897,6 @@ export interface MongoOptions
    * TODO: NODE-5671 - remove internal flag
    */
   mongodbLogPath?: 'stderr' | 'stdout' | MongoDBLogWritable;
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }

package/src/operations/execute_operation.ts

@@ -110,6 +110,11 @@ export async function executeOperation<
   } else if (session.client !== client) {
     throw new MongoInvalidArgumentError('ClientSession must be from the same MongoClient');
   }
+  if (session.explicit && session?.timeoutMS != null && operation.options.timeoutMS != null) {
+    throw new MongoInvalidArgumentError(
+      'Do not specify timeoutMS on operation if already specified on an explicit session'
+    );
+  }
 
   const readPreference = operation.readPreference ?? ReadPreference.primary;
   const inTransaction = !!session?.inTransaction();

package/src/operations/operation.ts

@@ -34,6 +34,9 @@ export interface OperationOptions extends BSONSerializeOptions {
   /** @internal Hints to `executeOperation` that this operation should not unpin on an ended transaction */
   bypassPinningCheck?: boolean;
   omitReadPreference?: boolean;
+
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }
 
 /** @internal */

package/src/sessions.ts

@@ -4,6 +4,7 @@ import { promisify } from 'util';
 import { Binary, type Document, Long, type Timestamp } from './bson';
 import type { CommandOptions, Connection } from './cmap/connection';
 import { ConnectionPoolMetrics } from './cmap/metrics';
+import { type MongoDBResponse } from './cmap/wire_protocol/responses';
 import { isSharded } from './cmap/wire_protocol/shared';
 import { PINNED, UNPINNED } from './constants';
 import type { AbstractCursor } from './cursor/abstract_cursor';
@@ -60,6 +61,9 @@ export interface ClientSessionOptions {
   snapshot?: boolean;
   /** The default TransactionOptions to use for transactions started on this session. */
   defaultTransactionOptions?: TransactionOptions;
+  /** @internal
+   * The value of timeoutMS used for CSOT. Used to override client timeoutMS */
+  defaultTimeoutMS?: number;
 
   /** @internal */
   owner?: symbol | AbstractCursor;
@@ -130,6 +134,8 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
   [kPinnedConnection]?: Connection;
   /** @internal */
   [kTxnNumberIncrement]: number;
+  /** @internal */
+  timeoutMS?: number;
 
   /**
    * Create a client session.
@@ -172,6 +178,7 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     this.sessionPool = sessionPool;
     this.hasEnded = false;
     this.clientOptions = clientOptions;
+    this.timeoutMS = options.defaultTimeoutMS ?? client.options?.timeoutMS;
 
     this.explicit = !!options.explicit;
     this[kServerSession] = this.explicit ? this.sessionPool.acquire() : null;
@@ -1040,7 +1047,7 @@ export function applySession(
   return;
 }
 
-export function updateSessionFromResponse(session: ClientSession, document: Document): void {
+export function updateSessionFromResponse(session: ClientSession, document: MongoDBResponse): void {
   if (document.$clusterTime) {
     _advanceClusterTime(session, document.$clusterTime);
   }
@@ -1056,7 +1063,7 @@ export function updateSessionFromResponse(session: ClientSession, document: Docu
   if (session?.[kSnapshotEnabled] && session[kSnapshotTime] == null) {
     // find and aggregate commands return atClusterTime on the cursor
     // distinct includes it in the response body
-    const atClusterTime = document.cursor?.atClusterTime || document.atClusterTime;
+    const atClusterTime = document.atClusterTime;
     if (atClusterTime) {
       session[kSnapshotTime] = atClusterTime;
     }