mongodb 5.2.0 → 5.3.0

package/src/connection_string.ts

@@ -6,6 +6,7 @@ import { URLSearchParams } from 'url';
 import type { Document } from './bson';
 import { MongoCredentials } from './cmap/auth/mongo_credentials';
 import { AUTH_MECHS_AUTH_SRC_EXTERNAL, AuthMechanism } from './cmap/auth/providers';
+import { makeClientMetadata } from './cmap/handshake/client_metadata';
 import { Compressor, CompressorName } from './cmap/wire_protocol/compression';
 import { Encrypter } from './encrypter';
 import {
@@ -32,7 +33,7 @@ import {
   emitWarningOnce,
   HostAddress,
   isRecord,
-  makeClientMetadata,
+  matchesParentDomain,
   parseInteger,
   setDifference
 } from './utils';
@@ -45,21 +46,6 @@ const LB_REPLICA_SET_ERROR = 'loadBalanced option not supported with a replicaSe
 const LB_DIRECT_CONNECTION_ERROR =
   'loadBalanced option not supported when directConnection is provided';
 
-/**
- * Determines whether a provided address matches the provided parent domain in order
- * to avoid certain attack vectors.
- *
- * @param srvAddress - The address to check against a domain
- * @param parentDomain - The domain to check the provided address against
- * @returns Whether the provided address matches the parent domain
- */
-function matchesParentDomain(srvAddress: string, parentDomain: string): boolean {
-  const regex = /^.*?\./;
-  const srv = `.${srvAddress.replace(regex, '')}`;
-  const parent = `.${parentDomain.replace(regex, '')}`;
-  return srv.endsWith(parent);
-}
-
 /**
  * Lookup a `mongodb+srv` connection string, combine the parts and reparse it as a normal
  * connection string.
@@ -277,7 +263,7 @@ export function parseOptions(
 
   mongoOptions.hosts = isSRV ? [] : hosts.map(HostAddress.fromString);
 
-  const urlOptions = new CaseInsensitiveMap<any[]>();
+  const urlOptions = new CaseInsensitiveMap<unknown[]>();
 
   if (url.pathname !== '/' && url.pathname !== '') {
     const dbName = decodeURIComponent(
@@ -312,7 +298,7 @@ export function parseOptions(
     }
   }
 
-  const objectOptions = new CaseInsensitiveMap(
+  const objectOptions = new CaseInsensitiveMap<unknown>(
     Object.entries(options).filter(([, v]) => v != null)
   );
 
@@ -330,48 +316,42 @@ export function parseOptions(
 
   // All option collection
 
-  const allOptions = new CaseInsensitiveMap();
+  const allProvidedOptions = new CaseInsensitiveMap<unknown[]>();
 
-  const allKeys = new Set<string>([
-    ...urlOptions.keys(),
-    ...objectOptions.keys(),
-    ...DEFAULT_OPTIONS.keys()
-  ]);
+  const allProvidedKeys = new Set<string>([...urlOptions.keys(), ...objectOptions.keys()]);
 
-  for (const key of allKeys) {
+  for (const key of allProvidedKeys) {
     const values = [];
     const objectOptionValue = objectOptions.get(key);
     if (objectOptionValue != null) {
       values.push(objectOptionValue);
     }
-    const urlValue = urlOptions.get(key);
-    if (urlValue != null) {
-      values.push(...urlValue);
-    }
-    const defaultOptionsValue = DEFAULT_OPTIONS.get(key);
-    if (defaultOptionsValue != null) {
-      values.push(defaultOptionsValue);
-    }
-    allOptions.set(key, values);
+
+    const urlValues = urlOptions.get(key) ?? [];
+    values.push(...urlValues);
+    allProvidedOptions.set(key, values);
   }
 
-  if (allOptions.has('tlsCertificateKeyFile') && !allOptions.has('tlsCertificateFile')) {
-    allOptions.set('tlsCertificateFile', allOptions.get('tlsCertificateKeyFile'));
+  if (
+    allProvidedOptions.has('tlsCertificateKeyFile') &&
+    !allProvidedOptions.has('tlsCertificateFile')
+  ) {
+    allProvidedOptions.set('tlsCertificateFile', allProvidedOptions.get('tlsCertificateKeyFile'));
   }
 
-  if (allOptions.has('tls') || allOptions.has('ssl')) {
-    const tlsAndSslOpts = (allOptions.get('tls') || [])
-      .concat(allOptions.get('ssl') || [])
+  if (allProvidedOptions.has('tls') || allProvidedOptions.has('ssl')) {
+    const tlsAndSslOpts = (allProvidedOptions.get('tls') || [])
+      .concat(allProvidedOptions.get('ssl') || [])
       .map(getBoolean.bind(null, 'tls/ssl'));
     if (new Set(tlsAndSslOpts).size !== 1) {
       throw new MongoParseError('All values of tls/ssl must be the same.');
     }
   }
 
-  checkTLSOptions(allOptions);
+  checkTLSOptions(allProvidedOptions);
 
   const unsupportedOptions = setDifference(
-    allKeys,
+    allProvidedKeys,
     Array.from(Object.keys(OPTIONS)).map(s => s.toLowerCase())
   );
   if (unsupportedOptions.size !== 0) {
@@ -385,9 +365,20 @@ export function parseOptions(
   // Option parsing and setting
 
   for (const [key, descriptor] of Object.entries(OPTIONS)) {
-    const values = allOptions.get(key);
-    if (!values || values.length === 0) continue;
-    setOption(mongoOptions, key, descriptor, values);
+    const values = allProvidedOptions.get(key);
+    if (!values || values.length === 0) {
+      if (DEFAULT_OPTIONS.has(key)) {
+        setOption(mongoOptions, key, descriptor, [DEFAULT_OPTIONS.get(key)]);
+      }
+    } else {
+      const { deprecated } = descriptor;
+      if (deprecated) {
+        const deprecatedMsg = typeof deprecated === 'string' ? `: ${deprecated}` : '';
+        emitWarning(`${key} is a deprecated option${deprecatedMsg}`);
+      }
+
+      setOption(mongoOptions, key, descriptor, values);
+    }
   }
 
   if (mongoOptions.credentials) {
@@ -397,7 +388,7 @@ export function parseOptions(
     const isOidc = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_OIDC;
     if (
       (isGssapi || isX509) &&
-      allOptions.has('authSource') &&
+      allProvidedOptions.has('authSource') &&
       mongoOptions.credentials.source !== '$external'
     ) {
       // If authSource was explicitly given and its incorrect, we error
@@ -409,7 +400,7 @@ export function parseOptions(
     if (
       !(isGssapi || isX509 || isAws || isOidc) &&
       mongoOptions.dbName &&
-      !allOptions.has('authSource')
+      !allProvidedOptions.has('authSource')
     ) {
       // inherit the dbName unless GSSAPI or X509, then silently ignore dbName
       // and there was no specific authSource given
@@ -585,14 +576,9 @@ function setOption(
   descriptor: OptionDescriptor,
   values: unknown[]
 ) {
-  const { target, type, transform, deprecated } = descriptor;
+  const { target, type, transform } = descriptor;
   const name = target ?? key;
 
-  if (deprecated) {
-    const deprecatedMsg = typeof deprecated === 'string' ? `: ${deprecated}` : '';
-    emitWarning(`${key} is a deprecated option${deprecatedMsg}`);
-  }
-
   switch (type) {
     case 'boolean':
       mongoOptions[name] = getBoolean(name, values[0]);
@@ -866,11 +852,13 @@ export const OPTIONS = {
   },
   keepAlive: {
     default: true,
-    type: 'boolean'
+    type: 'boolean',
+    deprecated: 'Will not be able to turn off in the future.'
   },
   keepAliveInitialDelay: {
     default: 120000,
-    type: 'uint'
+    type: 'uint',
+    deprecated: 'Will not be configurable in the future.'
   },
   loadBalanced: {
     default: false,
@@ -1292,5 +1280,6 @@ export const DEFAULT_OPTIONS = new CaseInsensitiveMap(
  */
 export const FEATURE_FLAGS = new Set([
   Symbol.for('@@mdb.skipPingOnConnect'),
-  Symbol.for('@@mdb.enableMongoLogger')
+  Symbol.for('@@mdb.enableMongoLogger'),
+  Symbol.for('@@mdb.internalLoggerConfig')
 ]);

package/src/constants.ts

@@ -23,16 +23,27 @@ export const SERVER_DESCRIPTION_CHANGED = 'serverDescriptionChanged' as const;
 export const TOPOLOGY_OPENING = 'topologyOpening' as const;
 export const TOPOLOGY_CLOSED = 'topologyClosed' as const;
 export const TOPOLOGY_DESCRIPTION_CHANGED = 'topologyDescriptionChanged' as const;
+/** @internal */
 export const CONNECTION_POOL_CREATED = 'connectionPoolCreated' as const;
+/** @internal */
 export const CONNECTION_POOL_CLOSED = 'connectionPoolClosed' as const;
+/** @internal */
 export const CONNECTION_POOL_CLEARED = 'connectionPoolCleared' as const;
+/** @internal */
 export const CONNECTION_POOL_READY = 'connectionPoolReady' as const;
+/** @internal */
 export const CONNECTION_CREATED = 'connectionCreated' as const;
+/** @internal */
 export const CONNECTION_READY = 'connectionReady' as const;
+/** @internal */
 export const CONNECTION_CLOSED = 'connectionClosed' as const;
+/** @internal */
 export const CONNECTION_CHECK_OUT_STARTED = 'connectionCheckOutStarted' as const;
+/** @internal */
 export const CONNECTION_CHECK_OUT_FAILED = 'connectionCheckOutFailed' as const;
+/** @internal */
 export const CONNECTION_CHECKED_OUT = 'connectionCheckedOut' as const;
+/** @internal */
 export const CONNECTION_CHECKED_IN = 'connectionCheckedIn' as const;
 export const CLUSTER_TIME_RECEIVED = 'clusterTimeReceived' as const;
 export const COMMAND_STARTED = 'commandStarted' as const;

package/src/cursor/abstract_cursor.ts

@@ -397,6 +397,7 @@ export abstract class AbstractCursor<
    * If the iterator returns `false`, iteration will stop.
    *
    * @param iterator - The iteration callback.
+   * @deprecated - Will be removed in a future release. Use for await...of instead.
    */
   async forEach(iterator: (doc: TSchema) => boolean | void): Promise<void> {
     if (typeof iterator !== 'function') {

package/src/db.ts

@@ -405,6 +405,8 @@ export class Db {
    * @param username - The username for the new user
    * @param passwordOrOptions - An optional password for the new user, or the options for the command
    * @param options - Optional settings for the command
+   * @deprecated Use the createUser command in `db.command()` instead.
+   * @see https://www.mongodb.com/docs/manual/reference/command/createUser/
    */
   async addUser(
     username: string,

package/src/index.ts

@@ -238,6 +238,7 @@ export type {
   WaitQueueMember,
   WithConnectionCallback
 } from './cmap/connection_pool';
+export type { ClientMetadata, ClientMetadataOptions } from './cmap/handshake/client_metadata';
 export type {
   MessageStream,
   MessageStreamOptions,
@@ -247,7 +248,20 @@ export type { ConnectionPoolMetrics } from './cmap/metrics';
 export type { StreamDescription, StreamDescriptionOptions } from './cmap/stream_description';
 export type { CompressorName } from './cmap/wire_protocol/compression';
 export type { CollectionOptions, CollectionPrivate, ModifyResult } from './collection';
-export type { MONGO_CLIENT_EVENTS } from './constants';
+export type {
+  CONNECTION_CHECK_OUT_FAILED,
+  CONNECTION_CHECK_OUT_STARTED,
+  CONNECTION_CHECKED_IN,
+  CONNECTION_CHECKED_OUT,
+  CONNECTION_CLOSED,
+  CONNECTION_CREATED,
+  CONNECTION_POOL_CLEARED,
+  CONNECTION_POOL_CLOSED,
+  CONNECTION_POOL_CREATED,
+  CONNECTION_POOL_READY,
+  CONNECTION_READY,
+  MONGO_CLIENT_EVENTS
+} from './constants';
 export type {
   AbstractCursorEvents,
   AbstractCursorOptions,
@@ -289,6 +303,11 @@ export type {
   WithSessionCallback
 } from './mongo_client';
 export type {
+  Log,
+  LogConvertible,
+  Loggable,
+  LoggableEvent,
+  MongoDBLogWritable,
   MongoLoggableComponent,
   MongoLogger,
   MongoLoggerEnvOptions,
@@ -463,8 +482,6 @@ export type { Transaction, TransactionOptions, TxnState } from './transactions';
 export type {
   BufferPool,
   Callback,
-  ClientMetadata,
-  ClientMetadataOptions,
   EventEmitterWithState,
   HostAddress,
   List,

package/src/mongo_client.ts

@@ -8,6 +8,7 @@ import type { AuthMechanismProperties, MongoCredentials } from './cmap/auth/mong
 import type { AuthMechanism } from './cmap/auth/providers';
 import type { LEGAL_TCP_SOCKET_OPTIONS, LEGAL_TLS_SOCKET_OPTIONS } from './cmap/connect';
 import type { Connection } from './cmap/connection';
+import type { ClientMetadata } from './cmap/handshake/client_metadata';
 import type { CompressorName } from './cmap/wire_protocol/compression';
 import { parseOptions, resolveSRVRecord } from './connection_string';
 import { MONGO_CLIENT_EVENTS } from './constants';
@@ -24,7 +25,7 @@ import { readPreferenceServerSelector } from './sdam/server_selection';
 import type { SrvPoller } from './sdam/srv_polling';
 import { Topology, TopologyEvents } from './sdam/topology';
 import { ClientSession, ClientSessionOptions, ServerSessionPool } from './sessions';
-import { ClientMetadata, HostAddress, MongoDBNamespace, ns, resolveOptions } from './utils';
+import { HostAddress, MongoDBNamespace, ns, resolveOptions } from './utils';
 import type { W, WriteConcern, WriteConcernSettings } from './write_concern';
 
 /** @public */
@@ -211,9 +212,12 @@ export interface MongoClientOptions extends BSONSerializeOptions, SupportedNodeC
   sslCRL?: string;
   /** TCP Connection no delay */
   noDelay?: boolean;
-  /** TCP Connection keep alive enabled */
+  /** @deprecated TCP Connection keep alive enabled. Will not be able to turn off in the future. */
   keepAlive?: boolean;
-  /** The number of milliseconds to wait before initiating keepAlive on the TCP socket */
+  /**
+   * @deprecated The number of milliseconds to wait before initiating keepAlive on the TCP socket.
+   *             Will not be configurable in the future.
+   */
   keepAliveInitialDelay?: number;
   /** Force server to assign `_id` values instead of driver */
   forceServerObjectId?: boolean;
@@ -363,6 +367,7 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> {
     };
   }
 
+  /** @see MongoOptions */
   get options(): Readonly<MongoOptions> {
     return Object.freeze({ ...this[kOptions] });
   }
@@ -660,7 +665,22 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> {
 }
 
 /**
- * Mongo Client Options
+ * Parsed Mongo Client Options.
+ *
+ * User supplied options are documented by `MongoClientOptions`.
+ *
+ * **NOTE:** The client's options parsing is subject to change to support new features.
+ * This type is provided to aid with inspection of options after parsing, it should not be relied upon programmatically.
+ *
+ * Options are sourced from:
+ * - connection string
+ * - options object passed to the MongoClient constructor
+ * - file system (ex. tls settings)
+ * - environment variables
+ * - DNS SRV records and TXT records
+ *
+ * Not all options may be present after client construction as some are obtained from asynchronous operations.
+ *
  * @public
  */
 export interface MongoOptions
@@ -717,6 +737,7 @@ export interface MongoOptions
   proxyPort?: number;
   proxyUsername?: string;
   proxyPassword?: string;
+
   /** @internal */
   connectionType?: typeof Connection;