DOCSP-4466 Add CSOT

.github/workflows/vale-tdbx.yml

@@ -11,6 +11,9 @@ jobs:
     steps:
       - name: checkout
         uses: actions/checkout@master
+
+      - name: Install docutils
+        run: sudo apt-get install -y docutils
 
       - id: files
         uses: masesgroup/retrieve-changed-files@v2

source/code-snippets/connection/csot-operation.js

@@ -0,0 +1,22 @@
+import { MongoClient } from "mongodb";
+
+// start-operation
+const uri = "<connection string uri>";
+const client = new MongoClient(uri, {
+  timeoutMS: 10000
+});
+
+async function run() {
+    try {
+      const db = client.db("test-db");
+      const coll = db.collection("test-collection");
+
+      const result = await coll.insertOne({ name: "Yngwie" });
+      console.log("Insert result:", result);
+    } finally {
+      await client.close();
+    }
+  }
+
+run().catch(console.dir);
+// end-operation

source/code-snippets/connection/csot.js

@@ -0,0 +1,31 @@
+import { MongoClient } from "mongodb";
+
+const { MongoClient } = require('mongodb');
+
+//start-csot
+// Creates a new MongoClient with a client-level timeoutMS configuration
+const uri = "<connection string uri>";
+const client = new MongoClient(uri, {
+  // Client-level timeout: 15 seconds
+  timeoutMS: 15000
+});
+
+async function run() {
+  try {
+    const db = client.db("test-db");
+    const coll = db.collection("test-collection");
+
+    // Performs a query operation with an operation-level timeoutMS configuration
+    const docs = await coll.find({}, 
+        // Operation-level timeout: 10 seconds
+        { timeoutMS: 10000 })
+        .toArray(); 
+
+    console.log(docs);
+  } finally {
+    await client.close();
+  }
+}
+
+run().catch(console.dir);
+//end-csot

source/fundamentals/connection.txt

@@ -21,6 +21,7 @@ Connection
    Network Compression </fundamentals/connection/network-compression>
    TLS </fundamentals/connection/tls>
    SOCKS5 Proxy Support </fundamentals/connection/socks>
+   Limit Server Execution Time </fundamentals/connection/csot>
    Connect with AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
 
 .. contents:: On this page
@@ -41,6 +42,7 @@ learn:
 - :ref:`How to Enable Network Compression <node-network-compression>`
 - :ref:`How to Enable TLS on a Connection <node-connect-tls>`
 - :ref:`How to Enable SOCKS5 Proxy Support <node-connect-socks>`
+- :ref:`How to Limit Server Execution Time <node-csot>`
 - :atlas:`How to Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`
 
 Compatibility

source/fundamentals/connection/csot.txt

