mongodb 5.3.0 → 5.4.0

package/mongodb.d.ts

@@ -279,6 +279,22 @@ export declare class Admin {
     /**
      * Execute a command
      *
+     * The driver will ensure the following fields are attached to the command sent to the server:
+     * - `lsid` - sourced from an implicit session or options.session
+     * - `$readPreference` - defaults to primary or can be configured by options.readPreference
+     * - `$db` - sourced from the name of this database
+     *
+     * If the client has a serverApi setting:
+     * - `apiVersion`
+     * - `apiStrict`
+     * - `apiDeprecationErrors`
+     *
+     * When in a transaction:
+     * - `readConcern` - sourced from readConcern set on the TransactionOptions
+     * - `writeConcern` - sourced from writeConcern set on the TransactionOptions
+     *
+     * Attaching any of the above fields to the command will have no effect as the driver will overwrite the value.
+     *
      * @param command - The command to execute
      * @param options - Optional settings for the command
      */
@@ -537,6 +553,8 @@ export declare interface AuthMechanismProperties extends Document {
     REFRESH_TOKEN_CALLBACK?: OIDCRefreshFunction;
     /** @experimental */
     PROVIDER_NAME?: 'aws';
+    /** @experimental */
+    ALLOWED_HOSTS?: string[];
 }
 
 /** @public */
@@ -1065,7 +1083,7 @@ export declare class ChangeStream<TSchema extends Document = Document, TChange e
     /**
      * Try to get the next available document from the Change Stream's cursor or `null` if an empty batch is returned
      */
-    tryNext(): Promise<Document | null>;
+    tryNext(): Promise<TChange | null>;
     [Symbol.asyncIterator](): AsyncGenerator<TChange, void, void>;
     /** Is the cursor closed */
     get closed(): boolean;
@@ -1997,6 +2015,9 @@ export declare class Collection<TSchema extends Document = Document> {
     /**
      * Get all the collection statistics.
      *
+     * @deprecated the `collStats` operation will be removed in the next major release.  Please
+     * use an aggregation pipeline with the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/) stage instead
+     *
      * @param options - Optional settings for the command
      */
     stats(options?: CollStatsOptions): Promise<CollStats>;
@@ -2125,6 +2146,8 @@ export declare interface CollectionOptions extends BSONSerializeOptions, WriteCo
 /* Excluded from this release type: CollectionPrivate */
 
 /**
+ * @deprecated the `collStats` operation will be removed in the next major release.  Please
+ * use an aggregation pipeline with the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/) stage instead
  * @public
  * @see https://www.mongodb.com/docs/manual/reference/command/collStats/
  */
@@ -2177,7 +2200,11 @@ export declare interface CollStats extends Document {
     scaleFactor: number;
 }
 
-/** @public */
+/**
+ * @public
+ * @deprecated the `collStats` operation will be removed in the next major release.  Please
+ * use an aggregation pipeline with the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/) stage instead
+ */
 export declare interface CollStatsOptions extends CommandOperationOptions {
     /** Divide the returned sizes by scale value. */
     scale?: number;
@@ -2711,6 +2738,22 @@ export declare class Db {
      * @remarks
      * This command does not inherit options from the MongoClient.
      *
+     * The driver will ensure the following fields are attached to the command sent to the server:
+     * - `lsid` - sourced from an implicit session or options.session
+     * - `$readPreference` - defaults to primary or can be configured by options.readPreference
+     * - `$db` - sourced from the name of this database
+     *
+     * If the client has a serverApi setting:
+     * - `apiVersion`
+     * - `apiStrict`
+     * - `apiDeprecationErrors`
+     *
+     * When in a transaction:
+     * - `readConcern` - sourced from readConcern set on the TransactionOptions
+     * - `writeConcern` - sourced from writeConcern set on the TransactionOptions
+     *
+     * Attaching any of the above fields to the command will have no effect as the driver will overwrite the value.
+     *
      * @param command - The command to run
      * @param options - Optional settings for the command
      */
@@ -3675,6 +3718,26 @@ export declare class HostAddress {
     };
 }
 
+/**
+ * @public
+ * @experimental
+ */
+export declare interface IdPServerInfo {
+    issuer: string;
+    clientId: string;
+    requestScopes?: string[];
+}
+
+/**
+ * @public
+ * @experimental
+ */
+export declare interface IdPServerResponse {
+    accessToken: string;
+    expiresInSeconds?: number;
+    refreshToken?: string;
+}
+
 /** @public */
 export declare interface IndexDescription extends Pick<CreateIndexesOptions, 'background' | 'unique' | 'partialFilterExpression' | 'sparse' | 'hidden' | 'expireAfterSeconds' | 'storageEngine' | 'version' | 'weights' | 'default_language' | 'language_override' | 'textIndexVersion' | '2dsphereIndexVersion' | 'bits' | 'min' | 'max' | 'bucketSize' | 'wildcardProjection'> {
     collation?: CollationOptions;
@@ -4399,7 +4462,7 @@ export declare class MongoCredentials {
 
 /** @public */
 export declare interface MongoCredentialsOptions {
-    username: string;
+    username?: string;
     password: string;
     source: string;
     db?: string;
@@ -4943,36 +5006,24 @@ export { ObjectId }
  * @public
  * @experimental
  */
-export declare interface OIDCMechanismServerStep1 {
-    authorizationEndpoint?: string;
-    tokenEndpoint?: string;
-    deviceAuthorizationEndpoint?: string;
-    clientId: string;
-    clientSecret?: string;
-    requestScopes?: string[];
+export declare interface OIDCCallbackContext {
+    refreshToken?: string;
+    timeoutSeconds?: number;
+    timeoutContext?: AbortSignal;
+    version: number;
 }
 
 /**
  * @public
  * @experimental
  */
-export declare type OIDCRefreshFunction = (principalName: string, serverResult: OIDCMechanismServerStep1, result: OIDCRequestTokenResult, timeout: AbortSignal | number) => Promise<OIDCRequestTokenResult>;
-
-/**
- * @public
- * @experimental
- */
-export declare type OIDCRequestFunction = (principalName: string, serverResult: OIDCMechanismServerStep1, timeout: AbortSignal | number) => Promise<OIDCRequestTokenResult>;
+export declare type OIDCRefreshFunction = (info: IdPServerInfo, context: OIDCCallbackContext) => Promise<IdPServerResponse>;
 
 /**
  * @public
  * @experimental
  */
-export declare interface OIDCRequestTokenResult {
-    accessToken: string;
-    expiresInSeconds?: number;
-    refreshToken?: string;
-}
+export declare type OIDCRequestFunction = (info: IdPServerInfo, context: OIDCCallbackContext) => Promise<IdPServerResponse>;
 
 /** @public */
 export declare type OneOrMore<T> = T | ReadonlyArray<T>;
@@ -5352,7 +5403,37 @@ export declare interface RootFilterOperators<TSchema> extends Document {
 /* Excluded from this release type: RTTPingerOptions */
 
 /** @public */
-export declare type RunCommandOptions = CommandOperationOptions;
+export declare type RunCommandOptions = {
+    /** Specify ClientSession for this command */
+    session?: ClientSession;
+    /** The read preference */
+    readPreference?: ReadPreferenceLike;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    willRetryWrite?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    omitReadPreference?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    writeConcern?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    explain?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    readConcern?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    collation?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    maxTimeMS?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    comment?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    retryWrites?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    dbName?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    authdb?: any;
+    /** @deprecated This is an internal option that has undefined behavior for this API */
+    noResponse?: any;
+    /* Excluded from this release type: bypassPinningCheck */
+} & BSONSerializeOptions;
 
 /** @public */
 export declare type SchemaMember<T, V> = {
@@ -6128,7 +6209,10 @@ export declare type W = number | 'majority';
 
 /* Excluded from this release type: WaitQueueMember */
 
-/** @public */
+/**
+ * @public
+ * @deprecated This type is only used for the deprecated `collStats` operation and will be removed in the next major release.
+ */
 export declare interface WiredTigerData extends Document {
     LSM: {
         'bloom filter false positives': number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mongodb",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "The official MongoDB driver for Node.js",
   "main": "lib/index.js",
   "files": [
@@ -127,7 +127,7 @@
     "check:atlas": "mocha --config test/manual/mocharc.json test/manual/atlas_connectivity.test.js",
     "check:adl": "mocha --config test/mocha_mongodb.json test/manual/atlas-data-lake-testing",
     "check:aws": "nyc mocha --config test/mocha_mongodb.json test/integration/auth/mongodb_aws.test.ts",
-    "check:oidc": "mocha --config test/manual/mocharc.json test/manual/mongodb_oidc.prose.test.ts",
+    "check:oidc": "mocha --config test/mocha_mongodb.json test/manual/mongodb_oidc.prose.test.ts",
     "check:ocsp": "mocha --config test/manual/mocharc.json test/manual/ocsp_support.test.js",
     "check:kerberos": "nyc mocha --config test/manual/mocharc.json test/manual/kerberos.test.ts",
     "check:tls": "mocha --config test/manual/mocharc.json test/manual/tls_support.test.js",

package/src/admin.ts

@@ -54,6 +54,22 @@ export class Admin {
   /**
    * Execute a command
    *
+   * The driver will ensure the following fields are attached to the command sent to the server:
+   * - `lsid` - sourced from an implicit session or options.session
+   * - `$readPreference` - defaults to primary or can be configured by options.readPreference
+   * - `$db` - sourced from the name of this database
+   *
+   * If the client has a serverApi setting:
+   * - `apiVersion`
+   * - `apiStrict`
+   * - `apiDeprecationErrors`
+   *
+   * When in a transaction:
+   * - `readConcern` - sourced from readConcern set on the TransactionOptions
+   * - `writeConcern` - sourced from writeConcern set on the TransactionOptions
+   *
+   * Attaching any of the above fields to the command will have no effect as the driver will overwrite the value.
+   *
    * @param command - The command to execute
    * @param options - Optional settings for the command
    */

package/src/change_stream.ts

@@ -700,7 +700,7 @@ export class ChangeStream<
   /**
    * Try to get the next available document from the Change Stream's cursor or `null` if an empty batch is returned
    */
-  async tryNext(): Promise<Document | null> {
+  async tryNext(): Promise<TChange | null> {
     this._setIsIterator();
     // Change streams must resume indefinitely while each resume event succeeds.
     // This loop continues until either a change event is received or until a resume attempt

package/src/cmap/auth/mongo_credentials.ts

@@ -30,6 +30,18 @@ function getDefaultAuthMechanism(hello?: Document): AuthMechanism {
   return AuthMechanism.MONGODB_CR;
 }
 
+const ALLOWED_HOSTS_ERROR = 'Auth mechanism property ALLOWED_HOSTS must be an array of strings.';
+
+/** @internal */
+export const DEFAULT_ALLOWED_HOSTS = [
+  '*.mongodb.net',
+  '*.mongodb-dev.net',
+  '*.mongodbgov.net',
+  'localhost',
+  '127.0.0.1',
+  '::1'
+];
+
 /** @public */
 export interface AuthMechanismProperties extends Document {
   SERVICE_HOST?: string;
@@ -43,11 +55,13 @@ export interface AuthMechanismProperties extends Document {
   REFRESH_TOKEN_CALLBACK?: OIDCRefreshFunction;
   /** @experimental */
   PROVIDER_NAME?: 'aws';
+  /** @experimental */
+  ALLOWED_HOSTS?: string[];
 }
 
 /** @public */
 export interface MongoCredentialsOptions {
-  username: string;
+  username?: string;
   password: string;
   source: string;
   db?: string;
@@ -72,7 +86,7 @@ export class MongoCredentials {
   readonly mechanismProperties: AuthMechanismProperties;
 
   constructor(options: MongoCredentialsOptions) {
-    this.username = options.username;
+    this.username = options.username ?? '';
     this.password = options.password;
     this.source = options.source;
     if (!this.source && options.db) {
@@ -101,6 +115,13 @@ export class MongoCredentials {
       }
     }
 
+    if (this.mechanism === AuthMechanism.MONGODB_OIDC && !this.mechanismProperties.ALLOWED_HOSTS) {
+      this.mechanismProperties = {
+        ...this.mechanismProperties,
+        ALLOWED_HOSTS: DEFAULT_ALLOWED_HOSTS
+      };
+    }
+
     Object.freeze(this.mechanismProperties);
     Object.freeze(this);
   }
@@ -181,6 +202,18 @@ export class MongoCredentials {
           `Either a PROVIDER_NAME or a REQUEST_TOKEN_CALLBACK must be specified for mechanism '${this.mechanism}'.`
         );
       }
+
+      if (this.mechanismProperties.ALLOWED_HOSTS) {
+        const hosts = this.mechanismProperties.ALLOWED_HOSTS;
+        if (!Array.isArray(hosts)) {
+          throw new MongoInvalidArgumentError(ALLOWED_HOSTS_ERROR);
+        }
+        for (const host of hosts) {
+          if (typeof host !== 'string') {
+            throw new MongoInvalidArgumentError(ALLOWED_HOSTS_ERROR);
+          }
+        }
+      }
     }
 
     if (AUTH_MECHS_AUTH_SRC_EXTERNAL.has(this.mechanism)) {

package/src/cmap/auth/mongodb_oidc/aws_service_workflow.ts

@@ -1,8 +1,11 @@
-import { readFile } from 'fs/promises';
+import * as fs from 'fs';
 
 import { MongoAWSError } from '../../../error';
 import { ServiceWorkflow } from './service_workflow';
 
+/** Error for when the token is missing in the environment. */
+const TOKEN_MISSING_ERROR = 'AWS_WEB_IDENTITY_TOKEN_FILE must be set in the environment.';
+
 /**
  * Device workflow implementation for AWS.
  *
@@ -19,8 +22,8 @@ export class AwsServiceWorkflow extends ServiceWorkflow {
   async getToken(): Promise<string> {
     const tokenFile = process.env.AWS_WEB_IDENTITY_TOKEN_FILE;
     if (!tokenFile) {
-      throw new MongoAWSError('AWS_WEB_IDENTITY_TOKEN_FILE must be set in the environment.');
+      throw new MongoAWSError(TOKEN_MISSING_ERROR);
     }
-    return readFile(tokenFile, 'utf8');
+    return fs.promises.readFile(tokenFile, 'utf8');
   }
 }

package/src/cmap/auth/mongodb_oidc/cache.ts

@@ -0,0 +1,27 @@
+/**
+ * Base class for OIDC caches.
+ */
+export abstract class Cache<T> {
+  entries: Map<string, T>;
+
+  /**
+   * Create a new cache.
+   */
+  constructor() {
+    this.entries = new Map<string, T>();
+  }
+
+  /**
+   * Clear the cache.
+   */
+  clear() {
+    this.entries.clear();
+  }
+
+  /**
+   * Create a cache key from the address and username.
+   */
+  cacheKey(address: string, username: string, callbackHash: string): string {
+    return JSON.stringify([address, username, callbackHash]);
+  }
+}

package/src/cmap/auth/mongodb_oidc/callback_lock_cache.ts

@@ -0,0 +1,107 @@
+import { MongoInvalidArgumentError } from '../../../error';
+import type { Connection } from '../../connection';
+import type { MongoCredentials } from '../mongo_credentials';
+import type {
+  IdPServerInfo,
+  IdPServerResponse,
+  OIDCCallbackContext,
+  OIDCRefreshFunction,
+  OIDCRequestFunction
+} from '../mongodb_oidc';
+import { Cache } from './cache';
+
+/** Error message for when request callback is missing. */
+const REQUEST_CALLBACK_REQUIRED_ERROR =
+  'Auth mechanism property REQUEST_TOKEN_CALLBACK is required.';
+/* Counter for function "hashes".*/
+let FN_HASH_COUNTER = 0;
+/* No function present function */
+const NO_FUNCTION: OIDCRequestFunction = async () => ({ accessToken: 'test' });
+/* The map of function hashes */
+const FN_HASHES = new WeakMap<OIDCRequestFunction | OIDCRefreshFunction, number>();
+/* Put the no function hash in the map. */
+FN_HASHES.set(NO_FUNCTION, FN_HASH_COUNTER);
+
+/**
+ * An entry of callbacks in the cache.
+ */
+interface CallbacksEntry {
+  requestCallback: OIDCRequestFunction;
+  refreshCallback?: OIDCRefreshFunction;
+  callbackHash: string;
+}
+
+/**
+ * A cache of request and refresh callbacks per server/user.
+ */
+export class CallbackLockCache extends Cache<CallbacksEntry> {
+  /**
+   * Get the callbacks for the connection and credentials. If an entry does not
+   * exist a new one will get set.
+   */
+  getCallbacks(connection: Connection, credentials: MongoCredentials): CallbacksEntry {
+    const requestCallback = credentials.mechanismProperties.REQUEST_TOKEN_CALLBACK;
+    const refreshCallback = credentials.mechanismProperties.REFRESH_TOKEN_CALLBACK;
+    if (!requestCallback) {
+      throw new MongoInvalidArgumentError(REQUEST_CALLBACK_REQUIRED_ERROR);
+    }
+    const callbackHash = hashFunctions(requestCallback, refreshCallback);
+    const key = this.cacheKey(connection.address, credentials.username, callbackHash);
+    const entry = this.entries.get(key);
+    if (entry) {
+      return entry;
+    }
+    return this.setCallbacks(key, callbackHash, requestCallback, refreshCallback);
+  }
+
+  /**
+   * Set locked callbacks on for connection and credentials.
+   */
+  private setCallbacks(
+    key: string,
+    callbackHash: string,
+    requestCallback: OIDCRequestFunction,
+    refreshCallback?: OIDCRefreshFunction
+  ): CallbacksEntry {
+    const entry = {
+      requestCallback: withLock(requestCallback),
+      refreshCallback: refreshCallback ? withLock(refreshCallback) : undefined,
+      callbackHash: callbackHash
+    };
+    this.entries.set(key, entry);
+    return entry;
+  }
+}
+
+/**
+ * Ensure the callback is only executed one at a time.
+ */
+function withLock(callback: OIDCRequestFunction | OIDCRefreshFunction) {
+  let lock: Promise<any> = Promise.resolve();
+  return async (info: IdPServerInfo, context: OIDCCallbackContext): Promise<IdPServerResponse> => {
+    await lock;
+    lock = lock.then(() => callback(info, context));
+    return lock;
+  };
+}
+
+/**
+ * Get the hash string for the request and refresh functions.
+ */
+function hashFunctions(requestFn: OIDCRequestFunction, refreshFn?: OIDCRefreshFunction): string {
+  let requestHash = FN_HASHES.get(requestFn);
+  let refreshHash = FN_HASHES.get(refreshFn ?? NO_FUNCTION);
+  if (requestHash == null) {
+    // Create a new one for the function and put it in the map.
+    FN_HASH_COUNTER++;
+    requestHash = FN_HASH_COUNTER;
+    FN_HASHES.set(requestFn, FN_HASH_COUNTER);
+  }
+  if (refreshHash == null && refreshFn) {
+    // Create a new one for the function and put it in the map.
+    FN_HASH_COUNTER++;
+    refreshHash = FN_HASH_COUNTER;
+    FN_HASHES.set(refreshFn, FN_HASH_COUNTER);
+  }
+  return `${requestHash}-${refreshHash}`;
+}