mongodb 5.2.0 → 5.4.0

package/src/cmap/auth/mongodb_oidc.ts

@@ -1,21 +1,23 @@
+import type { Document } from 'bson';
+
 import { MongoInvalidArgumentError, MongoMissingCredentialsError } from '../../error';
 import type { HandshakeDocument } from '../connect';
-import { type AuthContext, AuthProvider } from './auth_provider';
+import type { Connection } from '../connection';
+import { AuthContext, AuthProvider } from './auth_provider';
 import type { MongoCredentials } from './mongo_credentials';
 import { AwsServiceWorkflow } from './mongodb_oidc/aws_service_workflow';
 import { CallbackWorkflow } from './mongodb_oidc/callback_workflow';
-import type { Workflow } from './mongodb_oidc/workflow';
+
+/** Error when credentials are missing. */
+const MISSING_CREDENTIALS_ERROR = 'AuthContext must provide credentials.';
 
 /**
  * @public
  * @experimental
  */
-export interface OIDCMechanismServerStep1 {
-  authorizationEndpoint?: string;
-  tokenEndpoint?: string;
-  deviceAuthorizationEndpoint?: string;
+export interface IdPServerInfo {
+  issuer: string;
   clientId: string;
-  clientSecret?: string;
   requestScopes?: string[];
 }
 
@@ -23,35 +25,61 @@ export interface OIDCMechanismServerStep1 {
  * @public
  * @experimental
  */
-export interface OIDCRequestTokenResult {
+export interface IdPServerResponse {
   accessToken: string;
   expiresInSeconds?: number;
   refreshToken?: string;
 }
 
+/**
+ * @public
+ * @experimental
+ */
+export interface OIDCCallbackContext {
+  refreshToken?: string;
+  timeoutSeconds?: number;
+  timeoutContext?: AbortSignal;
+  version: number;
+}
+
 /**
  * @public
  * @experimental
  */
 export type OIDCRequestFunction = (
-  principalName: string,
-  serverResult: OIDCMechanismServerStep1,
-  timeout: AbortSignal | number
-) => Promise<OIDCRequestTokenResult>;
+  info: IdPServerInfo,
+  context: OIDCCallbackContext
+) => Promise<IdPServerResponse>;
 
 /**
  * @public
  * @experimental
  */
 export type OIDCRefreshFunction = (
-  principalName: string,
-  serverResult: OIDCMechanismServerStep1,
-  result: OIDCRequestTokenResult,
-  timeout: AbortSignal | number
-) => Promise<OIDCRequestTokenResult>;
+  info: IdPServerInfo,
+  context: OIDCCallbackContext
+) => Promise<IdPServerResponse>;
 
 type ProviderName = 'aws' | 'callback';
 
+export interface Workflow {
+  /**
+   * All device workflows must implement this method in order to get the access
+   * token and then call authenticate with it.
+   */
+  execute(
+    connection: Connection,
+    credentials: MongoCredentials,
+    reauthenticating: boolean,
+    response?: Document
+  ): Promise<Document>;
+
+  /**
+   * Get the document to add for speculative authentication.
+   */
+  speculativeAuth(credentials: MongoCredentials): Promise<Document>;
+}
+
 /** @internal */
 export const OIDC_WORKFLOWS: Map<ProviderName, Workflow> = new Map();
 OIDC_WORKFLOWS.set('callback', new CallbackWorkflow());
@@ -73,19 +101,10 @@ export class MongoDBOIDC extends AuthProvider {
    * Authenticate using OIDC
    */
   override async auth(authContext: AuthContext): Promise<void> {
-    const { connection, credentials, response, reauthenticating } = authContext;
-
-    if (response?.speculativeAuthenticate) {
-      return;
-    }
-
-    if (!credentials) {
-      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
-    }
-
+    const { connection, reauthenticating, response } = authContext;
+    const credentials = getCredentials(authContext);
     const workflow = getWorkflow(credentials);
-
-    await workflow.execute(connection, credentials, reauthenticating);
+    await workflow.execute(connection, credentials, reauthenticating, response);
   }
 
   /**
@@ -95,19 +114,24 @@ export class MongoDBOIDC extends AuthProvider {
     handshakeDoc: HandshakeDocument,
     authContext: AuthContext
   ): Promise<HandshakeDocument> {
-    const { credentials } = authContext;
-
-    if (!credentials) {
-      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
-    }
-
+    const credentials = getCredentials(authContext);
     const workflow = getWorkflow(credentials);
-
-    const result = await workflow.speculativeAuth();
+    const result = await workflow.speculativeAuth(credentials);
     return { ...handshakeDoc, ...result };
   }
 }
 
+/**
+ * Get credentials from the auth context, throwing if they do not exist.
+ */
+function getCredentials(authContext: AuthContext): MongoCredentials {
+  const { credentials } = authContext;
+  if (!credentials) {
+    throw new MongoMissingCredentialsError(MISSING_CREDENTIALS_ERROR);
+  }
+  return credentials;
+}
+
 /**
  * Gets either a device workflow or callback workflow.
  */

package/src/cmap/command_monitoring_events.ts

@@ -1,5 +1,11 @@
 import type { Document, ObjectId } from '../bson';
-import { LEGACY_HELLO_COMMAND, LEGACY_HELLO_COMMAND_CAMEL_CASE } from '../constants';
+import {
+  COMMAND_FAILED,
+  COMMAND_STARTED,
+  COMMAND_SUCCEEDED,
+  LEGACY_HELLO_COMMAND,
+  LEGACY_HELLO_COMMAND_CAMEL_CASE
+} from '../constants';
 import { calculateDurationInMs, deepCopy } from '../utils';
 import { Msg, WriteProtocolMessageType } from './commands';
 import type { Connection } from './connection';
@@ -18,6 +24,8 @@ export class CommandStartedEvent {
   address: string;
   connectionId?: string | number;
   serviceId?: ObjectId;
+  /** @internal */
+  name = COMMAND_STARTED;
 
   /**
    * Create a started event
@@ -65,6 +73,8 @@ export class CommandSucceededEvent {
   commandName: string;
   reply: unknown;
   serviceId?: ObjectId;
+  /** @internal */
+  name = COMMAND_SUCCEEDED;
 
   /**
    * Create a succeeded event
@@ -113,6 +123,8 @@ export class CommandFailedEvent {
   commandName: string;
   failure: Error;
   serviceId?: ObjectId;
+  /** @internal */
+  name = COMMAND_FAILED;
 
   /**
    * Create a failure event

package/src/cmap/connect.ts

@@ -17,7 +17,7 @@ import {
   MongoRuntimeError,
   needsRetryableWriteLabel
 } from '../error';
-import { Callback, ClientMetadata, HostAddress, ns } from '../utils';
+import { Callback, HostAddress, ns } from '../utils';
 import { AuthContext, AuthProvider } from './auth/auth_provider';
 import { GSSAPI } from './auth/gssapi';
 import { MongoCR } from './auth/mongocr';
@@ -28,6 +28,7 @@ import { AuthMechanism } from './auth/providers';
 import { ScramSHA1, ScramSHA256 } from './auth/scram';
 import { X509 } from './auth/x509';
 import { CommandOptions, Connection, ConnectionOptions, CryptoConnection } from './connection';
+import type { ClientMetadata } from './handshake/client_metadata';
 import {
   MAX_SUPPORTED_SERVER_VERSION,
   MAX_SUPPORTED_WIRE_VERSION,
@@ -400,6 +401,7 @@ function makeConnection(options: MakeConnectionOptions, _callback: Callback<Stre
 
     if ('authorizationError' in socket) {
       if (socket.authorizationError && rejectUnauthorized) {
+        // TODO(NODE-5192): wrap this with a MongoError subclass
         return callback(socket.authorizationError);
       }
     }

package/src/cmap/connection.ts

@@ -29,7 +29,6 @@ import { applySession, ClientSession, updateSessionFromResponse } from '../sessi
 import {
   calculateDurationInMs,
   Callback,
-  ClientMetadata,
   HostAddress,
   maxWireVersion,
   MongoDBNamespace,
@@ -46,6 +45,7 @@ import {
 } from './command_monitoring_events';
 import { BinMsg, Msg, Query, Response, WriteProtocolMessageType } from './commands';
 import type { Stream } from './connect';
+import type { ClientMetadata } from './handshake/client_metadata';
 import { MessageStream, OperationDescription } from './message_stream';
 import { StreamDescription, StreamDescriptionOptions } from './stream_description';
 import { getReadPreference, isSharded } from './wire_protocol/shared';
@@ -122,7 +122,9 @@ export interface ConnectionOptions
   credentials?: MongoCredentials;
   connectTimeoutMS?: number;
   tls: boolean;
+  /** @deprecated - Will not be able to turn off in the future. */
   keepAlive?: boolean;
+  /** @deprecated - Will not be configurable in the future. */
   keepAliveInitialDelay?: number;
   noDelay?: boolean;
   socketTimeoutMS?: number;
@@ -482,22 +484,23 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
 
   command(
     ns: MongoDBNamespace,
-    cmd: Document,
+    command: Document,
     options: CommandOptions | undefined,
     callback: Callback
   ): void {
-    const readPreference = getReadPreference(cmd, options);
+    let cmd = { ...command };
+
+    const readPreference = getReadPreference(options);
     const shouldUseOpMsg = supportsOpMsg(this);
     const session = options?.session;
 
     let clusterTime = this.clusterTime;
-    let finalCmd = Object.assign({}, cmd);
 
     if (this.serverApi) {
       const { version, strict, deprecationErrors } = this.serverApi;
-      finalCmd.apiVersion = version;
-      if (strict != null) finalCmd.apiStrict = strict;
-      if (deprecationErrors != null) finalCmd.apiDeprecationErrors = deprecationErrors;
+      cmd.apiVersion = version;
+      if (strict != null) cmd.apiStrict = strict;
+      if (deprecationErrors != null) cmd.apiDeprecationErrors = deprecationErrors;
     }
 
     if (hasSessionSupport(this) && session) {
@@ -509,7 +512,7 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
         clusterTime = session.clusterTime;
       }
 
-      const err = applySession(session, finalCmd, options);
+      const err = applySession(session, cmd, options);
       if (err) {
         return callback(err);
       }
@@ -519,12 +522,12 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
 
     // if we have a known cluster time, gossip it
     if (clusterTime) {
-      finalCmd.$clusterTime = clusterTime;
+      cmd.$clusterTime = clusterTime;
     }
 
     if (isSharded(this) && !shouldUseOpMsg && readPreference && readPreference.mode !== 'primary') {
-      finalCmd = {
-        $query: finalCmd,
+      cmd = {
+        $query: cmd,
         $readPreference: readPreference.toJSON()
       };
     }
@@ -542,8 +545,8 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
 
     const cmdNs = `${ns.db}.$cmd`;
     const message = shouldUseOpMsg
-      ? new Msg(cmdNs, finalCmd, commandOptions)
-      : new Query(cmdNs, finalCmd, commandOptions);
+      ? new Msg(cmdNs, cmd, commandOptions)
+      : new Query(cmdNs, cmd, commandOptions);
 
     try {
       write(this, message, commandOptions, callback);

package/src/cmap/connection_pool.ts

@@ -641,7 +641,10 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
     }
   }
 
-  private destroyConnection(connection: Connection, reason: string) {
+  private destroyConnection(
+    connection: Connection,
+    reason: 'error' | 'idle' | 'stale' | 'poolClosed'
+  ) {
     this.emit(
       ConnectionPool.CONNECTION_CLOSED,
       new ConnectionClosedEvent(this, connection, reason)
@@ -701,7 +704,13 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
         this[kPending]--;
         this.emit(
           ConnectionPool.CONNECTION_CLOSED,
-          new ConnectionClosedEvent(this, { id: connectOptions.id, serviceId: undefined }, 'error')
+          new ConnectionClosedEvent(
+            this,
+            { id: connectOptions.id, serviceId: undefined },
+            'error',
+            // TODO(NODE-5192): Remove this cast
+            err as MongoError
+          )
         );
         if (err instanceof MongoNetworkError || err instanceof MongoServerError) {
           err.connectionGeneration = connectOptions.generation;
@@ -812,7 +821,7 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
         const error = this.closed ? new PoolClosedError(this) : new PoolClearedError(this);
         this.emit(
           ConnectionPool.CONNECTION_CHECK_OUT_FAILED,
-          new ConnectionCheckOutFailedEvent(this, reason)
+          new ConnectionCheckOutFailedEvent(this, reason, error)
         );
         if (waitQueueMember.timer) {
           clearTimeout(waitQueueMember.timer);
@@ -865,7 +874,8 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
           if (err) {
             this.emit(
               ConnectionPool.CONNECTION_CHECK_OUT_FAILED,
-              new ConnectionCheckOutFailedEvent(this, 'connectionError')
+              // TODO(NODE-5192): Remove this cast
+              new ConnectionCheckOutFailedEvent(this, 'connectionError', err as MongoError)
             );
           } else if (connection) {
             this[kCheckedOut].add(connection);

package/src/cmap/connection_pool_events.ts

@@ -1,5 +1,18 @@
 import type { ObjectId } from '../bson';
-import type { AnyError } from '../error';
+import {
+  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
+} from '../constants';
+import type { MongoError } from '../error';
 import type { Connection } from './connection';
 import type { ConnectionPool, ConnectionPoolOptions } from './connection_pool';
 
@@ -8,11 +21,24 @@ import type { ConnectionPool, ConnectionPoolOptions } from './connection_pool';
  * @public
  * @category Event
  */
-export class ConnectionPoolMonitoringEvent {
+export abstract class ConnectionPoolMonitoringEvent {
   /** A timestamp when the event was created  */
   time: Date;
   /** The address (host/port pair) of the pool */
   address: string;
+  /** @internal */
+  abstract name:
+    | typeof CONNECTION_CHECK_OUT_FAILED
+    | typeof CONNECTION_CHECK_OUT_STARTED
+    | typeof CONNECTION_CHECKED_IN
+    | typeof CONNECTION_CHECKED_OUT
+    | typeof CONNECTION_CLOSED
+    | typeof CONNECTION_CREATED
+    | typeof CONNECTION_POOL_CLEARED
+    | typeof CONNECTION_POOL_CLOSED
+    | typeof CONNECTION_POOL_CREATED
+    | typeof CONNECTION_POOL_READY
+    | typeof CONNECTION_READY;
 
   /** @internal */
   constructor(pool: ConnectionPool) {
@@ -29,6 +55,8 @@ export class ConnectionPoolMonitoringEvent {
 export class ConnectionPoolCreatedEvent extends ConnectionPoolMonitoringEvent {
   /** The options used to create this connection pool */
   options?: ConnectionPoolOptions;
+  /** @internal */
+  name = CONNECTION_POOL_CREATED;
 
   /** @internal */
   constructor(pool: ConnectionPool) {
@@ -43,6 +71,9 @@ export class ConnectionPoolCreatedEvent extends ConnectionPoolMonitoringEvent {
  * @category Event
  */
 export class ConnectionPoolReadyEvent extends ConnectionPoolMonitoringEvent {
+  /** @internal */
+  name = CONNECTION_POOL_READY;
+
   /** @internal */
   constructor(pool: ConnectionPool) {
     super(pool);
@@ -55,6 +86,9 @@ export class ConnectionPoolReadyEvent extends ConnectionPoolMonitoringEvent {
  * @category Event
  */
 export class ConnectionPoolClosedEvent extends ConnectionPoolMonitoringEvent {
+  /** @internal */
+  name = CONNECTION_POOL_CLOSED;
+
   /** @internal */
   constructor(pool: ConnectionPool) {
     super(pool);
@@ -69,6 +103,8 @@ export class ConnectionPoolClosedEvent extends ConnectionPoolMonitoringEvent {
 export class ConnectionCreatedEvent extends ConnectionPoolMonitoringEvent {
   /** A monotonically increasing, per-pool id for the newly created connection */
   connectionId: number | '<monitor>';
+  /** @internal */
+  name = CONNECTION_CREATED;
 
   /** @internal */
   constructor(pool: ConnectionPool, connection: { id: number | '<monitor>' }) {
@@ -85,6 +121,8 @@ export class ConnectionCreatedEvent extends ConnectionPoolMonitoringEvent {
 export class ConnectionReadyEvent extends ConnectionPoolMonitoringEvent {
   /** The id of the connection */
   connectionId: number | '<monitor>';
+  /** @internal */
+  name = CONNECTION_READY;
 
   /** @internal */
   constructor(pool: ConnectionPool, connection: Connection) {
@@ -104,17 +142,23 @@ export class ConnectionClosedEvent extends ConnectionPoolMonitoringEvent {
   /** The reason the connection was closed */
   reason: string;
   serviceId?: ObjectId;
+  /** @internal */
+  name = CONNECTION_CLOSED;
+  /** @internal */
+  error: MongoError | null;
 
   /** @internal */
   constructor(
     pool: ConnectionPool,
     connection: Pick<Connection, 'id' | 'serviceId'>,
-    reason: string
+    reason: 'idle' | 'stale' | 'poolClosed' | 'error',
+    error?: MongoError
   ) {
     super(pool);
     this.connectionId = connection.id;
-    this.reason = reason || 'unknown';
+    this.reason = reason;
     this.serviceId = connection.serviceId;
+    this.error = error ?? null;
   }
 }
 
@@ -124,6 +168,9 @@ export class ConnectionClosedEvent extends ConnectionPoolMonitoringEvent {
  * @category Event
  */
 export class ConnectionCheckOutStartedEvent extends ConnectionPoolMonitoringEvent {
+  /** @internal */
+  name = CONNECTION_CHECK_OUT_STARTED;
+
   /** @internal */
   constructor(pool: ConnectionPool) {
     super(pool);
@@ -137,12 +184,21 @@ export class ConnectionCheckOutStartedEvent extends ConnectionPoolMonitoringEven
  */
 export class ConnectionCheckOutFailedEvent extends ConnectionPoolMonitoringEvent {
   /** The reason the attempt to check out failed */
-  reason: AnyError | string;
+  reason: string;
+  /** @internal */
+  error?: MongoError;
+  /** @internal */
+  name = CONNECTION_CHECK_OUT_FAILED;
 
   /** @internal */
-  constructor(pool: ConnectionPool, reason: AnyError | string) {
+  constructor(
+    pool: ConnectionPool,
+    reason: 'poolClosed' | 'timeout' | 'connectionError',
+    error?: MongoError
+  ) {
     super(pool);
     this.reason = reason;
+    this.error = error;
   }
 }
 
@@ -154,6 +210,8 @@ export class ConnectionCheckOutFailedEvent extends ConnectionPoolMonitoringEvent
 export class ConnectionCheckedOutEvent extends ConnectionPoolMonitoringEvent {
   /** The id of the connection */
   connectionId: number | '<monitor>';
+  /** @internal */
+  name = CONNECTION_CHECKED_OUT;
 
   /** @internal */
   constructor(pool: ConnectionPool, connection: Connection) {
@@ -170,6 +228,8 @@ export class ConnectionCheckedOutEvent extends ConnectionPoolMonitoringEvent {
 export class ConnectionCheckedInEvent extends ConnectionPoolMonitoringEvent {
   /** The id of the connection */
   connectionId: number | '<monitor>';
+  /** @internal */
+  name = CONNECTION_CHECKED_IN;
 
   /** @internal */
   constructor(pool: ConnectionPool, connection: Connection) {
@@ -188,6 +248,8 @@ export class ConnectionPoolClearedEvent extends ConnectionPoolMonitoringEvent {
   serviceId?: ObjectId;
 
   interruptInUseConnections?: boolean;
+  /** @internal */
+  name = CONNECTION_POOL_CLEARED;
 
   /** @internal */
   constructor(