@@ -0,0 +1,225 @@
+.. _node-csot:
+
+Limit Server Execution Time
+===========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: error, blocking, thread, task
+
+Overview
+--------
+
+When you use {+driver-short+} to perform a server operation, you can also limit
+the duration allowed for the server to finish the operation. To do so,
+specify a **client-side operation timeout**. The timeout applies to all steps
+needed to complete the operation, including server selection, connection
+checkout, serialization, and server-side execution. When the timeout expires,
+{+driver-short+} raises a timeout exception.
+
+You can specify a timeout by using the ``timeoutMS`` option.
+
+.. note:: Experimental Feature
+
+   The Client-Side Operation Timeout (CSOT) feature is experimental and might
+   change in future driver releases.
+
+timeoutMS Option
+----------------
+
+You can specify the ``timeoutMS`` option in your ``MongoClientOptions``
+instance or at the database, collection, session, transaction, or operation
+levels.
+
+To specify a timeout when connecting to a MongoDB deployment, set the
+``timeoutMS`` connection option to the timeout length in milliseconds.
+
+The following code example uses the ``timeoutMS`` option to specify a timeout of
+10 seconds when instantiating a new ``MongoClient`` instance:
+
+.. code-block:: javascript
+
+   const uri = "mongodb://<db_username>:<db_password>@<hostname:<port>";
+   const client = new MongoClient(uri, {
+     timeoutMS: 10000
+    });
+
+When you specify the ``timeoutMS`` option, it always takes precedence over the
+following options:
+
+- ``socketTimeoutMS``
+- ``waitQueueTimeoutMS``
+- ``wTimeoutMS``
+- ``maxTimeMS``
+- ``maxCommitTimeMS``
+
+.. note:: Experimental Feature
+
+   When the CSOT feature is no longer experimental, the preceding options will
+   be deprecated. The ``timeoutMS`` option will superse the older, deprecated
+   options. 
+
+If you specify the ``timeoutMS`` option, the driver automatically applies the
+specified timeout to each server operation. The following code example specifies
+a timeout limit of 10 seconds at the collection level, and then calls the
+``insertOne()`` method:
+
+.. literalinclude:: /code-snippets/connection/csot-operation.js
+   :language: javascript
+   :start-after: start-operation
+   :end-before: end-operation
+
+Inheritance Behavior
+~~~~~~~~~~~~~~~~~~~~
+
+When you specify a ``timeoutMS`` option, the driver applies the timeout
+according to the same inheritance behaviors as other {+driver-short+} options.
+The following list describes how the timeout value is inherited at each level:
+
+- **Operation Level**: Takes the highest precedence and will override ``timeoutMS``
+  options set at any other level.
+
+- **Transaction Level**: Takes precedence over ``timeoutMS`` set at the session,
+  collection, database, or client level.
+
+- **Session Level**: Inherits to all transactions and operations within
+  that session, unless the option is overridden by options set at those levels.
+
+- **Collection Level**: Inherits to all sessions and operations on that
+  collection, unless the option is overridden by options set at those levels.
+
+- **Database Level**: Applies to all collections within that database. It is
+  inherited by all sessions, collections, and operations within the collections
+  on that database, unless the option is overridden by an option set at a level
+  with higher precedence.
+
+- **Client Level**: Applies to all databases, collections, sessions,
+  transactions, and operations within that client that do not otherwise specify
+  ``timeoutMS``.
+
+For more information on overrides and specific options, see the :ref:`Overrides
+<node-csot-overrides>` section.
+
+.. _node-csot-overrides:
+
+Overrides
+---------
+
+The Node.js driver supports various levels of configuration to control the
+behavior and performance of database operations. 
+
+You can specify a ``timeoutMS`` option at the operation level to override the
+client-level configuration for a specific operation. This allows you to
+customize timeouts based on the needs of individual queries.
+
+The following example demonstrates how an operation-level ``timeoutMS``
+configuration can override a client-level ``timeoutMS`` configuration:
+
+.. literalinclude:: /code-snippets/connection/csot.js
+   :language: javascript
+   :start-after: start-csot
+   :end-before: end-csot
+
+Transactions
+~~~~~~~~~~~~
+
+When you create a new ``ClientSession`` instance to implement a transaction, use
+the ``defaultTimeoutMS`` option. You can set ``defaultTimeoutMS`` to specify the
+``timeoutMS`` values to use for:
+
+- `commitTransaction()
+  <{+api+}/classes/ClientSession.html#commitTransaction>`__
+- `abortTransaction()
+  <{+api+}/classes/ClientSession.html#abortTransaction>`__
+- `withTransaction() <{+api+}/classes/ClientSession.html#withTransaction>`__
+- `endSession()
+  <{+api+}/classes/ClientSession.html#endSession>`__
+
+If you do not specify ``defaultTimeoutMS``, the driver uses the ``timeoutMS``
+value set on the parent ``MongoClient``.
+
+You cannot override ``defaultTimeoutMS`` by setting the ``timeoutMS`` option on an
+operation in a transaction session provided by the ``withTransaction()`` callback.
+Doing so throws an error.
+
+Client Encryption
+~~~~~~~~~~~~~~~~~
+
+When you use Client-Side Field Level Encryption (CSFLE), the driver uses the
+``timeoutMS`` option to limit the time allowed for encryption and decryption
+operations.
+
+If you specify the ``timeoutMS`` option when you construct a
+``ClientEncryption`` instance, it controls the lifetime of all operations
+performed on that instance. If you do not provide ``timeoutMS``, the instance
+inherits the ``timeoutMS`` setting from the ``MongoClient`` used in the
+``ClientEncryption`` constructor.
+
+If you set ``timeoutMS`` on both the client and directly in
+``ClientEncryption``, the value provided to ``ClientEncryption`` takes
+precedence.
+
+Cursors
+-------
+
+Cursors require special handling when you use the CSOT feature. The
+``timeOutMS`` option is configurable on a per-cursor basis. You can configure
+cursors to interact with CSOT by using etiher the cursor lifetime or cursor
+iteration mode.
+
+Cursor Lifetime Mode
+~~~~~~~~~~~~~~~~~~~~
+
+The ``cursorLifetime`` mode uses ``timeoutMS`` to bound the entire lifetime of a
+cursor. This is the default timeout mode for non-tailable cursors, such as
+``find()``, ``aggregate()``, or ``listCollections()``. In this mode, the initialization
+of the cursor and all subsequent ``getMore()`` calls must finish within the limit
+specified with ``timeoutMS``. If they do not, the system throws a timeout error. 
+
+Closing a cursor, either as part of a ``toArray()`` call or manually using the
+``close()`` method, resets the timeout.
+
+Set the ``timeoutMS`` option to ensure the cursor initialization and retrieval
+of all documents occur within 10 seconds, as shown in the following example:
+
+.. code-block:: javascript
+
+   const docs = await collection.find({}, {timeoutMS: 10000}).toArray();
+
+Cursor Iteration Mode
+~~~~~~~~~~~~~~~~~~~~~
+
+The iteration mode uses ``timeoutMS`` to bind each ``next()``, ``hasNext()``, or
+``tryNext()`` call. The timeout refreshes after each call completes. This is the
+default mode for all tailable cursors, such as tailable ``find()`` cursors on
+capped collections or change streams.
+
+As shown in the following example, the cursor continues to fetch new documents
+as they are added to a collection, and then times out if it takes longer than 10
+seconds to retrieve documents:
+
+.. code-block:: javascript
+
+   for await (const doc of cappedCollection.find({}, 
+      {tailable: true, timeoutMS: 10000})) {
+      // Handle each document
+   };
+
+API Documentation
+-----------------
+
+To learn more about using timeouts with the {+driver-short+}, see the following
+API documentation:
+
+- `MongoClient <{+api+}/classes/MongoClient.html>`__
+- `timeoutMS <{+api+}/classes/MongoClient.html#timeoutMS>`__
+- `ClientSession <{+api+}/classes/ClientSession.html>`__