Skip to content

Commit ab66eaf

Browse files
nbbeekenjmikoladurran
authored
DRIVERS-2577: add a runCommand specification (#1389)
Co-authored-by: Jeremy Mikola <[email protected]> Co-authored-by: Durran Jordan <[email protected]>
1 parent 1f272b3 commit ab66eaf

File tree

5 files changed

+905
-6
lines changed

5 files changed

+905
-6
lines changed

‎source/run-command/run-command.rst

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
===========
2+
Run Command
3+
===========
4+
5+
:Status: Accepted
6+
:Minimum Server Version: N/A
7+
8+
.. contents::
9+
10+
--------
11+
12+
Abstract
13+
========
14+
This specification defines requirements and behaviors for drivers' run command and related APIs.
15+
16+
17+
META
18+
====
19+
20+
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
21+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
22+
document are to be interpreted as described in `RFC 2119
23+
<https://www.ietf.org/rfc/rfc2119.txt>`_.
24+
25+
Specification
26+
=============
27+
28+
-----
29+
Terms
30+
-----
31+
Command
32+
A structure representing a BSON document that has a shape matching a supported MongoDB operation.
33+
34+
---------------------------
35+
Implementation requirements
36+
---------------------------
37+
38+
All drivers MAY offer the operations defined in the following sections.
39+
This does not preclude a driver from offering more.
40+
41+
----------
42+
Deviations
43+
----------
44+
45+
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.
46+
47+
--------------
48+
``runCommand``
49+
--------------
50+
51+
The following represents how a runCommand API SHOULD be exposed.
52+
53+
.. code:: typescript
54+
55+
interface Database {
56+
/**
57+
* Takes an argument representing an arbitrary BSON document and executes it against the server.
58+
*/
59+
runCommand(command: BSONDocument, options: RunCommandOptions): BSONDocument;
60+
}
61+
62+
interface RunCommandOptions {
63+
/**
64+
* An optional readPreference setting to apply to server selection logic.
65+
* This value MUST be applied to the command document as the $readPreference global command argument if not set to primary.
66+
*
67+
* @defaultValue ReadPreference(mode: primary)
68+
*
69+
* @see https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#read-preference
70+
*/
71+
readPreference?: ReadPreference;
72+
73+
/**
74+
* An optional explicit client session.
75+
* The associated logical session id (`lsid`) the driver MUST apply to the command.
76+
*
77+
* @see https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst#clientsession
78+
*/
79+
session?: ClientSession;
80+
81+
/**
82+
* An optional timeout option to govern the amount of time that a single operation can execute before control is returned to the user.
83+
* This timeout applies to all of the work done to execute the operation, including but not limited to server selection, connection checkout, and server-side execution.
84+
*
85+
* @ see https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst
86+
*/
87+
timeoutMS?: number;
88+
}
89+
90+
RunCommand implementation details
91+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
92+
93+
RunCommand provides a way to access MongoDB server commands directly without requiring a driver to implement a bespoke helper.
94+
The API is intended to take a document from a user and apply a number of common driver internal concerns before forwarding the command to a server.
95+
A driver MUST not inspect the user's command, this includes checking for the fields a driver MUST attach to the command sent as described below.
96+
Depending on a driver's BSON implementation this can result in these fields being overwritten or duplicated, a driver SHOULD document that using these fields has undefined behavior.
97+
A driver MUST not modify the user's command, a clone SHOULD be created before the driver attaches any of the required fields to the command.
98+
99+
Drivers that have historically modified user input SHOULD strive to instead clone the input such that appended fields do not affect the user's input in their next major version.
100+
101+
OP_MSG
102+
""""""
103+
104+
The ``$db`` global command argument MUST be set on the command sent to the server and it MUST equal the database name RunCommand was invoked on.
105+
106+
* See OP_MSG's section on `Global Command Arguments <https://github.com/mongodb/specifications/blob/master/source/message/OP_MSG.rst#global-command-arguments>`_
107+
108+
ReadPreference
109+
""""""""""""""
110+
111+
For the purposes of server selection RunCommand MUST assume all commands are read operations.
112+
To facilitate server selection the RunCommand operation MUST accept an optional ``readPreference`` option.
113+
114+
* See Server Selection's section on `Use of read preferences with commands <https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#use-of-read-preferences-with-commands>`_
115+
116+
If the provided ReadPreference is NOT ``{mode: primary}``, the command sent MUST include the ``$readPreference`` global command argument.
117+
118+
* See OP_MSG's section on `Global Command Arguments <https://github.com/mongodb/specifications/blob/master/source/message/OP_MSG.rst#global-command-arguments>`_
119+
120+
Driver Sessions
121+
"""""""""""""""
122+
123+
A driver's RunCommand MUST provide an optional session option to support explicit sessions and transactions.
124+
If a session is not provided the driver MUST attach an implicit session if the connection supports sessions.
125+
Drivers MUST NOT attempt to check the command document for the presence of an ``lsid``.
126+
127+
Every ClientSession has a corresponding logical session ID representing the server-side session ID.
128+
The logical session ID MUST be included under ``lsid`` in the command sent to the server without modifying user input.
129+
130+
* 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>`_
131+
132+
Transactions
133+
""""""""""""
134+
135+
If RunCommand is used within a transaction the read preference MUST be sourced from the transaction's options.
136+
The command sent to the server MUST include the transaction specific fields, summarized as follows:
137+
138+
* If ``runCommand`` is executing within a transaction:
139+
140+
* ``autocommit`` - The autocommit flag MUST be set to false.
141+
* ``txnNumber`` - MUST be set.
142+
143+
* If ``runCommand`` is the first operation of the transaction:
144+
145+
* ``startTransaction`` - MUST be set to true.
146+
* ``readConcern`` - MUST be set to the transaction's read concern if it is NOT the default.
147+
148+
* See `Generic RunCommand helper within a transaction <https://github.com/mongodb/specifications/blob/master/source/transactions/transactions.rst#generic-runcommand-helper-within-a-transaction>`_ in the Transactions specification.
149+
150+
ReadConcern and WriteConcern
151+
""""""""""""""""""""""""""""
152+
153+
RunCommand MUST NOT support read concern and write concern options.
154+
Drivers MUST NOT attempt to check the command document for the presence of a ``readConcern`` and ``writeConcern`` field.
155+
156+
Additionally, unless executing within a transaction, RunCommand MUST NOT set the ``readConcern`` or ``writeConcern`` fields in the command document.
157+
For example, default values MUST NOT be inherited from client, database, or collection options.
158+
159+
If the user-provided command document already includes ``readConcern`` or ``writeConcern`` fields, the values MUST be left as-is.
160+
161+
* See Read Concern's section on `Generic Command Method <https://github.com/mongodb/specifications/blob/master/source/read-write-concern/read-write-concern.rst#generic-command-method>`_
162+
* See Write Concern's section on `Generic Command Method <https://github.com/mongodb/specifications/blob/master/source/read-write-concern/read-write-concern.rst#generic-command-method-1>`_
163+
164+
Retryability
165+
""""""""""""
166+
167+
All commands executed via RunCommand are non-retryable operations.
168+
Drivers MUST NOT inspect the command to determine if it is a write and MUST NOT attach a ``txnNumber``.
169+
170+
* See Retryable Reads' section on `Unsupported Read Operations <https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.rst#unsupported-read-operations>`_
171+
* See Retryable Writes' section on `Behavioral Changes for Write Commands <https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst#behavioral-changes-for-write-commands>`_
172+
173+
Stable API
174+
""""""""""
175+
176+
The command sent MUST attach stable API fields as configured on the MongoClient.
177+
178+
* See Stable API's section on `Generic Command Helper Behaviour <https://github.com/mongodb/specifications/blob/master/source/versioned-api/versioned-api.rst#generic-command-helper>`_
179+
180+
Client Side Operations Timeout
181+
""""""""""""""""""""""""""""""
182+
183+
RunCommand MUST provide an optional ``timeoutMS`` option to support client side operations timeout.
184+
Drivers MUST NOT attempt to check the command document for the presence of a ``maxTimeMS`` field.
185+
Drivers MUST document the behavior of RunCommand if a ``maxTimeMS`` field is already set on the command (such as overwriting the command field).
186+
187+
* 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>`_
188+
* 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>`_
189+
190+
Changelog
191+
=========
192+
193+
:2023-04-20: Add run command specification.

‎source/run-command/tests/README.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
=================
2+
Run Command Tests
3+
=================
4+
5+
.. contents::
6+
7+
----
8+
9+
Introduction
10+
============
11+
12+
The YAML and JSON files in the ``unified`` sub-directories are platform-independent tests
13+
that drivers can use to prove their conformance to the RunCommand spec. Tests in the
14+
``unified`` directory are written using the `Unified Test Format <../../unified-test-format/unified-test-format.rst>`_.

0 commit comments

Comments
 (0)