mongodb 4.2.1 → 4.4.0

package/src/cmap/auth/mongo_credentials.ts

@@ -1,22 +1,23 @@
 // Resolves the default auth mechanism according to
-
 import type { Document } from '../../bson';
 import { MongoAPIError, MongoMissingCredentialsError } from '../../error';
-import { AuthMechanism } from './defaultAuthProviders';
+import { emitWarningOnce } from '../../utils';
+import { GSSAPICanonicalizationValue } from './gssapi';
+import { AUTH_MECHS_AUTH_SRC_EXTERNAL, AuthMechanism } from './providers';
 
 // https://github.com/mongodb/specifications/blob/master/source/auth/auth.rst
-function getDefaultAuthMechanism(ismaster?: Document): AuthMechanism {
-  if (ismaster) {
-    // If ismaster contains saslSupportedMechs, use scram-sha-256
+function getDefaultAuthMechanism(hello?: Document): AuthMechanism {
+  if (hello) {
+    // If hello contains saslSupportedMechs, use scram-sha-256
     // if it is available, else scram-sha-1
-    if (Array.isArray(ismaster.saslSupportedMechs)) {
-      return ismaster.saslSupportedMechs.includes(AuthMechanism.MONGODB_SCRAM_SHA256)
+    if (Array.isArray(hello.saslSupportedMechs)) {
+      return hello.saslSupportedMechs.includes(AuthMechanism.MONGODB_SCRAM_SHA256)
         ? AuthMechanism.MONGODB_SCRAM_SHA256
         : AuthMechanism.MONGODB_SCRAM_SHA1;
     }
 
     // Fallback to legacy selection method. If wire version >= 3, use scram-sha-1
-    if (ismaster.maxWireVersion >= 3) {
+    if (hello.maxWireVersion >= 3) {
       return AuthMechanism.MONGODB_SCRAM_SHA1;
     }
   }
@@ -27,9 +28,10 @@ function getDefaultAuthMechanism(ismaster?: Document): AuthMechanism {
 
 /** @public */
 export interface AuthMechanismProperties extends Document {
+  SERVICE_HOST?: string;
   SERVICE_NAME?: string;
   SERVICE_REALM?: string;
-  CANONICALIZE_HOST_NAME?: boolean;
+  CANONICALIZE_HOST_NAME?: GSSAPICanonicalizationValue;
   AWS_SESSION_TOKEN?: string;
 }
 
@@ -89,6 +91,14 @@ export class MongoCredentials {
       }
     }
 
+    if ('gssapiCanonicalizeHostName' in this.mechanismProperties) {
+      emitWarningOnce(
+        'gssapiCanonicalizeHostName is deprecated. Please use CANONICALIZE_HOST_NAME instead.'
+      );
+      this.mechanismProperties.CANONICALIZE_HOST_NAME =
+        this.mechanismProperties.gssapiCanonicalizeHostName;
+    }
+
     Object.freeze(this.mechanismProperties);
     Object.freeze(this);
   }
@@ -107,16 +117,16 @@ export class MongoCredentials {
    * If the authentication mechanism is set to "default", resolves the authMechanism
    * based on the server version and server supported sasl mechanisms.
    *
-   * @param ismaster - An ismaster response from the server
+   * @param hello - A hello response from the server
    */
-  resolveAuthMechanism(ismaster?: Document): MongoCredentials {
+  resolveAuthMechanism(hello?: Document): MongoCredentials {
     // If the mechanism is not "default", then it does not need to be resolved
     if (this.mechanism.match(/DEFAULT/i)) {
       return new MongoCredentials({
         username: this.username,
         password: this.password,
         source: this.source,
-        mechanism: getDefaultAuthMechanism(ismaster),
+        mechanism: getDefaultAuthMechanism(hello),
         mechanismProperties: this.mechanismProperties
       });
     }
@@ -136,11 +146,7 @@ export class MongoCredentials {
       throw new MongoMissingCredentialsError(`Username required for mechanism '${this.mechanism}'`);
     }
 
-    if (
-      this.mechanism === AuthMechanism.MONGODB_GSSAPI ||
-      this.mechanism === AuthMechanism.MONGODB_AWS ||
-      this.mechanism === AuthMechanism.MONGODB_X509
-    ) {
+    if (AUTH_MECHS_AUTH_SRC_EXTERNAL.has(this.mechanism)) {
       if (this.source != null && this.source !== '$external') {
         // TODO(NODE-3485): Replace this with a MongoAuthValidationError
         throw new MongoAPIError(
@@ -162,6 +168,11 @@ export class MongoCredentials {
       // TODO(NODE-3485): Replace this with a MongoAuthValidationError
       throw new MongoAPIError(`Password not allowed for mechanism MONGODB-X509`);
     }
+
+    const canonicalization = this.mechanismProperties.CANONICALIZE_HOST_NAME ?? false;
+    if (!Object.values(GSSAPICanonicalizationValue).includes(canonicalization)) {
+      throw new MongoAPIError(`Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}`);
+    }
   }
 
   static merge(

package/src/cmap/auth/mongocr.ts

@@ -1,7 +1,8 @@
 import * as crypto from 'crypto';
-import { AuthProvider, AuthContext } from './auth_provider';
-import { Callback, ns } from '../../utils';
+
 import { MongoMissingCredentialsError } from '../../error';
+import { Callback, ns } from '../../utils';
+import { AuthContext, AuthProvider } from './auth_provider';
 
 export class MongoCR extends AuthProvider {
   auth(authContext: AuthContext, callback: Callback): void {

package/src/cmap/auth/mongodb_aws.ts

@@ -1,20 +1,19 @@
-import * as http from 'http';
 import * as crypto from 'crypto';
+import * as http from 'http';
 import * as url from 'url';
+
+import type { Binary, BSONSerializeOptions } from '../../bson';
 import * as BSON from '../../bson';
-import { AuthProvider, AuthContext } from './auth_provider';
-import { MongoCredentials } from './mongo_credentials';
+import { aws4 } from '../../deps';
 import {
-  MongoRuntimeError,
+  MongoCompatibilityError,
   MongoMissingCredentialsError,
-  MongoCompatibilityError
+  MongoRuntimeError
 } from '../../error';
-import { maxWireVersion, Callback, ns } from '../../utils';
-import type { BSONSerializeOptions } from '../../bson';
-
-import { aws4 } from '../../deps';
-import { AuthMechanism } from './defaultAuthProviders';
-import type { Binary } from 'bson';
+import { Callback, maxWireVersion, ns } from '../../utils';
+import { AuthContext, AuthProvider } from './auth_provider';
+import { MongoCredentials } from './mongo_credentials';
+import { AuthMechanism } from './providers';
 
 const ASCII_N = 110;
 const AWS_RELATIVE_URI = 'http://169.254.170.2';

package/src/cmap/auth/plain.ts

@@ -1,7 +1,7 @@
 import { Binary } from '../../bson';
-import { AuthProvider, AuthContext } from './auth_provider';
 import { MongoMissingCredentialsError } from '../../error';
 import { Callback, ns } from '../../utils';
+import { AuthContext, AuthProvider } from './auth_provider';
 
 export class Plain extends AuthProvider {
   auth(authContext: AuthContext, callback: Callback): void {

package/src/cmap/auth/providers.ts

@@ -0,0 +1,21 @@
+/** @public */
+export const AuthMechanism = Object.freeze({
+  MONGODB_AWS: 'MONGODB-AWS',
+  MONGODB_CR: 'MONGODB-CR',
+  MONGODB_DEFAULT: 'DEFAULT',
+  MONGODB_GSSAPI: 'GSSAPI',
+  MONGODB_PLAIN: 'PLAIN',
+  MONGODB_SCRAM_SHA1: 'SCRAM-SHA-1',
+  MONGODB_SCRAM_SHA256: 'SCRAM-SHA-256',
+  MONGODB_X509: 'MONGODB-X509'
+} as const);
+
+/** @public */
+export type AuthMechanism = typeof AuthMechanism[keyof typeof AuthMechanism];
+
+/** @internal */
+export const AUTH_MECHS_AUTH_SRC_EXTERNAL = new Set<AuthMechanism>([
+  AuthMechanism.MONGODB_GSSAPI,
+  AuthMechanism.MONGODB_AWS,
+  AuthMechanism.MONGODB_X509
+]);

package/src/cmap/auth/scram.ts

@@ -1,19 +1,19 @@
 import * as crypto from 'crypto';
+
 import { Binary, Document } from '../../bson';
+import { saslprep } from '../../deps';
 import {
   AnyError,
-  MongoRuntimeError,
-  MongoServerError,
   MongoInvalidArgumentError,
-  MongoMissingCredentialsError
+  MongoMissingCredentialsError,
+  MongoRuntimeError,
+  MongoServerError
 } from '../../error';
-import { AuthProvider, AuthContext } from './auth_provider';
-import { Callback, ns, emitWarning } from '../../utils';
-import type { MongoCredentials } from './mongo_credentials';
+import { Callback, emitWarning, ns } from '../../utils';
 import type { HandshakeDocument } from '../connect';
-
-import { saslprep } from '../../deps';
-import { AuthMechanism } from './defaultAuthProviders';
+import { AuthContext, AuthProvider } from './auth_provider';
+import type { MongoCredentials } from './mongo_credentials';
+import { AuthMechanism } from './providers';
 
 type CryptoMethod = 'sha1' | 'sha256';
 

package/src/cmap/auth/x509.ts

@@ -1,9 +1,9 @@
-import { AuthProvider, AuthContext } from './auth_provider';
-import { MongoMissingCredentialsError } from '../../error';
 import type { Document } from '../../bson';
+import { MongoMissingCredentialsError } from '../../error';
 import { Callback, ns } from '../../utils';
-import type { MongoCredentials } from './mongo_credentials';
 import type { HandshakeDocument } from '../connect';
+import { AuthContext, AuthProvider } from './auth_provider';
+import type { MongoCredentials } from './mongo_credentials';
 
 export class X509 extends AuthProvider {
   prepare(handshakeDoc: HandshakeDocument, authContext: AuthContext, callback: Callback): void {

package/src/cmap/command_monitoring_events.ts

@@ -1,7 +1,8 @@
-import { GetMore, KillCursor, Msg, WriteProtocolMessageType } from './commands';
+import type { Document, ObjectId } from '../bson';
+import { LEGACY_HELLO_COMMAND, LEGACY_HELLO_COMMAND_CAMEL_CASE } from '../constants';
 import { calculateDurationInMs, deepCopy } from '../utils';
+import { GetMore, KillCursor, Msg, WriteProtocolMessageType } from './commands';
 import type { Connection } from './connection';
-import type { Document, ObjectId } from '../bson';
 
 /**
  * An event indicating the start of a given
@@ -161,7 +162,7 @@ const SENSITIVE_COMMANDS = new Set([
   'copydb'
 ]);
 
-const HELLO_COMMANDS = new Set(['hello', 'ismaster', 'isMaster']);
+const HELLO_COMMANDS = new Set(['hello', LEGACY_HELLO_COMMAND, LEGACY_HELLO_COMMAND_CAMEL_CASE]);
 
 // helper methods
 const extractCommandName = (commandDoc: Document) => Object.keys(commandDoc)[0];

package/src/cmap/commands.ts

@@ -1,18 +1,18 @@
-import { ReadPreference } from '../read_preference';
+import type { BSONSerializeOptions, Document, Long } from '../bson';
 import * as BSON from '../bson';
-import { databaseNamespace } from '../utils';
-import { OP_QUERY, OP_GETMORE, OP_KILL_CURSORS, OP_MSG } from './wire_protocol/constants';
-import type { Long, Document, BSONSerializeOptions } from '../bson';
+import { MongoInvalidArgumentError, MongoRuntimeError } from '../error';
+import { ReadPreference } from '../read_preference';
 import type { ClientSession } from '../sessions';
+import { databaseNamespace } from '../utils';
 import type { CommandOptions } from './connection';
-import { MongoRuntimeError, MongoInvalidArgumentError } from '../error';
+import { OP_GETMORE, OP_KILL_CURSORS, OP_MSG, OP_QUERY } from './wire_protocol/constants';
 
 // Incrementing request id
 let _requestId = 0;
 
 // Query flags
 const OPTS_TAILABLE_CURSOR = 2;
-const OPTS_SLAVE = 4;
+const OPTS_SECONDARY = 4;
 const OPTS_OPLOG_REPLAY = 8;
 const OPTS_NO_CURSOR_TIMEOUT = 16;
 const OPTS_AWAIT_DATA = 32;
@@ -41,7 +41,7 @@ export interface OpQueryOptions extends CommandOptions {
   ignoreUndefined?: boolean;
   maxBsonSize?: number;
   checkKeys?: boolean;
-  slaveOk?: boolean;
+  secondaryOk?: boolean;
 
   requestId?: number;
   moreToCome?: boolean;
@@ -67,7 +67,7 @@ export class Query {
   checkKeys: boolean;
   batchSize: number;
   tailable: boolean;
-  slaveOk: boolean;
+  secondaryOk: boolean;
   oplogReplay: boolean;
   noCursorTimeout: boolean;
   awaitData: boolean;
@@ -112,7 +112,7 @@ export class Query {
 
     // Flags
     this.tailable = false;
-    this.slaveOk = typeof options.slaveOk === 'boolean' ? options.slaveOk : false;
+    this.secondaryOk = typeof options.secondaryOk === 'boolean' ? options.secondaryOk : false;
     this.oplogReplay = false;
     this.noCursorTimeout = false;
     this.awaitData = false;
@@ -146,8 +146,8 @@ export class Query {
       flags |= OPTS_TAILABLE_CURSOR;
     }
 
-    if (this.slaveOk) {
-      flags |= OPTS_SLAVE;
+    if (this.secondaryOk) {
+      flags |= OPTS_SECONDARY;
     }
 
     if (this.oplogReplay) {
@@ -469,8 +469,6 @@ export interface MessageHeader {
 export interface OpResponseOptions extends BSONSerializeOptions {
   raw?: boolean;
   documentsReturnedIn?: string | null;
-  // For now we use this internally to only prevent writeErrors from crashing the driver
-  validation?: { utf8: { writeErrors: boolean } };
 }
 
 /** @internal */
@@ -839,7 +837,7 @@ export class BinMsg {
     const promoteValues = options.promoteValues ?? this.opts.promoteValues;
     const promoteBuffers = options.promoteBuffers ?? this.opts.promoteBuffers;
     const bsonRegExp = options.bsonRegExp ?? this.opts.bsonRegExp;
-    const validation = options.validation ?? { utf8: { writeErrors: false } };
+    const validation = this.parseBsonSerializationOptions(options);
 
     // Set up the options
     const bsonOptions: BSONSerializeOptions = {
@@ -876,4 +874,14 @@ export class BinMsg {
 
     this.parsed = true;
   }
+
+  parseBsonSerializationOptions({ enableUtf8Validation }: BSONSerializeOptions): {
+    utf8: { writeErrors: false } | false;
+  } {
+    if (enableUtf8Validation === false) {
+      return { utf8: false };
+    }
+
+    return { utf8: { writeErrors: false } };
+  }
 }

package/src/cmap/connect.ts

@@ -1,39 +1,60 @@
+import type { Socket, SocketConnectOpts } from 'net';
 import * as net from 'net';
+import { SocksClient } from 'socks';
+import type { ConnectionOptions as TLSConnectionOpts, TLSSocket } from 'tls';
 import * as tls from 'tls';
-import { Connection, ConnectionOptions, CryptoConnection } from './connection';
+
+import type { Document } from '../bson';
+import { Int32 } from '../bson';
+import { LEGACY_HELLO_COMMAND } from '../constants';
 import {
-  MongoNetworkError,
-  MongoNetworkTimeoutError,
   AnyError,
   MongoCompatibilityError,
   MongoInvalidArgumentError,
-  MongoServerError,
-  MongoRuntimeError
+  MongoNetworkError,
+  MongoNetworkTimeoutError,
+  MongoRuntimeError,
+  MongoServerError
 } from '../error';
-import { AUTH_PROVIDERS, AuthMechanism } from './auth/defaultAuthProviders';
-import { AuthContext } from './auth/auth_provider';
-import { makeClientMetadata, ClientMetadata, Callback, CallbackWithType, ns } from '../utils';
 import {
-  MAX_SUPPORTED_WIRE_VERSION,
+  Callback,
+  CallbackWithType,
+  ClientMetadata,
+  HostAddress,
+  makeClientMetadata,
+  ns
+} from '../utils';
+import { AuthContext, AuthProvider } from './auth/auth_provider';
+import { GSSAPI } from './auth/gssapi';
+import { MongoCR } from './auth/mongocr';
+import { MongoDBAWS } from './auth/mongodb_aws';
+import { Plain } from './auth/plain';
+import { AuthMechanism } from './auth/providers';
+import { ScramSHA1, ScramSHA256 } from './auth/scram';
+import { X509 } from './auth/x509';
+import { Connection, ConnectionOptions, CryptoConnection } from './connection';
+import {
   MAX_SUPPORTED_SERVER_VERSION,
-  MIN_SUPPORTED_WIRE_VERSION,
-  MIN_SUPPORTED_SERVER_VERSION
+  MAX_SUPPORTED_WIRE_VERSION,
+  MIN_SUPPORTED_SERVER_VERSION,
+  MIN_SUPPORTED_WIRE_VERSION
 } from './wire_protocol/constants';
-import type { Document } from '../bson';
-import { Int32 } from '../bson';
 
-import type { Socket, SocketConnectOpts } from 'net';
-import type { TLSSocket, ConnectionOptions as TLSConnectionOpts } from 'tls';
-
-const FAKE_MONGODB_SERVICE_ID =
-  typeof process.env.FAKE_MONGODB_SERVICE_ID === 'string' &&
-  process.env.FAKE_MONGODB_SERVICE_ID.toLowerCase() === 'true';
+const AUTH_PROVIDERS = new Map<AuthMechanism | string, AuthProvider>([
+  [AuthMechanism.MONGODB_AWS, new MongoDBAWS()],
+  [AuthMechanism.MONGODB_CR, new MongoCR()],
+  [AuthMechanism.MONGODB_GSSAPI, new GSSAPI()],
+  [AuthMechanism.MONGODB_PLAIN, new Plain()],
+  [AuthMechanism.MONGODB_SCRAM_SHA1, new ScramSHA1()],
+  [AuthMechanism.MONGODB_SCRAM_SHA256, new ScramSHA256()],
+  [AuthMechanism.MONGODB_X509, new X509()]
+]);
 
 /** @public */
 export type Stream = Socket | TLSSocket;
 
 export function connect(options: ConnectionOptions, callback: Callback<Connection>): void {
-  makeConnection(options, (err, socket) => {
+  makeConnection({ ...options, existingSocket: undefined }, (err, socket) => {
     if (err || !socket) {
       return callback(err);
     }
@@ -46,15 +67,15 @@ export function connect(options: ConnectionOptions, callback: Callback<Connectio
   });
 }
 
-function checkSupportedServer(ismaster: Document, options: ConnectionOptions) {
+function checkSupportedServer(hello: Document, options: ConnectionOptions) {
   const serverVersionHighEnough =
-    ismaster &&
-    (typeof ismaster.maxWireVersion === 'number' || ismaster.maxWireVersion instanceof Int32) &&
-    ismaster.maxWireVersion >= MIN_SUPPORTED_WIRE_VERSION;
+    hello &&
+    (typeof hello.maxWireVersion === 'number' || hello.maxWireVersion instanceof Int32) &&
+    hello.maxWireVersion >= MIN_SUPPORTED_WIRE_VERSION;
   const serverVersionLowEnough =
-    ismaster &&
-    (typeof ismaster.minWireVersion === 'number' || ismaster.minWireVersion instanceof Int32) &&
-    ismaster.minWireVersion <= MAX_SUPPORTED_WIRE_VERSION;
+    hello &&
+    (typeof hello.minWireVersion === 'number' || hello.minWireVersion instanceof Int32) &&
+    hello.minWireVersion <= MAX_SUPPORTED_WIRE_VERSION;
 
   if (serverVersionHighEnough) {
     if (serverVersionLowEnough) {
@@ -62,13 +83,13 @@ function checkSupportedServer(ismaster: Document, options: ConnectionOptions) {
     }
 
     const message = `Server at ${options.hostAddress} reports minimum wire version ${JSON.stringify(
-      ismaster.minWireVersion
+      hello.minWireVersion
     )}, but this version of the Node.js Driver requires at most ${MAX_SUPPORTED_WIRE_VERSION} (MongoDB ${MAX_SUPPORTED_SERVER_VERSION})`;
     return new MongoCompatibilityError(message);
   }
 
   const message = `Server at ${options.hostAddress} reports maximum wire version ${
-    JSON.stringify(ismaster.maxWireVersion) ?? 0
+    JSON.stringify(hello.maxWireVersion) ?? 0
   }, but this version of the Node.js Driver requires at least ${MIN_SUPPORTED_WIRE_VERSION} (MongoDB ${MIN_SUPPORTED_SERVER_VERSION})`;
   return new MongoCompatibilityError(message);
 }
@@ -122,9 +143,9 @@ function performInitialHandshake(
         return;
       }
 
-      if ('isWritablePrimary' in response) {
-        // Provide pre-hello-style response document.
-        response.ismaster = response.isWritablePrimary;
+      if (!('isWritablePrimary' in response)) {
+        // Provide hello-style response document.
+        response.isWritablePrimary = response[LEGACY_HELLO_COMMAND];
       }
 
       if (response.helloOk) {
@@ -138,10 +159,6 @@ function performInitialHandshake(
       }
 
       if (options.loadBalanced) {
-        // TODO: Durran: Remove when server support exists. (NODE-3431)
-        if (FAKE_MONGODB_SERVICE_ID) {
-          response.serviceId = response.topologyVersion.processId;
-        }
         if (!response.serviceId) {
           return callback(
             new MongoCompatibilityError(
@@ -155,8 +172,8 @@ function performInitialHandshake(
       // NOTE: This is metadata attached to the connection while porting away from
       //       handshake being done in the `Server` class. Likely, it should be
       //       relocated, or at very least restructured.
-      conn.ismaster = response;
-      conn.lastIsMasterMS = new Date().getTime() - start;
+      conn.hello = response;
+      conn.lastHelloMS = new Date().getTime() - start;
 
       if (!response.arbiterOnly && credentials) {
         // store the response on auth context
@@ -185,6 +202,9 @@ function performInitialHandshake(
 }
 
 export interface HandshakeDocument extends Document {
+  /**
+   * @deprecated Use hello instead
+   */
   ismaster?: boolean;
   hello?: boolean;
   helloOk?: boolean;
@@ -200,7 +220,7 @@ function prepareHandshakeDocument(authContext: AuthContext, callback: Callback<H
   const { serverApi } = authContext.connection;
 
   const handshakeDoc: HandshakeDocument = {
-    [serverApi?.version ? 'hello' : 'ismaster']: true,
+    [serverApi?.version ? 'hello' : LEGACY_HELLO_COMMAND]: true,
     helloOk: true,
     client: options.metadata || makeClientMetadata(options),
     compression: compressors,
@@ -289,7 +309,9 @@ function parseConnectOptions(options: ConnectionOptions): SocketConnectOpts {
   }
 }
 
-function parseSslOptions(options: ConnectionOptions): TLSConnectionOpts {
+type MakeConnectionOptions = ConnectionOptions & { existingSocket?: Stream };
+
+function parseSslOptions(options: MakeConnectionOptions): TLSConnectionOpts {
   const result: TLSConnectionOpts = parseConnectOptions(options);
   // Merge in valid SSL options
   for (const name of LEGAL_TLS_SOCKET_OPTIONS) {
@@ -298,6 +320,10 @@ function parseSslOptions(options: ConnectionOptions): TLSConnectionOpts {
     }
   }
 
+  if (options.existingSocket) {
+    result.socket = options.existingSocket;
+  }
+
   // Set default sni servername to be the same as host
   if (result.servername == null && result.host && !net.isIP(result.host)) {
     result.servername = result.host;
@@ -310,17 +336,21 @@ const SOCKET_ERROR_EVENT_LIST = ['error', 'close', 'timeout', 'parseError'] as c
 type ErrorHandlerEventName = typeof SOCKET_ERROR_EVENT_LIST[number] | 'cancel';
 const SOCKET_ERROR_EVENTS = new Set(SOCKET_ERROR_EVENT_LIST);
 
-function makeConnection(options: ConnectionOptions, _callback: CallbackWithType<AnyError, Stream>) {
+function makeConnection(
+  options: MakeConnectionOptions,
+  _callback: CallbackWithType<AnyError, Stream>
+) {
   const useTLS = options.tls ?? false;
   const keepAlive = options.keepAlive ?? true;
   const socketTimeoutMS = options.socketTimeoutMS ?? Reflect.get(options, 'socketTimeout') ?? 0;
   const noDelay = options.noDelay ?? true;
-  const connectionTimeout = options.connectTimeoutMS ?? 30000;
+  const connectTimeoutMS = options.connectTimeoutMS ?? 30000;
   const rejectUnauthorized = options.rejectUnauthorized ?? true;
   const keepAliveInitialDelay =
     ((options.keepAliveInitialDelay ?? 120000) > socketTimeoutMS
       ? Math.round(socketTimeoutMS / 2)
       : options.keepAliveInitialDelay) ?? 120000;
+  const existingSocket = options.existingSocket;
 
   let socket: Stream;
   const callback: Callback<Stream> = function (err, ret) {
@@ -331,18 +361,34 @@ function makeConnection(options: ConnectionOptions, _callback: CallbackWithType<
     _callback(err, ret);
   };
 
+  if (options.proxyHost != null) {
+    // Currently, only Socks5 is supported.
+    return makeSocks5Connection(
+      {
+        ...options,
+        connectTimeoutMS // Should always be present for Socks5
+      },
+      callback
+    );
+  }
+
   if (useTLS) {
     const tlsSocket = tls.connect(parseSslOptions(options));
     if (typeof tlsSocket.disableRenegotiation === 'function') {
       tlsSocket.disableRenegotiation();
     }
     socket = tlsSocket;
+  } else if (existingSocket) {
+    // In the TLS case, parseSslOptions() sets options.socket to existingSocket,
+    // so we only need to handle the non-TLS case here (where existingSocket
+    // gives us all we need out of the box).
+    socket = existingSocket;
   } else {
     socket = net.createConnection(parseConnectOptions(options));
   }
 
   socket.setKeepAlive(keepAlive, keepAliveInitialDelay);
-  socket.setTimeout(connectionTimeout);
+  socket.setTimeout(connectTimeoutMS);
   socket.setNoDelay(noDelay);
 
   const connectEvent = useTLS ? 'secureConnect' : 'connect';
@@ -381,10 +427,80 @@ function makeConnection(options: ConnectionOptions, _callback: CallbackWithType<
     options.cancellationToken.once('cancel', cancellationHandler);
   }
 
-  socket.once(connectEvent, connectHandler);
+  if (existingSocket) {
+    process.nextTick(connectHandler);
+  } else {
+    socket.once(connectEvent, connectHandler);
+  }
+}
+
+function makeSocks5Connection(options: MakeConnectionOptions, callback: Callback<Stream>) {
+  const hostAddress = HostAddress.fromHostPort(
+    options.proxyHost ?? '', // proxyHost is guaranteed to set here
+    options.proxyPort ?? 1080
+  );
+
+  // First, connect to the proxy server itself:
+  makeConnection(
+    {
+      ...options,
+      hostAddress,
+      tls: false,
+      proxyHost: undefined
+    },
+    (err, rawSocket) => {
+      if (err) {
+        return callback(err);
+      }
+
+      const destination = parseConnectOptions(options) as net.TcpNetConnectOpts;
+      if (typeof destination.host !== 'string' || typeof destination.port !== 'number') {
+        return callback(
+          new MongoInvalidArgumentError('Can only make Socks5 connections to TCP hosts')
+        );
+      }
+
+      // Then, establish the Socks5 proxy connection:
+      SocksClient.createConnection(
+        {
+          existing_socket: rawSocket,
+          timeout: options.connectTimeoutMS,
+          command: 'connect',
+          destination: {
+            host: destination.host,
+            port: destination.port
+          },
+          proxy: {
+            // host and port are ignored because we pass existing_socket
+            host: 'iLoveJavaScript',
+            port: 0,
+            type: 5,
+            userId: options.proxyUsername || undefined,
+            password: options.proxyPassword || undefined
+          }
+        },
+        (err: AnyError, info: { socket: Stream }) => {
+          if (err) {
+            return callback(connectionFailureError('error', err));
+          }
+
+          // Finally, now treat the resulting duplex stream as the
+          // socket over which we send and receive wire protocol messages:
+          makeConnection(
+            {
+              ...options,
+              existingSocket: info.socket,
+              proxyHost: undefined
+            },
+            callback
+          );
+        }
+      );
+    }
+  );
 }
 
-function connectionFailureError(type: string, err: Error) {
+function connectionFailureError(type: ErrorHandlerEventName, err: Error) {
   switch (type) {
     case 'error':
       return new MongoNetworkError(err);