GODRIVER-2347 Further deprecate timeout options and clarify RunCommand behavior. (#982)

Author: benjirewis

mongo/database.go

@@ -185,11 +185,13 @@ func (db *Database) processRunCommand(ctx context.Context, cmd interface{},
 //
 // The runCommand parameter must be a document for the command to be executed. It cannot be nil.
 // This must be an order-preserving type such as bson.D. Map types such as bson.M are not valid.
-// If the command document contains a session ID or any transaction-specific fields, the behavior is undefined.
-// Specifying API versioning options in the command document and declaring an API version on the client is not supported.
-// The behavior of RunCommand is undefined in this case.
 //
 // The opts parameter can be used to specify options for this operation (see the options.RunCmdOptions documentation).
+//
+// The behavior of RunCommand is undefined if the command document contains any of the following:
+// - A session ID or any transaction-specific fields
+// - API versioning options when an API version is already declared on the Client
+// - maxTimeMS when Timeout is set on the Client
 func (db *Database) RunCommand(ctx context.Context, runCommand interface{}, opts ...*options.RunCmdOptions) *SingleResult {
 	if ctx == nil {
 		ctx = context.Background()
@@ -218,9 +220,13 @@ func (db *Database) RunCommand(ctx context.Context, runCommand interface{}, opts
 //
 // The runCommand parameter must be a document for the command to be executed. It cannot be nil.
 // This must be an order-preserving type such as bson.D. Map types such as bson.M are not valid.
-// If the command document contains a session ID or any transaction-specific fields, the behavior is undefined.
 //
 // The opts parameter can be used to specify options for this operation (see the options.RunCmdOptions documentation).
+//
+// The behavior of RunCommandCursor is undefined if the command document contains any of the following:
+// - A session ID or any transaction-specific fields
+// - API versioning options when an API version is already declared on the Client
+// - maxTimeMS when Timeout is set on the Client
 func (db *Database) RunCommandCursor(ctx context.Context, runCommand interface{}, opts ...*options.RunCmdOptions) (*Cursor, error) {
 	if ctx == nil {
 		ctx = context.Background()

mongo/options/aggregateoptions.go

@@ -34,6 +34,10 @@ type AggregateOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the Aggregate operation can run before
+	// returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 
 	// The maximum amount of time that the server should wait for new documents to satisfy a tailable cursor query.
@@ -91,6 +95,10 @@ func (ao *AggregateOptions) SetCollation(c *Collation) *AggregateOptions {
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver.
+// The more general Timeout option should be used in its place to control the amount of time that the
+// Aggregate operation can run before returning an error.
 func (ao *AggregateOptions) SetMaxTime(d time.Duration) *AggregateOptions {
 	ao.MaxTime = &d
 	return ao

mongo/options/clientoptions.go

@@ -724,11 +724,15 @@ func (c *ClientOptions) SetSocketTimeout(d time.Duration) *ClientOptions {
 }
 
 // SetTimeout specifies the amount of time that a single operation run on this Client can execute before returning an error.
-// This can also be set through the "timeoutMS" URI option (e.g. "timeoutMS=1000"). The default value is nil, meaning operations
-// do not inherit a timeout from the Client.
+// The deadline of any operation run through the Client will be honored above any Timeout set on the Client; Timeout will only
+// be honored if there is no deadline on the operation Context. Timeout can also be set through the "timeoutMS" URI option
+// (e.g. "timeoutMS=1000"). The default value is nil, meaning operations do not inherit a timeout from the Client.
 //
-// If any Timeout is set (even 0) on the Client, the values of other, deprecated timeout-related options will be ignored. In particular:
-// ClientOptions.SocketTimeout, WriteConcern.wTimeout, MaxTime on operations, and TransactionOptions.MaxCommitTime.
+// If any Timeout is set (even 0) on the Client, the values of other, deprecated timeout-related options will be ignored.
+// In particular: ClientOptions.SocketTimeout, WriteConcern.wTimeout, MaxTime on operations, and TransactionOptions.MaxCommitTime.
+//
+// NOTE(benjirewis): SetTimeout represents unstable, provisional API. The behavior of the driver when a Timeout is specified is
+// subject to change.
 func (c *ClientOptions) SetTimeout(d time.Duration) *ClientOptions {
 	c.Timeout = &d
 	return c

mongo/options/countoptions.go

@@ -33,6 +33,10 @@ type CountOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there is
 	// no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the count operation can run before
+	// returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 
 	// The number of documents to skip before counting. The default value is 0.
@@ -69,6 +73,10 @@ func (co *CountOptions) SetLimit(i int64) *CountOptions {
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the count operation can run before
+// returning an error.
 func (co *CountOptions) SetMaxTime(d time.Duration) *CountOptions {
 	co.MaxTime = &d
 	return co

mongo/options/distinctoptions.go

@@ -17,6 +17,10 @@ type DistinctOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the Distinct operation can run before
+	// returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 }
 
@@ -32,6 +36,10 @@ func (do *DistinctOptions) SetCollation(c *Collation) *DistinctOptions {
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the Distinct operation can run before
+// returning an error.
 func (do *DistinctOptions) SetMaxTime(d time.Duration) *DistinctOptions {
 	do.MaxTime = &d
 	return do

mongo/options/estimatedcountoptions.go

@@ -16,6 +16,10 @@ type EstimatedDocumentCountOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the EstimatedDocumentCount operation
+	// can run before returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 }
 
@@ -31,6 +35,10 @@ func (eco *EstimatedDocumentCountOptions) SetComment(comment interface{}) *Estim
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the EstimatedDocumentCount operation
+// can run before returning an error.
 func (eco *EstimatedDocumentCountOptions) SetMaxTime(d time.Duration) *EstimatedDocumentCountOptions {
 	eco.MaxTime = &d
 	return eco

mongo/options/findoptions.go

@@ -55,10 +55,6 @@ type FindOptions struct {
 	// MaxAwaitTime is the maximum amount of time that the server should wait for new documents to satisfy a tailable cursor
 	// query. This option is only valid for tailable await cursors (see the CursorType option for more information) and
 	// MongoDB versions >= 3.2. For other cursor types or previous server versions, this option is ignored.
-	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the Find operation can run before
-	// returning an error. MaxAwaitTime is still usable through the deprecated setter.
 	MaxAwaitTime *time.Duration
 
 	// MaxTime is the maximum amount of time that the query can run on the server. The default value is nil, meaning that there
@@ -181,10 +177,6 @@ func (f *FindOptions) SetMax(max interface{}) *FindOptions {
 }
 
 // SetMaxAwaitTime sets the value for the MaxAwaitTime field.
-//
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver.
-// The more general Timeout option should be used in its place to control the amount of time that the
-// Find operation can run before returning an error.
 func (f *FindOptions) SetMaxAwaitTime(d time.Duration) *FindOptions {
 	f.MaxAwaitTime = &d
 	return f
@@ -377,6 +369,10 @@ type FindOneOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the FindOne operation can run before
+	// returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 
 	// A document specifying the inclusive lower bound for a specific index. The default value is 0, which means that
@@ -481,6 +477,10 @@ func (f *FindOneOptions) SetMaxAwaitTime(d time.Duration) *FindOneOptions {
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the FindOne operation can run before
+// returning an error.
 func (f *FindOneOptions) SetMaxTime(d time.Duration) *FindOneOptions {
 	f.MaxTime = &d
 	return f
@@ -633,6 +633,10 @@ type FindOneAndReplaceOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the FindOneAndReplace operation can
+	// run before returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 
 	// A document describing which fields will be included in the document returned by the operation. The default value
@@ -691,6 +695,10 @@ func (f *FindOneAndReplaceOptions) SetComment(comment interface{}) *FindOneAndRe
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the FindOneAndReplace operation can
+// run before returning an error.
 func (f *FindOneAndReplaceOptions) SetMaxTime(d time.Duration) *FindOneAndReplaceOptions {
 	f.MaxTime = &d
 	return f
@@ -799,6 +807,10 @@ type FindOneAndUpdateOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the FindOneAndUpdate operation can run
+	// before returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 
 	// A document describing which fields will be included in the document returned by the operation. The default value
@@ -863,6 +875,10 @@ func (f *FindOneAndUpdateOptions) SetComment(comment interface{}) *FindOneAndUpd
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the FindOneAndUpdate operation can run
+// before returning an error.
 func (f *FindOneAndUpdateOptions) SetMaxTime(d time.Duration) *FindOneAndUpdateOptions {
 	f.MaxTime = &d
 	return f
@@ -963,6 +979,10 @@ type FindOneAndDeleteOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the FindOneAndDelete operation can run
+	// before returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 
 	// A document describing which fields will be included in the document returned by the operation. The default value
@@ -1007,6 +1027,10 @@ func (f *FindOneAndDeleteOptions) SetComment(comment interface{}) *FindOneAndDel
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the FindOneAndDelete operation can run
+// before returning an error.
 func (f *FindOneAndDeleteOptions) SetMaxTime(d time.Duration) *FindOneAndDeleteOptions {
 	f.MaxTime = &d
 	return f

mongo/options/gridfsoptions.go

@@ -225,6 +225,10 @@ type GridFSFindOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that GridFS operations can run before
+	// returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 
 	// If true, the cursor created by the operation will not timeout after a period of inactivity. The default value
@@ -263,6 +267,10 @@ func (f *GridFSFindOptions) SetLimit(i int32) *GridFSFindOptions {
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver.
+// The more general Timeout option should be used in its place to control the amount of time that
+// GridFS operations can run before returning an error.
 func (f *GridFSFindOptions) SetMaxTime(d time.Duration) *GridFSFindOptions {
 	f.MaxTime = &d
 	return f

mongo/options/indexoptions.go

@@ -29,6 +29,10 @@ type CreateIndexesOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the create index operation can run before
+	// returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 }
 
@@ -38,6 +42,10 @@ func CreateIndexes() *CreateIndexesOptions {
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the create index operation can run before
+// returning an error.
 func (c *CreateIndexesOptions) SetMaxTime(d time.Duration) *CreateIndexesOptions {
 	c.MaxTime = &d
 	return c
@@ -91,6 +99,10 @@ func MergeCreateIndexesOptions(opts ...*CreateIndexesOptions) *CreateIndexesOpti
 type DropIndexesOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the drop index operation can run before
+	// returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 }
 
@@ -100,6 +112,10 @@ func DropIndexes() *DropIndexesOptions {
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the drop index operation can run before
+// returning an error.
 func (d *DropIndexesOptions) SetMaxTime(duration time.Duration) *DropIndexesOptions {
 	d.MaxTime = &duration
 	return d
@@ -128,6 +144,10 @@ type ListIndexesOptions struct {
 
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
+	//
+	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+	// Timeout option should be used in its place to control the amount of time that the List operation can run before
+	// returning an error. MaxTime is still usable through the deprecated setter.
 	MaxTime *time.Duration
 }
 
@@ -143,6 +163,10 @@ func (l *ListIndexesOptions) SetBatchSize(i int32) *ListIndexesOptions {
 }
 
 // SetMaxTime sets the value for the MaxTime field.
+//
+// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
+// Timeout option should be used in its place to control the amount of time that the List operation can run before
+// returning an error.
 func (l *ListIndexesOptions) SetMaxTime(d time.Duration) *ListIndexesOptions {
 	l.MaxTime = &d
 	return l