[DOCS-14397] Investigate changes in SERVER-55614: Require passing Versioned API options to getMore and transaction-continuing commands Created: 30/Apr/21  Updated: 13/Nov/23  Due: 21/May/21  Resolved: 20/May/21

Status: Closed
Project: Documentation
Component/s: manual, Server
Affects Version/s: None
Fix Version/s: 5.0.0-rc0, Server_Docs_20231030, Server_Docs_20231106, Server_Docs_20231105, Server_Docs_20231113

Type: Task Priority: Major - P3
Reporter: Backlog - Core Eng Program Management Team Assignee: Joseph Dougherty
Resolution: Won't Do Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Documented
documents SERVER-55614 Permit Versioned API options for getM... Closed
Duplicate
is duplicated by DOCS-14459 Investigate changes in SERVER-56550: ... Closed
Participants:
Days since reply: 2 years, 37 weeks, 6 days ago
Epic Link: DOCSP-14217
Story Points: 2

 Description   

Description

Downstream Change Summary

This ticket will make API parameters optional for getMore and transaction-continuing commands. Any user of the stable API needs to include API version parameters for those commands before the server can make the parameters required.

Description of Linked Ticket

The Versioned API design requires drivers and users to omit Versioned API parameters in the following two instances:
1. When calling getMore
2. In any command that is part of a transaction, except for the command starting the transaction.

The reason for not allowing them on getMore calls is that it's bound to the API Version declared when creating the cursor. For transactions, the entire transaction operates under the same declared API Version, so later commands should not be able to override this.

While this approach makes sense, it creates unnecessary workload in drivers. Drivers have to inspect command documents to know whether they should append Versioned API options for this instance. This can have a performance impact for drivers that already have raw BSON documents at this point.

To fix this, Drivers and users should be required to include API versioning options for getMore and transaction-continuing commands, with the server emitting a command error if there is an API Version mismatch (exact comparison, e.g. apiVersion, apiStrict, and apiDeprecationErrors match).

To aid with the transition to this new requirement, the options should be optional at first and can become required options once all drivers have updated their logic to always include these options.

Scope of changes

Impact to Other Docs

MVP (Work and Date)

Resources (Scope or Design Docs, Invision, etc.)



 Comments   
Comment by Joseph Dougherty [ 20/May/21 ]

Closing this one as drivers handle it correctly (DRIVERS-1720) and we don't expect users to execute getMore themselves. 

Comment by Joseph Dougherty [ 20/May/21 ]

jesse Thanks for the clarification! It's much appreciated. Closing this one out.

Comment by A. Jesse Jiryu Davis [ 20/May/21 ]

I think in your latter example, since you started the shell with --apiVersion 1, the shell is including apiVersion on your behalf. MongoDB v5.0.0-alpha0-506-gbddc8a8 does require API args in getMore/transaction-continuing commands if they were passed in the cursor/transaction-initiating command.

In any case, this is a great example of a protocol detail we should not distract users with. The drivers handle it correctly (DRIVERS-1720) and we don't expect users to execute getMore themselves. Users should use the shell or driver to iterate cursors. I recommend closing this ticket and doing nothing. Or, if you've already documented the previous behavior (getMore and transaction-continuing commands used to ban API params) then let's remove that documentation, since it's protocol details.

Comment by Joseph Dougherty [ 20/May/21 ]

jesse Should we direct users to specify API-related args manually?

I notice that both of these commands work when running against v5.0.0-alpha0-506-gbddc8a8 (Assume we have a cursor, c, where c.IsClosed() == false.)

Specifying API-related args: 

// Connected with --apiVersion 1
db.runCommand( { "getMore": c.getId(), "collection": "inventory", apiVersion: "1" } )

  

Omitting API-related args:

// Connected with --apiVersion 1
db.runCommand( { "getMore": c.getId(), "collection": "inventory", } ) 

The issue description suggests "Drivers and users should be required to include API versioning options for getMore [...]"

Also: "the options should be optional at first and can become required options once all drivers have updated their logic to always include these options."

Are these optional in v5.0.0-alpha0-506-gbddc8a8, but will be required later? Or are these args that are passed along implicitly?

Could you help clarify if we do, in fact, want users to specify API-related args explicitly?

Thank you!

 

 

Generated at Thu Feb 08 08:10:18 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.