[CDRIVER-1527] Add mongoc_client_[read|write|read_write]_command_with_opts Created: 07/Sep/16  Updated: 15/Nov/17  Resolved: 20/Oct/16

Status: Closed
Project: C Driver
Component/s: libmongoc
Affects Version/s: None
Fix Version/s: 1.5.0

Type: New Feature Priority: Major - P3
Reporter: A. Jesse Jiryu Davis Assignee: Backlog - C Driver Team
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by CXX-927 Support sending writeConcern for comm... Closed
is depended on by CXX-971 Support providing collation per opera... Closed
is depended on by PHPC-834 Add Read, ReadWrite, and Write comman... Closed
is depended on by CDRIVER-1005 Improve wire version checks Backlog
Related
related to CDRIVER-2207 Introduce generic mongoc_client_comma... Closed
related to CDRIVER-1537 Audit _mongoc_cursor_new's read prefs... Closed
is related to CDRIVER-1551 Collation: Raise error for command he... Closed
is related to CDRIVER-329 add distinct helper to mongoc_collect... Closed
Epic Link: Flexible opts

 Description   

*Update*: the API proposed below was not what we implemented. See the first linked commit for an overview of the actual API.

Currently we have mongoc_client_command and mongoc_client_command_simple (and equivalents for database and collection). These functions are "generic command methods" and follow driver specs that require they do no special handling of writeConcern, readConcern, or collation. They don't obey the read preference set on the client, database, or collection object. They don't parse writeConcernError from the server reply. This matches various specs that say things like:

The generic command method MUST NOT check the user's command document for a WriteConcern nor check whether the server is new enough to support a write concern for the command. The method simply sends the user's command to the server as-is.

If your driver offers a generic RunCommand method on your database object, ReadConcern MUST NOT be applied automatically to any command. A user wishing to use a ReadConcern in a generic command must supply it manually.

And in the Server Selection Spec:

The generic command method MUST ignore any default read preference from client, database or collection configuration. The generic command method SHOULD allow an optional read preference argument.

The relevant specs are Read and Write Concern, Collation, and Server Selection.

HLL drivers built on the C Driver can take advantage of our implementation of driver specs when the HLL drivers call our command-specific helper functions. E.g., when the PHP driver calls mongoc_collection_aggregate_with_opts (CDRIVER-1526), the C Driver selects a server for the operation, ensures it has a connection, and then applies server version checks for writeConcern, readConcern, and collation (CDRIVER-1551). It parses the reply for writeConcernError.

Implementing this special logic in the C Driver gives us two benefits: it consolidates logic in the C Driver so it need not be reimplemented in HLL drivers, and it executes the logic after selecting a server and verifying we have an open connection to it, which eliminates all race conditions during server upgrades.

However, to keep taking advantage of these two benefits for all future commands and features, we have to keep adding helper functions with names like mongoc_client_do_new_command_with_opts.

I propose a function that can execute any command, but applies special rules for writeConcern, readConcern, and collation, and all future options with special behavior:

bool
mongoc_client_command_with_opts (mongoc_client_t           *client,
                                 const char                *db_name,
                                 const bson_t              *command,
                                 const mongoc_read_prefs_t *read_prefs,
                                 const bson_t              *opts,
                                 bson_t                    *reply,
                                 bson_error_t              *error);

We'll also add equivalents at the database and collection level: mongoc_database_command_with_opts and mongoc_collection_command_with_opts.

Each of these functions:

In the future this will be our "porcelain" command helper for future specs that require special handling of options. mongoc_client_command_simple and other generic command functions remain "plumbing" with no special handling.



 Comments   
Comment by Githook User [ 22/Oct/16 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1527 git ignore example-command-with-opts
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/972e3970d30d05a2cf4909075cc5125f0ff49049

Comment by Githook User [ 20/Oct/16 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1527 don't call "insert" etc. with mongoc_client_write_command_with_opts
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/0ca49ad05074950f128192f4e5866f325cb6819a

Comment by Githook User [ 20/Oct/16 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1527 whitespace in command func docs
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/b9b66212cad92e2f45906ee8ae7a1797575a2c40

Comment by Githook User [ 19/Oct/16 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1527 new command funcs with bson_t opts
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/3e34af30faca57e014044e0a3b7ca8f3460991df

Comment by A. Jesse Jiryu Davis [ 18/Oct/16 ]

I hadn't been thinking about cursor commands, but that's a good point. I suppose that's an intended use case: CDRIVER-1842

I always forget that the PHP driver let users select servers and run operations in distinct steps. We have to support that: CDRIVER-1844

Comment by Jeremy Mikola [ 17/Oct/16 ]

Are the new "with_opts" functions (i.e. read, read_write, and write) intended to be used for commands that return a cursor? I realize that they return a single result document, but I found no examples for using these in conjunction with something like aggregation or listCollections. Perhaps the PR should include an example using mongoc_cursor_new_from_command_reply().

Second question: will these new functions allow consumers to specify their own hint for server selection, or does this API require libmongoc to perform internal server selection? PHPC and HHVM won't be able to use this API without a configurable hint, since we already provide APIs for executing commands on pre-selected servers.

Comment by A. Jesse Jiryu Davis [ 29/Sep/16 ]

After re-reading DRIVERS-250 and the PyMongo source I realize that mongoc_database_command_with_opts should do nothing special with bypassDocumentValidation.

Generated at Wed Feb 07 21:12:48 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.