GODRIVER-1380 Document Session and provide GoDoc examples (#227)

Author: Divjot Arora

mongo/client.go

@@ -237,6 +237,9 @@ func (c *Client) Ping(ctx context.Context, rp *readpref.ReadPref) error {
 }
 
 // StartSession starts a new session configured with the given options.
+//
+// If the DefaultReadConcern, DefaultWriteConcern, or DefaultReadPreference options are not set, the client's read
+// concern, write concern, or read preference will be used, respectively.
 func (c *Client) StartSession(opts ...*options.SessionOptions) (Session, error) {
 	if c.sessionPool == nil {
 		return nil, ErrClientDisconnected
@@ -734,38 +737,30 @@ func (c *Client) ListDatabaseNames(ctx context.Context, filter interface{}, opts
 	return names, nil
 }
 
-// WithSession allows a user to start a session themselves and manage
-// its lifetime. The only way to provide a session to a CRUD method is
-// to invoke that CRUD method with the mongo.SessionContext within the
-// closure. The mongo.SessionContext can be used as a regular context,
-// so methods like context.WithDeadline and context.WithTimeout are
-// supported.
+// WithSession creates a new SessionContext from the ctx and sess parameters and uses it to call the fn callback. The
+// SessionContext must be used as the Context parameter for any operations in the fn callback that should be executed
+// under the session.
 //
-// If the context.Context already has a mongo.Session attached, that
-// mongo.Session will be replaced with the one provided.
+// If the ctx parameter already contains a Session, that Session will be replaced with the one provided.
 //
-// Errors returned from the closure are transparently returned from
-// this function.
+// Any error returned by the fn callback will be returned without any modifications.
 func WithSession(ctx context.Context, sess Session, fn func(SessionContext) error) error {
 	return fn(contextWithSession(ctx, sess))
 }
 
-// UseSession creates a new session that is only valid for the
-// lifetime of the fn callback. No cleanup outside of closing the session
-// is done upon exiting the closure. This means that an outstanding
-// transaction will be aborted, even if the closure returns an error.
+// UseSession creates a new Session and uses it to create a new SessionContext, which is used to call the fn callback.
+// The SessionContext parameter must be used as the Context parameter for any operations in the fn callback that should
+// be executed under a session. After the callback returns, the created Session is ended, meaning that any in-progress
+// transactions started by fn will be aborted even if fn returns an error.
 //
-// If ctx already contains a mongo.Session, that mongo.Session will be
-// replaced with the newly created one.
+// If the ctx parameter already contains a Session, that Session will be replaced with the newly created one.
 //
-// Errors returned from the closure are transparently returned from
-// this method.
+// Any error returned by the fn callback will be returned without any modifications.
 func (c *Client) UseSession(ctx context.Context, fn func(SessionContext) error) error {
 	return c.UseSessionWithOptions(ctx, options.Session(), fn)
 }
 
-// UseSessionWithOptions works like UseSession but allows the caller
-// to specify the options used to create the session.
+// UseSessionWithOptions operates like UseSession but uses the given SessionOptions to create the Session.
 func (c *Client) UseSessionWithOptions(ctx context.Context, opts *options.SessionOptions, fn func(SessionContext) error) error {
 	defaultSess, err := c.StartSession(opts)
 	if err != nil {

mongo/crud_examples_test.go

@@ -16,6 +16,7 @@ import (
 	"go.mongodb.org/mongo-driver/bson/primitive"
 	"go.mongodb.org/mongo-driver/mongo"
 	"go.mongodb.org/mongo-driver/mongo/options"
+	"go.mongodb.org/mongo-driver/mongo/readconcern"
 	"go.mongodb.org/mongo-driver/mongo/readpref"
 )
 
@@ -451,3 +452,107 @@ func ExampleCollection_Watch() {
 		fmt.Println(changeStream.Current)
 	}
 }
+
+// Session examples
+
+func ExampleWithSession() {
+	var client *mongo.Client // assume client is configured with write concern majority and read preference primary
+
+	// Specify the DefaultReadConcern option so any transactions started through the session will have read concern
+	// majority.
+	// The DefaultReadPreference and DefaultWriteConcern options aren't specified so they will be inheritied from client
+	// and be set to primary and majority, respectively.
+	opts := options.Session().SetDefaultReadConcern(readconcern.Majority())
+	sess, err := client.StartSession(opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer sess.EndSession(context.TODO())
+
+	// Call WithSession to use the new Session to insert a document and find it.
+	err = mongo.WithSession(context.TODO(), sess, func(sessCtx mongo.SessionContext) error {
+		// Use sessCtx as the Context parameter for InsertOne and FindOne so both operations are run under the new
+		// Session.
+
+		coll := client.Database("db").Collection("coll")
+		res, err := coll.InsertOne(sessCtx, bson.D{{"x", 1}})
+		if err != nil {
+			return err
+		}
+
+		var result bson.M
+		if err = coll.FindOne(sessCtx, bson.D{{"_id", res.InsertedID}}).Decode(result); err != nil {
+			return err
+		}
+		fmt.Println(result)
+		return nil
+	})
+}
+
+func ExampleClient_UseSessionWithOptions() {
+	var client *mongo.Client
+
+	// Specify the DefaultReadConcern option so any transactions started through the session will have read concern
+	// majority.
+	// The DefaultReadPreference and DefaultWriteConcern options aren't specified so they will be inheritied from client
+	// and be set to primary and majority, respectively.
+	opts := options.Session().SetDefaultReadConcern(readconcern.Majority())
+	err := client.UseSessionWithOptions(context.TODO(), opts, func(sessCtx mongo.SessionContext) error {
+		// Use sessCtx as the Context parameter for InsertOne and FindOne so both operations are run under the new
+		// Session.
+
+		coll := client.Database("db").Collection("coll")
+		res, err := coll.InsertOne(sessCtx, bson.D{{"x", 1}})
+		if err != nil {
+			return err
+		}
+
+		var result bson.M
+		if err = coll.FindOne(sessCtx, bson.D{{"_id", res.InsertedID}}).Decode(result); err != nil {
+			return err
+		}
+		fmt.Println(result)
+		return nil
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleClient_StartSession_withTransaction() {
+	var client *mongo.Client // assume client is configured with write concern majority and read preference primary
+
+	// Specify the DefaultReadConcern option so any transactions started through the session will have read concern
+	// majority.
+	// The DefaultReadPreference and DefaultWriteConcern options aren't specified so they will be inheritied from client
+	// and be set to primary and majority, respectively.
+	opts := options.Session().SetDefaultReadConcern(readconcern.Majority())
+	sess, err := client.StartSession(opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer sess.EndSession(context.TODO())
+
+	// Specify the ReadPreference option to set the read preference to primary preferred for this transaction.
+	txnOpts := options.Transaction().SetReadPreference(readpref.PrimaryPreferred())
+	result, err := sess.WithTransaction(context.TODO(), func(sessCtx mongo.SessionContext) (interface{}, error) {
+		// Use sessCtx as the Context parameter for InsertOne and FindOne so both operations are run in a
+		// transaction.
+
+		coll := client.Database("db").Collection("coll")
+		res, err := coll.InsertOne(sessCtx, bson.D{{"x", 1}})
+		if err != nil {
+			return nil, err
+		}
+
+		var result bson.M
+		if err = coll.FindOne(sessCtx, bson.D{{"_id", res.InsertedID}}).Decode(result); err != nil {
+			return nil, err
+		}
+		return result, err
+	}, txnOpts)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("result: %v\n", result)
+}

mongo/session.go

@@ -28,9 +28,9 @@ var ErrWrongClient = errors.New("session was not created by this client")
 
 var withTransactionTimeout = 120 * time.Second
 
-// SessionContext is a hybrid interface. It combines a context.Context with
-// a mongo.Session. This type can be used as a regular context.Context or
-// Session type. It is not goroutine safe and should not be used in multiple goroutines concurrently.
+// SessionContext combines the context.Context and mongo.Session interfaces. It should be used as the Context arguments
+// to operations that should be executed in a session. This type is not goroutine safe and must not be used concurrently
+// by multiple goroutines.
 type SessionContext interface {
 	context.Context
 	Session
@@ -44,20 +44,51 @@ type sessionContext struct {
 type sessionKey struct {
 }
 
-// Session is the interface that represents a sequential set of operations executed.
-// Instances of this interface can be used to use transactions against the server
-// and to enable causally consistent behavior for applications.
+// Session is an interface that represents a MongoDB logical session. Sessions can be used to enable causal consistency
+// for a group of operations or to execute operations in an ACID transaction. A new Session can be created from a Client
+// instance. A Session created from a Client must only be used to execute operations using that Client or a Database or
+// Collection created from that Client. Custom implementations of this interface should not be used in production. For
+// more information about sessions, and their use cases, see https://docs.mongodb.com/manual/reference/server-sessions/,
+// https://docs.mongodb.com/manual/core/read-isolation-consistency-recency/#causal-consistency, and
+// https://docs.mongodb.com/manual/core/transactions/.
+//
+// StartTransaction starts a new transaction, configured with the given options, on this session. This method will
+// return an error if there is already a transaction in-progress for this session.
+//
+// CommitTransaction commits the active transaction for this session. This method will return an error if there is no
+// active transaction for this session or the transaction has been aborted.
+//
+// AbortTransaction aborts the active transaction for this session. This method will return an error if there is no
+// active transaction for this session or the transaction has been committed or aborted.
+//
+// WithTransaction starts a transaction on this session and runs the fn callback. Errors with the
+// TransientTransactionError and UnknownTransactionCommitResult labels are retried for up to 120 seconds. Inside the
+// callback, sessCtx must be used as the Context parameter for any operations that should be part of the transaction. If
+// the ctx parameter already has a Session attached to it, it will be replaced by this session. The fn callback may be
+// run multiple times during WithTransaction due to retry attempts, so it must be idempotent. Non-retryable operation
+// errors or any operation errors that occur after the timeout expires will be returned without retrying. For a usage
+// example, see the Client.StartSession method documentation.
+//
+// ClusterTime, OperationTime, and Client return the session's current operation time, the session's current cluster
+// time, and the Client associated with the session, respectively.
+//
+// EndSession method should abort any existing transactions and close the session.
+//
+// AdvanceClusterTime and AdvanceOperationTime are for internal use only and must not be called.
 type Session interface {
-	EndSession(context.Context)
-	WithTransaction(ctx context.Context, fn func(sessCtx SessionContext) (interface{}, error), opts ...*options.TransactionOptions) (interface{}, error)
 	StartTransaction(...*options.TransactionOptions) error
 	AbortTransaction(context.Context) error
 	CommitTransaction(context.Context) error
+	WithTransaction(ctx context.Context, fn func(sessCtx SessionContext) (interface{}, error),
+		opts ...*options.TransactionOptions) (interface{}, error)
 	ClusterTime() bson.Raw
-	AdvanceClusterTime(bson.Raw) error
 	OperationTime() *primitive.Timestamp
-	AdvanceOperationTime(*primitive.Timestamp) error
 	Client() *Client
+	EndSession(context.Context)
+
+	AdvanceClusterTime(bson.Raw) error
+	AdvanceOperationTime(*primitive.Timestamp) error
+
 	session()
 }
 
@@ -89,7 +120,7 @@ func (s *sessionImpl) ID() bsonx.Doc {
 	return s.clientSession.SessionID
 }
 
-// EndSession ends the session.
+// EndSession implements the Session interface.
 func (s *sessionImpl) EndSession(ctx context.Context) {
 	if s.clientSession.TransactionInProgress() {
 		// ignore all errors aborting during an end session
@@ -98,18 +129,9 @@ func (s *sessionImpl) EndSession(ctx context.Context) {
 	s.clientSession.EndSession()
 }
 
-// WithTransaction creates a transaction on this session and runs the given callback, retrying for
-// TransientTransactionError and UnknownTransactionCommitResult errors. The only way to provide a
-// session to a CRUD method is to invoke that CRUD method with the mongo.SessionContext within the
-// callback. The mongo.SessionContext can be used as a regular context, so methods like
-// context.WithDeadline and context.WithTimeout are supported.
-//
-// If the context.Context already has a mongo.Session attached, that mongo.Session will be replaced
-// with the one provided.
-//
-// The callback may be run multiple times due to retry attempts. Non-retryable and timed out errors
-// are returned from this function.
-func (s *sessionImpl) WithTransaction(ctx context.Context, fn func(sessCtx SessionContext) (interface{}, error), opts ...*options.TransactionOptions) (interface{}, error) {
+// WithTransaction implements the Session interface.
+func (s *sessionImpl) WithTransaction(ctx context.Context, fn func(sessCtx SessionContext) (interface{}, error),
+	opts ...*options.TransactionOptions) (interface{}, error) {
 	timeout := time.NewTimer(withTransactionTimeout)
 	defer timeout.Stop()
 	var err error
@@ -170,7 +192,7 @@ func (s *sessionImpl) WithTransaction(ctx context.Context, fn func(sessCtx Sessi
 	}
 }
 
-// StartTransaction starts a transaction for this session.
+// StartTransaction implements the Session interface.
 func (s *sessionImpl) StartTransaction(opts ...*options.TransactionOptions) error {
 	err := s.clientSession.CheckStartTransaction()
 	if err != nil {
@@ -190,7 +212,7 @@ func (s *sessionImpl) StartTransaction(opts ...*options.TransactionOptions) erro
 	return s.clientSession.StartTransaction(coreOpts)
 }
 
-// AbortTransaction aborts the session's transaction, returning any errors and error codes
+// AbortTransaction implements the Session interface.
 func (s *sessionImpl) AbortTransaction(ctx context.Context) error {
 	err := s.clientSession.CheckAbortTransaction()
 	if err != nil {
@@ -207,15 +229,16 @@ func (s *sessionImpl) AbortTransaction(ctx context.Context) error {
 	s.clientSession.Aborting = true
 	_ = operation.NewAbortTransaction().Session(s.clientSession).ClusterClock(s.client.clock).Database("admin").
 		Deployment(s.deployment).WriteConcern(s.clientSession.CurrentWc).ServerSelector(selector).
-		Retry(driver.RetryOncePerCommand).CommandMonitor(s.client.monitor).RecoveryToken(bsoncore.Document(s.clientSession.RecoveryToken)).Execute(ctx)
+		Retry(driver.RetryOncePerCommand).CommandMonitor(s.client.monitor).
+		RecoveryToken(bsoncore.Document(s.clientSession.RecoveryToken)).Execute(ctx)
 
 	s.clientSession.Aborting = false
 	_ = s.clientSession.AbortTransaction()
 
 	return nil
 }
 
-// CommitTransaction commits the sesson's transaction.
+// CommitTransaction implements the Session interface.
 func (s *sessionImpl) CommitTransaction(ctx context.Context) error {
 	err := s.clientSession.CheckCommitTransaction()
 	if err != nil {
@@ -256,26 +279,32 @@ func (s *sessionImpl) CommitTransaction(ctx context.Context) error {
 	return commitErr
 }
 
+// ClusterTime implements the Session interface.
 func (s *sessionImpl) ClusterTime() bson.Raw {
 	return s.clientSession.ClusterTime
 }
 
+// AdvanceClusterTime implements the Session interface.
 func (s *sessionImpl) AdvanceClusterTime(d bson.Raw) error {
 	return s.clientSession.AdvanceClusterTime(d)
 }
 
+// OperationTime implements the Session interface.
 func (s *sessionImpl) OperationTime() *primitive.Timestamp {
 	return s.clientSession.OperationTime
 }
 
+// AdvanceOperationTime implements the Session interface.
 func (s *sessionImpl) AdvanceOperationTime(ts *primitive.Timestamp) error {
 	return s.clientSession.AdvanceOperationTime(ts)
 }
 
+// Client implements the Session interface.
 func (s *sessionImpl) Client() *Client {
 	return s.client
 }
 
+// session implements the Session interface.
 func (*sessionImpl) session() {
 }
 
@@ -290,6 +319,7 @@ func sessionFromContext(ctx context.Context) *session.Client {
 	return nil
 }
 
+// contextWithSession creates a new SessionContext associated with the given Context and Session parameters.
 func contextWithSession(ctx context.Context, sess Session) SessionContext {
 	return &sessionContext{
 		Context: context.WithValue(ctx, sessionKey{}, sess),