From 1178d8de965b10d3c0f6005a6d08dab4b0769606 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Fri, 13 Dec 2024 15:58:30 -0800 Subject: [PATCH 01/14] add csot doc and links --- .../connection/csot-operation.js | 27 +++ source/code-snippets/connection/csot.js | 29 +++ source/fundamentals/connection.txt | 2 + source/fundamentals/connection/csot.txt | 171 ++++++++++++++++++ 4 files changed, 229 insertions(+) create mode 100644 source/code-snippets/connection/csot-operation.js create mode 100644 source/code-snippets/connection/csot.js create mode 100644 source/fundamentals/connection/csot.txt diff --git a/source/code-snippets/connection/csot-operation.js b/source/code-snippets/connection/csot-operation.js new file mode 100644 index 000000000..8fb4ac0a4 --- /dev/null +++ b/source/code-snippets/connection/csot-operation.js @@ -0,0 +1,27 @@ +import { MongoClient } from "mongodb"; + +// start-operation +const uri = ""; +const client = new MongoClient(uri, { + timeoutMS: 1000 +}); + +async function run() { + try { + await client.connect(); // Ensure you connect the client + console.log("Connected to the database"); + + const db = client.db('test-db'); + const coll = db.collection('test-collection'); + + // Perform operations with the collection + const result = await coll.insertOne({ name: "Yngwie" }); + console.log("Insert result:", result); + } finally { + await client.close(); + } + } + + run().catch(console.dir); + +// end-operation \ No newline at end of file diff --git a/source/code-snippets/connection/csot.js b/source/code-snippets/connection/csot.js new file mode 100644 index 000000000..1e7e491f2 --- /dev/null +++ b/source/code-snippets/connection/csot.js @@ -0,0 +1,29 @@ +import { MongoClient } from "mongodb"; + +const { MongoClient } = require('mongodb'); + +//start-csot +async function run() { + // Creates a new MongoClient with a client-level timeoutMS configuration + const uri = ""; + const client = new MongoClient(uri, { + serverSelectionTimeoutMS: 5000 // Client-level timeout: 5 seconds + }); + + try { + await client.connect(); + + const db = client.db('test-db'); + const coll = database.collection('test-collection'); + + // Performs a query operation with an operation-level timeoutMS configuration + const docs = await coll.find({}, { timeoutMS: 1000 }).toArray(); // Operation-level timeout: 1 second + + console.log(docs); + } finally { + await client.close(); + } +} + +run().catch(console.dir); +//end-csot \ No newline at end of file diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt index ca2182d7d..c768dba01 100644 --- a/source/fundamentals/connection.txt +++ b/source/fundamentals/connection.txt @@ -21,6 +21,7 @@ Connection Network Compression TLS SOCKS5 Proxy Support + Limit Server Execution Time Connect with AWS Lambda .. contents:: On this page @@ -41,6 +42,7 @@ learn: - :ref:`How to Enable Network Compression ` - :ref:`How to Enable TLS on a Connection ` - :ref:`How to Enable SOCKS5 Proxy Support ` +- :ref:`How to Limit Server Execution Time ` - :atlas:`How to Connect to MongoDB Atlas from AWS Lambda ` Compatibility diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt new file mode 100644 index 000000000..f184b8bfa --- /dev/null +++ b/source/fundamentals/connection/csot.txt @@ -0,0 +1,171 @@ +.. _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 amount +of time the server has to finish this operation. To do so, specify a +**client-side operation timeout**. The timeout applies 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 as a client, database, collection, +session, and transaction option. + +To specify a timeout when connecting to a MongoDB deployment, set the +``timeoutMS`` connection option to the timeout length, in milliseconds. + +The following code examples use the ``timeoutMS`` option to specify a timeout of +10 seconds: + +.. code-block:: javascript + + const uri = "mongodb://:@"; + const client = new MongoClient(uri, { + timeoutMS: 1000 + }); + +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, ``timeoutMS`` will deprecate + and supersede the preceding 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, then calls the +``insertOne`` method. + +.. literalinclude:: /code-snippets/connection/csot-operation.js + :language: javascript + :start-after: start-operation + :end-before: end-operation + +Overrides +--------- + +The Node.js driver supports various levels of configuration to control the +behavior and performance of database operations. + +You can specify a ``timoutMS`` option at the operation level. This setting +overrides the client-level configuration for that specific operation, allowing +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 + +.. tip:: Transactions and timeoutMS + + If you try to override the ``timeoutMS`` option at the operation level for + operations using the explicit session inside the ``withTransaction`` + callback, it throws an error. + +ClientEncryption +~~~~~~~~~~~~~~~~~ + +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 in two ways. + +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 (for example, +``find``, ``aggregate``, ``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 via the +``close()`` method, resets the timeout before sending a ``killCursors`` +operation to the server. + +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: 1000}).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. + +The cursor continues to fetch new documents as they are added to a collection, +then times out if it takes longer than 10 seconds to retrieve documents, as +shown in the following example: + +.. code-block:: javascript + + for await (const doc of cappedCollection.find({}, {tailable: true, timeoutMS: 1000})) { + // 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>`__ From 0b8b950d8762a928ba6098c395cdc3c30475e0ec Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Fri, 13 Dec 2024 16:29:49 -0800 Subject: [PATCH 02/14] fix spacing --- source/code-snippets/connection/csot.js | 6 ++++-- source/fundamentals/connection/csot.txt | 5 +++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/source/code-snippets/connection/csot.js b/source/code-snippets/connection/csot.js index 1e7e491f2..b684aeb11 100644 --- a/source/code-snippets/connection/csot.js +++ b/source/code-snippets/connection/csot.js @@ -14,10 +14,12 @@ async function run() { await client.connect(); const db = client.db('test-db'); - const coll = database.collection('test-collection'); + const coll = db.collection('test-collection'); // Performs a query operation with an operation-level timeoutMS configuration - const docs = await coll.find({}, { timeoutMS: 1000 }).toArray(); // Operation-level timeout: 1 second + const docs = await coll.find({}, + { timeoutMS: 1000 }) // Operation-level timeout: 1 second + .toArray(); console.log(docs); } finally { diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index f184b8bfa..8acf29aeb 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -157,8 +157,9 @@ shown in the following example: .. code-block:: javascript - for await (const doc of cappedCollection.find({}, {tailable: true, timeoutMS: 1000})) { - // Handle each document + for await (const doc of cappedCollection.find({}, + {tailable: true, timeoutMS: 1000})) { + // Handle each document }; API Documentation From 0d5a095286b731900bfb1c651d5968f4b619f8c3 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 16 Dec 2024 11:54:14 -0800 Subject: [PATCH 03/14] edits --- source/fundamentals/connection/csot.txt | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index 8acf29aeb..411e8e89d 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -35,14 +35,15 @@ You can specify a timeout by using the ``timeoutMS`` option. timeoutMS Option ---------------- -You can specify the ``timeoutMS`` option as a client, database, collection, -session, and transaction 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. +``timeoutMS`` connection option to the timeout length in milliseconds. -The following code examples use the ``timeoutMS`` option to specify a timeout of -10 seconds: +The following code example uses the ``timeoutMS`` option to specify a timeout of +10 seconds when instatiating a new ``MongoClient`` instance: .. code-block:: javascript @@ -81,11 +82,11 @@ Overrides The Node.js driver supports various levels of configuration to control the behavior and performance of database operations. -You can specify a ``timoutMS`` option at the operation level. This setting -overrides the client-level configuration for that specific operation, allowing -you to customize timeouts based on the needs of individual queries. +You can specify a ``timoutMS`` 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`` +The following example demonstrates how an operation-level ``timeoutMS`` configuration can override a client-level ``timeoutMS`` configuration: .. literalinclude:: /code-snippets/connection/csot.js @@ -132,7 +133,7 @@ cursor. This is the default timeout mode for non-tailable cursors (for example, 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 via the +Closing a cursor, either as part of a ``toArray()`` call or manually using the ``close()`` method, resets the timeout before sending a ``killCursors`` operation to the server. From 703252c9d93759da76dae04a3a6104418f954775 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 16 Dec 2024 13:05:42 -0800 Subject: [PATCH 04/14] expand transactions section and add reference links --- source/fundamentals/connection/csot.txt | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index 411e8e89d..6ea626bc2 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -94,11 +94,27 @@ configuration can override a client-level ``timeoutMS`` configuration: :start-after: start-csot :end-before: end-csot -.. tip:: Transactions and timeoutMS +Transactions +~~~~~~~~~~~~ - If you try to override the ``timeoutMS`` option at the operation level for - operations using the explicit session inside the ``withTransaction`` - callback, it throws an error. +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``. + +If you try to override ``defaultTimeoutMS`` by setting the ``timeoutMS`` option +at the operation level for operations using the explicit session inside the +``withTransaction()`` callback, it throws an error. ClientEncryption ~~~~~~~~~~~~~~~~~ @@ -171,3 +187,4 @@ API documentation: - `MongoClient <{+api+}/classes/MongoClient.html>`__ - `timeoutMS <{+api+}/classes/MongoClient.html#timeoutMS>`__ +- `ClientSession <{+api+}/classes/ClientSession.html>`__ \ No newline at end of file From 381da042ba5ae98e45c4af5aeb4e32b565d72548 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 16 Dec 2024 14:10:46 -0800 Subject: [PATCH 05/14] cleanup code snippets --- .../connection/csot-operation.js | 13 ++++------- source/code-snippets/connection/csot.js | 22 +++++++++---------- 2 files changed, 15 insertions(+), 20 deletions(-) diff --git a/source/code-snippets/connection/csot-operation.js b/source/code-snippets/connection/csot-operation.js index 8fb4ac0a4..293f69781 100644 --- a/source/code-snippets/connection/csot-operation.js +++ b/source/code-snippets/connection/csot-operation.js @@ -8,13 +8,9 @@ const client = new MongoClient(uri, { async function run() { try { - await client.connect(); // Ensure you connect the client - console.log("Connected to the database"); - - const db = client.db('test-db'); - const coll = db.collection('test-collection'); - - // Perform operations with the collection + 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 { @@ -22,6 +18,5 @@ async function run() { } } - run().catch(console.dir); - +run().catch(console.dir); // end-operation \ No newline at end of file diff --git a/source/code-snippets/connection/csot.js b/source/code-snippets/connection/csot.js index b684aeb11..1f6d9ab66 100644 --- a/source/code-snippets/connection/csot.js +++ b/source/code-snippets/connection/csot.js @@ -3,22 +3,22 @@ import { MongoClient } from "mongodb"; const { MongoClient } = require('mongodb'); //start-csot -async function run() { - // Creates a new MongoClient with a client-level timeoutMS configuration - const uri = ""; - const client = new MongoClient(uri, { - serverSelectionTimeoutMS: 5000 // Client-level timeout: 5 seconds - }); +// Creates a new MongoClient with a client-level timeoutMS configuration +const uri = ""; +const client = new MongoClient(uri, { + // Client-level timeout: 5 seconds + serverSelectionTimeoutMS: 5000 +}); +async function run() { try { - await client.connect(); - - const db = client.db('test-db'); - const coll = db.collection('test-collection'); + 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({}, - { timeoutMS: 1000 }) // Operation-level timeout: 1 second + // Operation-level timeout: 1 second + { timeoutMS: 1000 }) .toArray(); console.log(docs); From 9145ed6172b0c7e9ca93d0ec2e3418b8b0b9a03d Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 17 Dec 2024 12:54:02 -0800 Subject: [PATCH 06/14] add list --- source/fundamentals/connection/csot.txt | 35 +++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index 6ea626bc2..581d672c2 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -76,6 +76,41 @@ a timeout limit of 10 seconds at the collection level, then calls the :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: + +- **Operation Level**: The operation-level ``timeoutMS`` option takes the + highest precedence and will override this option set at any other layer. + +- **Transaction Level**: The transaction-level ``timeoutMS`` option takes + precedence over ``timeoutMS`` set at the session, collection, database, or + client level. + +- **Session Level**: The session-level ``timeoutMS`` option inherits down to all + transactions and operations within that session, unless the option is + overriden by options set at those levels. + +- **Collection Level**: The collection-level ``timeoutMS`` option inherits down + to all sessions nad operations on that collection, unless the option is overriden. + +- **Database Level**: The database-level ``timeoutMS`` option 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 overriden. + +- **Client Level**: The client-level ``timeoutMS`` option 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 +` section. + +.. _node-csot-overrides: + Overrides --------- From 20827e26c7e686c95f0c13aaecd681a3e43be3f5 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 17 Dec 2024 14:01:34 -0800 Subject: [PATCH 07/14] update workflow --- .github/workflows/vale-tdbx.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/vale-tdbx.yml b/.github/workflows/vale-tdbx.yml index 284033abe..050fcd56c 100644 --- a/.github/workflows/vale-tdbx.yml +++ b/.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 From 74770f053181906a35903d8fab5336d3a5e01c17 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 17 Dec 2024 14:15:19 -0800 Subject: [PATCH 08/14] edits --- source/fundamentals/connection/csot.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index 581d672c2..e7138ff39 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -19,11 +19,12 @@ Limit Server Execution Time Overview -------- -When you use {+driver-short+} to perform a server operation, you can also limit the amount -of time the server has to finish this operation. To do so, specify a -**client-side operation timeout**. The timeout applies 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. +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. @@ -185,8 +186,7 @@ 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 before sending a ``killCursors`` -operation to the server. +``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: From d87f15cc212703a1d8d2a8b5a5a6f05706ed6944 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 17 Dec 2024 16:02:03 -0800 Subject: [PATCH 09/14] cleanup --- source/fundamentals/connection/csot.txt | 47 ++++++++++++------------- 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index e7138ff39..7fb47799f 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -44,7 +44,7 @@ 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 instatiating a new ``MongoClient`` instance: +10 seconds when instantiating a new ``MongoClient`` instance: .. code-block:: javascript @@ -70,7 +70,7 @@ following 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, then calls the -``insertOne`` method. +``insertOne()`` method. .. literalinclude:: /code-snippets/connection/csot-operation.js :language: javascript @@ -84,28 +84,25 @@ 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: -- **Operation Level**: The operation-level ``timeoutMS`` option takes the - highest precedence and will override this option set at any other layer. +- **Operation Level**: Takes the highest precedence and will override this + option set at any other layer. -- **Transaction Level**: The transaction-level ``timeoutMS`` option takes - precedence over ``timeoutMS`` set at the session, collection, database, or - client level. +- **Transaction Level**: Takes precedence over ``timeoutMS`` set at the session, + collection, database, or client level. -- **Session Level**: The session-level ``timeoutMS`` option inherits down to all - transactions and operations within that session, unless the option is - overriden by options set at those levels. +- **Session Level**: Inherits down to all transactions and operations within + that session, unless the option is overridden by options set at those levels. -- **Collection Level**: The collection-level ``timeoutMS`` option inherits down - to all sessions nad operations on that collection, unless the option is overriden. +- **Collection Level**: Inherits down to all sessions and operations on that + collection, unless the option is overridden. -- **Database Level**: The database-level ``timeoutMS`` option 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 overriden. +- **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. -- **Client Level**: The client-level ``timeoutMS`` option applies to all - databases, collections, sessions, transactions, and operations within that - client that do not otherwise specify ``timeoutMS``. +- **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 ` section. @@ -118,7 +115,7 @@ Overrides The Node.js driver supports various levels of configuration to control the behavior and performance of database operations. -You can specify a ``timoutMS`` option at the operation level to override the +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. @@ -181,8 +178,8 @@ 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 (for example, -``find``, ``aggregate``, ``listCollections``). In this mode, the initialization -of the cursor and all subsequent ``getMore`` calls must finish within the limit +``find()``, ``aggregate()``, ``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 @@ -198,9 +195,9 @@ of all documents occur within 10 seconds, as shown in the following example: 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 +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. The cursor continues to fetch new documents as they are added to a collection, From f4134ad9954e007cc13d07e7d30e0633e40b8b27 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 18 Dec 2024 09:17:23 -0800 Subject: [PATCH 10/14] change section heading --- source/fundamentals/connection/csot.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index 7fb47799f..6095ed322 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -78,7 +78,7 @@ a timeout limit of 10 seconds at the collection level, then calls the :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. From 0d5f77a4bb66df553fc952a56b0a23a907762bd2 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 30 Dec 2024 13:22:37 -0800 Subject: [PATCH 11/14] lm feedback --- .../connection/csot-operation.js | 2 +- source/code-snippets/connection/csot.js | 8 +-- source/fundamentals/connection/csot.txt | 53 ++++++++++--------- 3 files changed, 33 insertions(+), 30 deletions(-) diff --git a/source/code-snippets/connection/csot-operation.js b/source/code-snippets/connection/csot-operation.js index 293f69781..d3482443f 100644 --- a/source/code-snippets/connection/csot-operation.js +++ b/source/code-snippets/connection/csot-operation.js @@ -3,7 +3,7 @@ import { MongoClient } from "mongodb"; // start-operation const uri = ""; const client = new MongoClient(uri, { - timeoutMS: 1000 + timeoutMS: 10000 }); async function run() { diff --git a/source/code-snippets/connection/csot.js b/source/code-snippets/connection/csot.js index 1f6d9ab66..0be473f82 100644 --- a/source/code-snippets/connection/csot.js +++ b/source/code-snippets/connection/csot.js @@ -6,8 +6,8 @@ const { MongoClient } = require('mongodb'); // Creates a new MongoClient with a client-level timeoutMS configuration const uri = ""; const client = new MongoClient(uri, { - // Client-level timeout: 5 seconds - serverSelectionTimeoutMS: 5000 + // Client-level timeout: 15 seconds + timeoutMS: 15000 }); async function run() { @@ -17,8 +17,8 @@ async function run() { // Performs a query operation with an operation-level timeoutMS configuration const docs = await coll.find({}, - // Operation-level timeout: 1 second - { timeoutMS: 1000 }) + // Operation-level timeout: 10 second + { timeoutMS: 10000 }) .toArray(); console.log(docs); diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index 6095ed322..4f0c2e446 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -37,7 +37,7 @@ timeoutMS Option ---------------- You can specify the ``timeoutMS`` option in your ``MongoClientOptions`` -instance, or at the database, collection, session, transaction, or operation +instance or at the database, collection, session, transaction, or operation levels. To specify a timeout when connecting to a MongoDB deployment, set the @@ -50,7 +50,7 @@ The following code example uses the ``timeoutMS`` option to specify a timeout of const uri = "mongodb://:@"; const client = new MongoClient(uri, { - timeoutMS: 1000 + timeoutMS: 10000 }); When you specify the ``timeoutMS`` option, it always takes precedence over the @@ -64,13 +64,14 @@ following options: .. note:: Experimental Feature - When the CSOT feature is no longer experimental, ``timeoutMS`` will deprecate - and supersede the preceding options. + 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, then calls the -``insertOne()`` method. +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 @@ -82,23 +83,24 @@ 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: +The following list describes how the timeout value is inherited at each level: -- **Operation Level**: Takes the highest precedence and will override this - option set at any other layer. +- **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 down to all transactions and operations within +- **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 down to all sessions and operations on that - collection, unless the option is overridden. +- **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. + 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 @@ -145,11 +147,11 @@ the ``defaultTimeoutMS`` option. You can set ``defaultTimeoutMS`` to specify the If you do not specify ``defaultTimeoutMS``, the driver uses the ``timeoutMS`` value set on the parent ``MongoClient``. -If you try to override ``defaultTimeoutMS`` by setting the ``timeoutMS`` option -at the operation level for operations using the explicit session inside the -``withTransaction()`` callback, it throws an error. +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. -ClientEncryption +Client Encryption ~~~~~~~~~~~~~~~~~ When you use Client-Side Field Level Encryption (CSFLE), the driver uses the @@ -171,14 +173,15 @@ 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 in two ways. +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 (for example, -``find()``, ``aggregate()``, ``listCollections()``). In this mode, the initialization +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. @@ -197,17 +200,17 @@ 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 +default mode for all tailable cursors, such as tailable ``find()`` cursors on capped collections or change streams. -The cursor continues to fetch new documents as they are added to a collection, -then times out if it takes longer than 10 seconds to retrieve documents, as -shown in the following example: +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: 1000})) { + {tailable: true, timeoutMS: 10000})) { // Handle each document }; From 5f4f261c927804e22b305dbb263cfe62163e5e42 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 31 Dec 2024 08:37:52 -0800 Subject: [PATCH 12/14] update snippet --- source/code-snippets/connection/csot.js | 2 +- source/fundamentals/connection/csot.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/code-snippets/connection/csot.js b/source/code-snippets/connection/csot.js index 0be473f82..8a10333b9 100644 --- a/source/code-snippets/connection/csot.js +++ b/source/code-snippets/connection/csot.js @@ -17,7 +17,7 @@ async function run() { // Performs a query operation with an operation-level timeoutMS configuration const docs = await coll.find({}, - // Operation-level timeout: 10 second + // Operation-level timeout: 10 seconds { timeoutMS: 10000 }) .toArray(); diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index 4f0c2e446..775f914ab 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -193,7 +193,7 @@ of all documents occur within 10 seconds, as shown in the following example: .. code-block:: javascript - const docs = await collection.find({}, {timeoutMS: 1000}).toArray(); + const docs = await collection.find({}, {timeoutMS: 10000}).toArray(); Cursor Iteration Mode ~~~~~~~~~~~~~~~~~~~~~ From 75909a99377631ec797d9be417a9e56251554a61 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Fri, 3 Jan 2025 13:51:41 -0800 Subject: [PATCH 13/14] MW feedback --- source/fundamentals/connection/csot.txt | 81 ++++++++++++------------- 1 file changed, 38 insertions(+), 43 deletions(-) diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index 775f914ab..c65590016 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -21,56 +21,50 @@ 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 +specify a **client-side operation timeout (CSOT)**. 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. + The 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. +``timeoutMS`` connection option to the timeout length in milliseconds. You can +specify the ``timeoutMS`` option in your ``MongoClientOptions`` instance or at +the database, collection, session, transaction, or operation levels. 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://:@"; + const uri = "mongodb://"; const client = new MongoClient(uri, { timeoutMS: 10000 }); -When you specify the ``timeoutMS`` option, it always takes precedence over the -following options: +.. note:: -- ``socketTimeoutMS`` -- ``waitQueueTimeoutMS`` -- ``wTimeoutMS`` -- ``maxTimeMS`` -- ``maxCommitTimeMS`` + The ``timeoutMS`` connection option takes precedence over the + following options: -.. note:: Experimental Feature + - ``socketTimeoutMS`` + - ``waitQueueTimeoutMS`` + - ``wTimeoutMS`` + - ``maxTimeMS`` + - ``maxCommitTimeMS`` When the CSOT feature is no longer experimental, the preceding options will - be deprecated. The ``timeoutMS`` option will superse the older, deprecated - options. + be deprecated. 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 +a timeout limit of 10 seconds at the client level, and then calls the ``insertOne()`` method: .. literalinclude:: /code-snippets/connection/csot-operation.js @@ -78,8 +72,8 @@ a timeout limit of 10 seconds at the collection level, and then calls the :start-after: start-operation :end-before: end-operation -Inheritance Behavior -~~~~~~~~~~~~~~~~~~~~ +Timeout Inheritance +~~~~~~~~~~~~~~~~~~~ When you specify a ``timeoutMS`` option, the driver applies the timeout according to the same inheritance behaviors as other {+driver-short+} options. @@ -91,10 +85,10 @@ The following list describes how the timeout value is inherited at each 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 +- **Session Level**: Applies 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 Level**: Applies 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 @@ -114,7 +108,7 @@ For more information on overrides and specific options, see the :ref:`Overrides Overrides --------- -The Node.js driver supports various levels of configuration to control the +The {+driver-short+} 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 @@ -171,25 +165,25 @@ 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 +Cursors require special handling when you use the CSOT feature. You can configure +cursors to interact with CSOT by using either 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. +The cursor lifetime mode uses ``timeoutMS`` to limit the entire lifetime of a +cursor. This is the default timeout mode for non-tailable cursors, such as those +returned by the ``find()``, ``aggregate()``, or ``listCollections()`` methods. +In this mode, the initialization of the cursor and all subsequent calls to the +``getMore()`` method must finish within the limit specified by the ``timeoutMS`` +option. 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. +When you close a cursor by calling the ``toArray()``or ``close()`` method, the +timeout resets. -Set the ``timeoutMS`` option to ensure the cursor initialization and retrieval -of all documents occur within 10 seconds, as shown in the following example: +The following example shows how to set the ``timeoutMS`` option to ensure that +the cursor is initialized and all documents are retrieved within 10 seconds: .. code-block:: javascript @@ -198,10 +192,11 @@ of all documents occur within 10 seconds, as shown in the following example: 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. +The cursor iteration mode uses the ``timeoutMS`` option to limit each call to +the ``next()``, ``hasNext()``, or ``tryNext()`` method. The timeout refreshes +after each call completes. This is the default mode for all tailable cursors, +such as the tailable cursors returned by the ``find()`` method 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 From b5d5f6da6544b89f35c53b8be24e909686992a94 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Fri, 3 Jan 2025 14:54:40 -0800 Subject: [PATCH 14/14] add table --- source/fundamentals/connection/csot.txt | 39 +++++++++++++++---------- 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/source/fundamentals/connection/csot.txt b/source/fundamentals/connection/csot.txt index c65590016..eb34a1a82 100644 --- a/source/fundamentals/connection/csot.txt +++ b/source/fundamentals/connection/csot.txt @@ -77,28 +77,35 @@ Timeout Inheritance 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: +The following table 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. +.. list-table:: + :header-rows: 1 + :widths: 30 70 -- **Transaction Level**: Takes precedence over ``timeoutMS`` set at the session, - collection, database, or client level. + * - Level + - Inheritance Description -- **Session Level**: Applies to all transactions and operations within - that session, unless the option is overridden by options set at those levels. + * - Operation + - Takes the highest precedence and will override ``timeoutMS`` + options set at any other level. -- **Collection Level**: Applies to all sessions and operations on that - collection, unless the option is overridden by options set at those levels. + * - Transaction + - Takes precedence over ``timeoutMS`` set at the session, + collection, database, or client level. -- **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. + * - Session + - Applies to all transactions and operations within + that session, unless the option is overridden by options set at those levels. -- **Client Level**: Applies to all databases, collections, sessions, - transactions, and operations within that client that do not otherwise specify - ``timeoutMS``. + * - Collection + - Applies to all sessions and operations on that + collection, unless the option is overridden by options set at those levels. + + * - Client + - 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 ` section.