DRIVERS-2533: add RunCursorCommand API

source/run-command/run-command.rst

@@ -44,6 +44,8 @@ Deviations
 
 Please refer to `The CRUD specification's Guidance <https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst#guidance>`_ on how APIs may deviate between languages.
 
+Cursor iterating APIs MAY be offered via language syntax or predefined iterable methods.
+
 --------------
 ``runCommand``
 --------------
@@ -129,6 +131,10 @@ The logical session ID MUST be included under ``lsid`` in the command sent to th
 
 * See Driver Sessions' section on `Sending the session ID to the server on all commands <https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst#sending-the-session-id-to-the-server-on-all-commands>`_
 
+The command sent to the server MUST gossip the ``$clusterTime`` if cluster time support is detected.
+
+* See Driver Sessions' section on `Gossipping the cluster time <https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst#gossipping-the-cluster-time>`_
+
 Transactions
 """"""""""""
 
@@ -187,7 +193,160 @@ Drivers MUST document the behavior of RunCommand if a ``maxTimeMS`` field  is al
 * See Client Side Operations Timeout's section on `runCommand <https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst#runcommand>`_
 * See Client Side Operations Timeout's section on `runCommand behavior <https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst#runcommand-behavior>`_
 
+
+--------------------
+``runCursorCommand``
+--------------------
+
+The following represents how a runCursorCommand API may be exposed.
+
+.. code:: typescript
+
+    interface Database {
+      /**
+       * Takes an argument representing an arbitrary BSON document and executes it against the server.
+       */
+      runCursorCommand(command: BSONDocument, options: RunCursorCommandOptions): RunCommandCursor;
+    }
+
+    interface RunCursorCommandOptions extends RunCommandOptions {
+      /**
+       * For operations that create cursors, timeoutMS can either cap the lifetime of the cursor or be applied separately to the original operation and all subsequent calls.
+       * To support both of these use cases, these operations MUST support a timeoutMode option.
+       *
+       * @defaultValue 'CURSOR_LIFETIME'
+       *
+       * @see https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst
+       */
+      timeoutMode?: 'ITERATION' | 'CURSOR_LIFETIME';
+
+      /**
+       * Identifies the type of cursor this is.
+       *
+       * A tailable cursor can receive empty `nextBatch` arrays in `getMore` responses.
+       * However, subsequent `getMore` operations may return documents if new data has become available.
+       *
+       * A tailableAwait cursor is an enhancement where instead of dealing with empty responses the server will block until data becomes available.
+       *
+       * @defaultValue NON_TAILABLE
+       */
+      cursorType: NON_TAILABLE | TAILABLE | TAILABLE_AWAIT;
+    }
+
+RunCursorCommand implementation details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+RunCursorCommand provides a way to access MongoDB server commands that return a cursor directly without requiring a driver to implement a bespoke cursor implementation.
+The API is intended to be built upon RunCommand and take a document from a user and apply a number of common driver internal concerns before forwarding the command to a server.
+A driver can expect that the result from running this command will return a document with a ``cursor`` field and MUST provide the caller with a language native abstraction to continue iterating the results from the server.
+
+High level RunCursorCommand steps:
+
+* Run the cursor creating command provided by the caller and retain the ClientSession used as well as the server the command was executed on.
+* Create a local Cursor instance and store the ``firstBatch``, ``ns``, and ``id`` from the response.
+* When the current batch has been fully iterated, using the same server the initial command was executed on execute a ``getMore``
+* Store the ``nextBatch`` from the ``getMore`` response and update the cursor's ``id``
+* Continue executing ``getMore`` commands until the cursor is exhausted
+
+Driver Sessions
+"""""""""""""""
+
+A driver MUST create an implicit ClientSession if none is provided and it MUST be attached for the duration of the cursor's lifetime.
+All ``getMore`` commands constructed for this cursor MUST send the same ``lsid`` used on the initial command.
+A cursor is exhausted when the server reports a cursor is equal to zero.
+When the cursor is exhausted the client session MUST be ended and the server session returned to the pool as early as possible rather than waiting for a caller to completely iterate the final batch.
+
+* See Drivers Sessions' section on `Sessions and Cursors <https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst#sessions-and-cursors>`_
+
+Server Selection
+""""""""""""""""
+
+RunCursorCommand MUST support a ``readPreference`` option that MUST be used to determine server selection.
+The selected server MUST be used for subsequent ``getMore`` commands.
+
+Load Balancers
+""""""""""""""
+
+When in ``loadBalanced`` mode, a driver MUST pin the connection used to execute the initial operation, and reuse it for subsequent ``getMore`` operations.
+
+* See Load Balancer's section on `Behaviour With Cursors <https://github.com/mongodb/specifications/blob/master/source/load-balancers/load-balancers.rst#behaviour-with-cursors>`_
+
+Iterating the Cursor
+""""""""""""""""""""
+
+Drivers MUST provide an API, typically, a method named ``next()``, that returns one document per invocation.
+If the cursor's batch is empty and the cursor id is nonzero, the driver MUST perform a ``getMore`` operation.
+
+Executing GetMores
+""""""""""""""""""
+
+The cursor API returned to the caller MUST offer a way to configure ``batchSize``, ``maxTimeMS``, and ``comment`` that are sent on the ``getMore`` command.
+
+.. code:: typescript
+
+  interface GetMore {
+    /** Set to the nonzero cursor id */
+    getMore: int64;
+    /** Set to the namespace returned by the initial command response */
+    collection: string;
+    /**
+     * User configurable document count for the batch returned for this getMore.
+     * Only attached to command document if nonzero.
+     */
+    batchSize?: int32;
+    /**
+     * User configurable time limit enforced by the server.
+     */
+    maxTimeMS?: int32;
+    /**
+     * User configurable comment that can be used to identify the operation in logs.
+     * This can be any BSON value.
+     */
+    comment?: BSONValue;
+  }
+
+The driver's cursor MUST update its ``id`` and ``ns``, as well as store the ``nextBatch`` from every ``getMore`` response.
+
+* See Find, getMore and killCursors commands' section on `GetMore <https://github.com/mongodb/specifications/blob/master/source/find_getmore_killcursors_commands.rst#getmore>`_
+
+Tailable and TailableAwait
+""""""""""""""""""""""""""
+
+By default most cursors are non-tailable, for example, a ``find`` that exhausts when all results for the filter have been satisfied.
+MongoDB also supports creating cursors that "tail" or follow the target namespace for new data.
+Querying capped collections and change streams are some examples of tailable cursor use cases.
+A tailable cursor can receive ``getMore`` responses with an empty ``nextBatch`` array, this does not indicate that the cursor has been exhausted.
+
+In addition to considering a cursor tailable, an ``awaitData`` flag may be sent on the initial command.
+This will request that the server block responding to the ``getMore`` immediately and instead rely on the ``maxTimeMS`` field of the ``getMore`` (or server default).
+If the time does expire an empty batch will be returned and the driver MUST issue another ``getMore``.
+
+It is up to the user to construct their initial command with ``awaitData`` and ``tailable`` flags as well as inform RunCursorCommand of the ``cursorType`` that should be constructed.
+Requesting a ``cursorType`` that does not align with the fields sent to the server on the initial command SHOULD be documented as undefined behavior.
+
+Resource Cleanup
+""""""""""""""""
+
+Drivers MUST provide an explicit mechanism for releasing the cursor resources, typically a ``.close()`` method.
+If the cursor id is nonzero a KillCursors operation MUST be attempted, the result of the operation SHOULD be ignored.
+The ClientSession associated with the cursor MUST be ended and the ServerSession returned to the pool.
+
+* See Driver Sessions' section on `When sending a killCursors command <https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst#when-sending-a-killcursors-command>`_
+* See Find, getMore and killCursors commands' section on `killCursors <https://github.com/mongodb/specifications/blob/master/source/find_getmore_killcursors_commands.rst#killcursors>`_
+
+Client Side Operations Timeout
+""""""""""""""""""""""""""""""
+
+As with RunCommand if the initial command has a ``maxTimeMS`` and CSOT settings are provided the behavior is undefined and drivers MUST NOT inspect the document to detect this.
+Drivers SHOULD not allow both a ``getMore`` ``maxTimeMS`` setting to be provided and CSOT settings.
+Drivers MUST document that attempting to set both can have undefined behavior and is not supported.
+
+When ``timeoutMS`` and ``timeoutMode`` are provided the driver MUST support timeout functionality as described in the CSOT specification.
+
+* See Client Side Operations Timeout's section on `Cursors <https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst#cursors>`_
+
 Changelog
 =========
 
+:2023-04-24: Add runCursorCommand API specification.
 :2023-04-20: Add run command specification.

source/run-command/tests/unified/runCursorCommand.json

@@ -0,0 +1,215 @@
+{
+  "description": "runCursorCommand",
+  "schemaVersion": "1.3",
+  "createEntities": [
+    {
+      "client": {
+        "id": "client",
+        "useMultipleMongoses": false,
+        "observeEvents": [
+          "commandStartedEvent"
+        ]
+      }
+    },
+    {
+      "database": {
+        "id": "db",
+        "client": "client",
+        "databaseName": "db"
+      }
+    },
+    {
+      "collection": {
+        "id": "collection",
+        "database": "db",
+        "collectionName": "collection"
+      }
+    }
+  ],
+  "initialData": [
+    {
+      "collectionName": "collection",
+      "databaseName": "db",
+      "documents": [
+        {
+          "_id": 1,
+          "x": 11
+        },
+        {
+          "_id": 2,
+          "x": 22
+        },
+        {
+          "_id": 3,
+          "x": 33
+        },
+        {
+          "_id": 4,
+          "x": 44
+        },
+        {
+          "_id": 5,
+          "x": 55
+        }
+      ]
+    }
+  ],
+  "tests": [
+    {
+      "description": "creates a cursor and iterates results from getMores",
+      "operations": [
+        {
+          "name": "runCursorCommand",
+          "object": "db",
+          "arguments": {
+            "commandName": "find",
+            "batchSize": 2,
+            "command": {
+              "find": "collection",
+              "filter": {},
+              "batchSize": 2
+            }
+          },
+          "expectResult": [
+            {
+              "_id": 1,
+              "x": 11
+            },
+            {
+              "_id": 2,
+              "x": 22
+            },
+            {
+              "_id": 3,
+              "x": 33
+            },
+            {
+              "_id": 4,
+              "x": 44
+            },
+            {
+              "_id": 5,
+              "x": 55
+            }
+          ]
+        }
+      ],
+      "expectEvents": [
+        {
+          "client": "client",
+          "events": [
+            {
+              "commandStartedEvent": {
+                "command": {
+                  "find": "collection",
+                  "filter": {},
+                  "batchSize": 2,
+                  "$db": "db",
+                  "lsid": {
+                    "id": {
+                      "$$type": "binData"
+                    }
+                  }
+                },
+                "commandName": "find"
+              }
+            },
+            {
+              "commandStartedEvent": {
+                "command": {
+                  "getMore": {
+                    "$$type": "long"
+                  },
+                  "collection": "collection",
+                  "$db": "db",
+                  "lsid": {
+                    "id": {
+                      "$$type": "binData"
+                    }
+                  }
+                },
+                "commandName": "getMore"
+              }
+            },
+            {
+              "commandStartedEvent": {
+                "command": {
+                  "getMore": {
+                    "$$type": "long"
+                  },
+                  "collection": "collection",
+                  "$db": "db",
+                  "lsid": {
+                    "id": {
+                      "$$type": "binData"
+                    }
+                  }
+                },
+                "commandName": "getMore"
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "description": "creates a cursor and iterates one result",
+      "operations": [
+        {
+          "name": "createRunCursorCommand",
+          "object": "db",
+          "arguments": {
+            "commandName": "find",
+            "batchSize": 2,
+            "command": {
+              "find": "collection",
+              "filter": {},
+              "batchSize": 2
+            }
+          },
+          "saveResultAsEntity": "myRunCommandCursor"
+        },
+        {
+          "name": "iterateUntilDocumentOrError",
+          "object": "myRunCommandCursor",
+          "expectResult": {
+            "_id": 1,
+            "x": 11
+          }
+        },
+        {
+          "name": "iterateUntilDocumentOrError",
+          "object": "myRunCommandCursor",
+          "expectResult": {
+            "_id": 2,
+            "x": 22
+          }
+        },
+        {
+          "name": "iterateUntilDocumentOrError",
+          "object": "myRunCommandCursor",
+          "expectResult": {
+            "_id": 3,
+            "x": 33
+          }
+        },
+        {
+          "name": "iterateUntilDocumentOrError",
+          "object": "myRunCommandCursor",
+          "expectResult": {
+            "_id": 4,
+            "x": 44
+          }
+        },
+        {
+          "name": "iterateUntilDocumentOrError",
+          "object": "myRunCommandCursor",
+          "expectResult": {
+            "_id": 5,
+            "x": 55
+          }
+        }
+      ]
+    }
+  ]
+}