[GODRIVER-3060] Investigate updating documentation for CommitTransaction Created: 27/Nov/23  Updated: 06/Dec/23  Resolved: 04/Dec/23

Status: Closed
Project: Go Driver
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Unknown
Reporter: Preston Vasquez Assignee: Unassigned
Resolution: Won't Do Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to GODRIVER-2997 WithTransaction completes despite a c... Closed
Documentation Changes Summary:

1. What would you like to communicate to the user about this feature?
2. Would you like the user to see examples of the syntax and/or executable code and its output?
3. Which versions of the driver/connector does this apply to?


 Description   

Context

GODRIVER-2997 describes an issue where if a user passes a cancelable context into WithTransaction and cancels mid-transaction, then the transaction still completes. It is noted in in the documentation for WithTransaction that we do not honor cancelations:

Because this method must succeed to ensure that server-side resources are properly cleaned up, context deadlines and cancellations will not be respected during this call.

The underlying method that causes this issue is CommitTransaction. Perhaps the documentation for this method should include the context limitations.

Definition of done

The following questions should be answered and documented:

1. Can you cancel a context while committing a transaction? If yes, what is the difference between doing that and using WithTransaction, which is a convenience wrapper for CommitTransaction.
2. If you can't use the functionality of a context on CommitTransaction and WithTransaction, what is the purpose of passing a context to these methods?

What must be done to consider the task complete?

Pitfalls

What should the implementer watch out for? What are the risks?



 Comments   
Comment by Preston Vasquez [ 06/Dec/23 ]

rushil.kumar@mongodb.com The documentation for this should be drivers-wide, not specific to the Go Driver. You can cancel a context while committing a transaction, since reading the server response is context-oriented it's possible that a commit operation is successful but you still get an error on cancelation / timeout. When this occurs, you should just retry the transaction.

I've created https://jira.mongodb.org/browse/DOCSP-34822 for the team to make this more clear at a documentation level.

Comment by Rushil Kumar [ 06/Dec/23 ]

I am bit unclear on why this ticket was closed out. I don't think the questions in the ticket description were answered yet.

Comment by KeAna Moutra [ 04/Dec/23 ]

The addition of this comment (in thread) suggests that we want users to avoid doing something we allow them to do.

Comment by Rushil Kumar [ 27/Nov/23 ]

In addition, maybe it is worth updating the documentation for WithTransaction to indicate a cancellable-context can be passed in since it now wraps the passed in context with a background context?

https://pkg.go.dev/go.mongodb.org/mongo-driver/mongo#Session

Because this method must succeed to ensure that server-side resources are
// properly cleaned up, context deadlines and cancellations will not be respected during this
// call

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