DRIVERS-1943 Make maxConnecting configurable (#1098)

source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst

@@ -9,8 +9,8 @@ Connection Monitoring and Pooling
 :Status: Accepted
 :Type: Standards
 :Minimum Server Version: N/A
-:Last Modified: 2021-06-02
-:Version: 1.5.1
+:Last Modified: 2021-11-08
+:Version: 1.5.2
 
 .. contents::
 
@@ -116,6 +116,15 @@ Drivers that implement a Connection Pool MUST support the following ConnectionPo
        *  Defaults to 0.
        */
       maxIdleTimeMS?: number;
+
+      /**
+       *  The maximum number of Connections a Pool may be establishing concurrently.
+       *  Establishment of a Connection is a part of its life cycle
+       *  starting after a ConnectionCreatedEvent and ending before a ConnectionReadyEvent.
+       *  If specified, MUST be a number > 0.
+       *  Defaults to 2.
+       */
+      maxConnecting?: number;
     }
 
 Additionally, Drivers that implement a Connection Pool MUST support the following ConnectionPoolOptions UNLESS that driver meets ALL of the following conditions:
@@ -269,7 +278,7 @@ has the following properties:
    -  Connections are not created in the background to satisfy minPoolSize
 
 -  **Capped:** a pool is capped if **maxPoolSize** is set to a non-zero value. If a pool is capped, then its total number of `Connections <#connection>`_ (including available and in use) MUST NOT exceed **maxPoolSize**
--  **Rate-limited:** A Pool MUST limit the number of connections being created at a given time to be 2 (maxConnecting). 
+-  **Rate-limited:** A Pool MUST limit the number of `Connections <#connection>`_ being `established <#establishing-a-connection-internal-implementation>`_ concurrently via the **maxConnecting** `pool option <#connection-pool-options-1>`_.
 
 
 .. code:: typescript
@@ -1138,6 +1147,8 @@ Change log
 
 :2021-06-02: Formalize the behavior of a `Background Thread <#background-thread>`__.
 
+:2021-11-08: Make maxConnecting configurable.
+
 .. Section for links.
 
 .. _Application Errors: /source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#application-errors

source/connection-monitoring-and-pooling/tests/pool-checkout-custom-maxConnecting-is-enforced.json

@@ -0,0 +1,81 @@
+{
+  "version": 1,
+  "style": "integration",
+  "description": "custom maxConnecting is enforced",
+  "runOn": [
+    {
+      "minServerVersion": "4.4.0"
+    }
+  ],
+  "failPoint": {
+    "configureFailPoint": "failCommand",
+    "mode": "alwaysOn",
+    "data": {
+      "failCommands": [
+        "isMaster",
+        "hello"
+      ],
+      "closeConnection": false,
+      "blockConnection": true,
+      "blockTimeMS": 500
+    }
+  },
+  "poolOptions": {
+    "maxConnecting": 1,
+    "maxPoolSize": 2,
+    "waitQueueTimeoutMS": 5000
+  },
+  "operations": [
+    {
+      "name": "ready"
+    },
+    {
+      "name": "start",
+      "target": "thread1"
+    },
+    {
+      "name": "start",
+      "target": "thread2"
+    },
+    {
+      "name": "checkOut",
+      "thread": "thread1"
+    },
+    {
+      "name": "waitForEvent",
+      "event": "ConnectionCreated",
+      "count": 1
+    },
+    {
+      "name": "checkOut",
+      "thread": "thread2"
+    },
+    {
+      "name": "waitForEvent",
+      "event": "ConnectionReady",
+      "count": 2
+    }
+  ],
+  "events": [
+    {
+      "type": "ConnectionCreated"
+    },
+    {
+      "type": "ConnectionReady"
+    },
+    {
+      "type": "ConnectionCreated"
+    },
+    {
+      "type": "ConnectionReady"
+    }
+  ],
+  "ignore": [
+    "ConnectionCheckOutStarted",
+    "ConnectionCheckedIn",
+    "ConnectionCheckedOut",
+    "ConnectionClosed",
+    "ConnectionPoolCreated",
+    "ConnectionPoolReady"
+  ]
+}

source/connection-monitoring-and-pooling/tests/pool-checkout-custom-maxConnecting-is-enforced.yml

@@ -0,0 +1,50 @@
+version: 1
+style: integration
+description: custom maxConnecting is enforced
+runOn:
+  -
+    minServerVersion: "4.4.0"
+failPoint:
+  configureFailPoint: failCommand
+  mode: "alwaysOn"
+  data:
+    failCommands: ["isMaster","hello"]
+    closeConnection: false
+    blockConnection: true
+    blockTimeMS: 500
+poolOptions:
+  maxConnecting: 1
+  # gives opportunity for the checkout in thread2 to establish a new connection, which it must not do until thread1 establishes one
+  maxPoolSize: 2
+  waitQueueTimeoutMS: 5000
+operations:
+  - name: ready
+  # thread1 exists to consume the single permit to open a connection,
+  # so that thread2 would be blocked acquiring a permit, which results in ordering its ConnectionCreated event after
+  # the ConnectionReady event from thread1.
+  - name: start
+    target: thread1
+  - name: start
+    target: thread2
+  - name: checkOut
+    thread: thread1
+  - name: waitForEvent
+    event: ConnectionCreated
+    count: 1
+  - name: checkOut
+    thread: thread2
+  - name: waitForEvent
+    event: ConnectionReady
+    count: 2
+events:
+  - type: ConnectionCreated
+  - type: ConnectionReady
+  - type: ConnectionCreated
+  - type: ConnectionReady
+ignore:
+  - ConnectionCheckOutStarted
+  - ConnectionCheckedIn
+  - ConnectionCheckedOut
+  - ConnectionClosed
+  - ConnectionPoolCreated
+  - ConnectionPoolReady

source/uri-options/tests/connection-pool-options.json

@@ -2,15 +2,16 @@
   "tests": [
     {
       "description": "Valid connection pool options are parsed correctly",
-      "uri": "mongodb://example.com/?maxIdleTimeMS=50000&maxPoolSize=5&minPoolSize=3",
+      "uri": "mongodb://example.com/?maxIdleTimeMS=50000&maxPoolSize=5&minPoolSize=3&maxConnecting=1",
       "valid": true,
       "warning": false,
       "hosts": null,
       "auth": null,
       "options": {
         "maxIdleTimeMS": 50000,
         "maxPoolSize": 5,
-        "minPoolSize": 3
+        "minPoolSize": 3,
+        "maxConnecting": 1
       }
     },
     {
@@ -52,6 +53,24 @@
       "options": {
         "minPoolSize": 0
       }
+    },
+    {
+      "description": "maxConnecting=0 causes a warning",
+      "uri": "mongodb://example.com/?maxConnecting=0",
+      "valid": true,
+      "warning": true,
+      "hosts": null,
+      "auth": null,
+      "options": {}
+    },
+    {
+      "description": "maxConnecting<0 causes a warning",
+      "uri": "mongodb://example.com/?maxConnecting=-1",
+      "valid": true,
+      "warning": true,
+      "hosts": null,
+      "auth": null,
+      "options": {}
     }
   ]
 }

source/uri-options/tests/connection-pool-options.yml

@@ -1,7 +1,7 @@
 tests:
     -
         description: "Valid connection pool options are parsed correctly"
-        uri: "mongodb://example.com/?maxIdleTimeMS=50000&maxPoolSize=5&minPoolSize=3"
+        uri: "mongodb://example.com/?maxIdleTimeMS=50000&maxPoolSize=5&minPoolSize=3&maxConnecting=1"
         valid: true
         warning: false
         hosts: ~
@@ -10,6 +10,7 @@ tests:
             maxIdleTimeMS: 50000
             maxPoolSize: 5
             minPoolSize: 3
+            maxConnecting: 1
     -
         description: "Non-numeric maxIdleTimeMS causes a warning"
         uri: "mongodb://example.com/?maxIdleTimeMS=invalid"
@@ -46,3 +47,21 @@ tests:
       auth: ~
       options:
           minPoolSize: 0 
+
+    -
+      description: "maxConnecting=0 causes a warning"
+      uri: "mongodb://example.com/?maxConnecting=0"
+      valid: true
+      warning: true
+      hosts: ~
+      auth: ~
+      options: {}
+
+    -
+      description: "maxConnecting<0 causes a warning"
+      uri: "mongodb://example.com/?maxConnecting=-1"
+      valid: true
+      warning: true
+      hosts: ~
+      auth: ~
+      options: {}

source/uri-options/uri-options.rst

@@ -3,15 +3,15 @@ URI Options Specification
 =========================
 
 :Spec Title: URI Options Specification
-:Spec Version: 1.9.0
+:Spec Version: 1.9.1
 :Author: Sam Rossi
 :Spec Lead: Bernie Hackett
 :Advisory Group: Scott L'Hommedieu
 :Approver(s): Cailin Nelson, Jeff Yemin, Matt Broadstone, Dan Pasette, Prashant Mital, Spencer Jackson
 :Informed: drivers@
 :Status: Accepted (Could be Draft, Accepted, Rejected, Final, or Replaced)
 :Type: Standards
-:Last Modified: 2021-10-14
+:Last Modified: 2021-11-08
 
 
 **Abstract**
@@ -210,6 +210,12 @@ pertaining to URI options apply here.
      - required for drivers with connection pools
      - The maximum number of clients or connections able to be created by a pool at a given time. This count includes connections which are currently checked out.
 
+   * - maxConnecting
+     - positive integer
+     - defined in the `Connection Pooling spec`_
+     - required for drivers with connection pools
+     - The maximum number of Connections a Pool may be establishing concurrently.
+
    * - maxStalenessSeconds
      - -1 (no max staleness check) or integer >= 90
      - defined in `max staleness spec <https://github.com/mongodb/specifications/blob/master/source/max-staleness/max-staleness.rst#api>`_
@@ -482,6 +488,7 @@ this specification MUST be updated to reflect those changes.
 Changes
 -------
 
+- 2021-11-08 Add maxConnecting option.
 - 2021-10-14 Add srvMaxHosts option. Merge headings discussing URI validation
   for directConnection option.
 - 2021-09-15 Add srvServiceName option