session

Documentation

Overview

Package session is intended for internal use only. It is made available to facilitate use cases that require access to internal MongoDB driver functionality and state. The API of this package is not stable and there is no backward compatibility guarantee.

WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT NOTICE! USE WITH EXTREME CAUTION!

Index

• Constants
• Variables
• func MaxClusterTime(ct1, ct2 bson.Raw) bson.Raw
• type Client
  • func NewClientSession(pool *Pool, clientID uuid.UUID, opts ...*ClientOptions) (*Client, error)
  • func NewImplicitClientSession(pool *Pool, clientID uuid.UUID) *Client
  • func (c *Client) AbortTransaction() error
  • func (c *Client) AdvanceClusterTime(clusterTime bson.Raw) error
  • func (c *Client) AdvanceOperationTime(opTime *primitive.Timestamp) error
  • func (c *Client) ApplyCommand(desc description.Server) error
  • func (c *Client) CheckAbortTransaction() error
  • func (c *Client) CheckCommitTransaction() error
  • func (c *Client) CheckStartTransaction() error
  • func (c *Client) ClearPinnedResources() error
  • func (c *Client) CommitTransaction() error
  • func (c *Client) EndSession()
  • func (c *Client) SetServer() error
  • func (c *Client) StartCommand() error
  • func (c *Client) StartTransaction(opts *TransactionOptions) error
  • func (c *Client) TransactionCommitted() bool
  • func (c *Client) TransactionInProgress() bool
  • func (c *Client) TransactionRunning() bool
  • func (c *Client) TransactionStarting() bool
  • func (c *Client) UpdateCommitTransactionWriteConcern()
  • func (c *Client) UpdateRecoveryToken(response bson.Raw)
  • func (c *Client) UpdateSnapshotTime(response bsoncore.Document)
  • func (c *Client) UpdateUseTime() error
• type ClientOptions
• type ClusterClock
  • func (cc *ClusterClock) AdvanceClusterTime(clusterTime bson.Raw)
  • func (cc *ClusterClock) GetClusterTime() bson.Raw
• type LoadBalancedTransactionConnection
• type Node
• type Pool
  • func NewPool(descChan <-chan description.Topology) *Pool
  • func (p *Pool) CheckedOut() int64
  • func (p *Pool) GetSession() (*Server, error)
  • func (p *Pool) IDSlice() []bsoncore.Document
  • func (p *Pool) ReturnSession(ss *Server)
  • func (p *Pool) String() string
• type Server
  • func (ss *Server) IncrementTxnNumber()
  • func (ss *Server) MarkDirty()
• type TransactionOptions
• type TransactionState
  • func (s TransactionState) String() string

Constants

const UUIDSubtype byte = 4

UUIDSubtype is the BSON binary subtype that a UUID should be encoded as

Variables

var ErrAbortAfterCommit = errors.New("cannot call abortTransaction after calling commitTransaction")

ErrAbortAfterCommit is returned when abort is called after a commit.

var ErrAbortTwice = errors.New("cannot call abortTransaction twice")

ErrAbortTwice is returned if abort is called after transaction is already aborted.

var ErrCommitAfterAbort = errors.New("cannot call commitTransaction after calling abortTransaction")

ErrCommitAfterAbort is returned if commit is called after an abort.

var ErrNoTransactStarted = errors.New("no transaction started")

ErrNoTransactStarted is returned if a transaction operation is called when no transaction has started.

var ErrSessionEnded = errors.New("ended session was used")

ErrSessionEnded is returned when a client session is used after a call to endSession().

var ErrSnapshotTransaction = errors.New("transactions are not supported in snapshot sessions")

ErrSnapshotTransaction is returned if an transaction is started on a snapshot session.

var ErrTransactInProgress = errors.New("transaction already in progress")

ErrTransactInProgress is returned if startTransaction() is called when a transaction is in progress.

var ErrUnackWCUnsupported = errors.New("transactions do not support unacknowledged write concerns")

ErrUnackWCUnsupported is returned if an unacknowledged write concern is supported for a transaction.

Functions

func MaxClusterTime

func MaxClusterTime(ct1, ct2 bson.Raw) bson.Raw

MaxClusterTime compares 2 clusterTime documents and returns the document representing the highest cluster time.

Types

type Client

type Client struct {
	*Server
	ClientID       uuid.UUID
	ClusterTime    bson.Raw
	Consistent     bool // causal consistency
	OperationTime  *primitive.Timestamp
	IsImplicit     bool
	Terminated     bool
	RetryingCommit bool
	Committing     bool
	Aborting       bool
	RetryWrite     bool
	RetryRead      bool
	Snapshot       bool

	// options for the current transaction
	// most recently set by transactionopt
	CurrentRc  *readconcern.ReadConcern
	CurrentRp  *readpref.ReadPref
	CurrentWc  *writeconcern.WriteConcern
	CurrentMct *time.Duration

	TransactionState TransactionState
	PinnedServer     *description.Server
	RecoveryToken    bson.Raw
	PinnedConnection LoadBalancedTransactionConnection
	SnapshotTime     *primitive.Timestamp
	// contains filtered or unexported fields
}

Client is a session for clients to run commands.

func NewClientSession

func NewClientSession(pool *Pool, clientID uuid.UUID, opts ...*ClientOptions) (*Client, error)

NewClientSession creates a new explicit client-side session.

func NewImplicitClientSession

func NewImplicitClientSession(pool *Pool, clientID uuid.UUID) *Client

NewImplicitClientSession creates a new implicit client-side session.

func (*Client) AbortTransaction

func (c *Client) AbortTransaction() error

AbortTransaction updates the state for a successfully aborted transaction and returns an error if not permissible. It does not actually perform the abort.

func (*Client) AdvanceClusterTime

func (c *Client) AdvanceClusterTime(clusterTime bson.Raw) error

AdvanceClusterTime updates the session's cluster time.

func (*Client) AdvanceOperationTime

func (c *Client) AdvanceOperationTime(opTime *primitive.Timestamp) error

AdvanceOperationTime updates the session's operation time.

func (*Client) ApplyCommand

func (c *Client) ApplyCommand(desc description.Server) error

ApplyCommand advances the state machine upon command execution. This must be called after server selection is complete.

func (*Client) CheckAbortTransaction

func (c *Client) CheckAbortTransaction() error

CheckAbortTransaction checks to see if allowed to abort transaction and returns an error if not allowed.

func (*Client) CheckCommitTransaction

func (c *Client) CheckCommitTransaction() error

CheckCommitTransaction checks to see if allowed to commit transaction and returns an error if not allowed.

func (*Client) CheckStartTransaction

func (c *Client) CheckStartTransaction() error

CheckStartTransaction checks to see if allowed to start transaction and returns an error if not allowed

func (*Client) ClearPinnedResources

func (c *Client) ClearPinnedResources() error

ClearPinnedResources clears the pinned server and/or connection associated with the session.

func (*Client) CommitTransaction

func (c *Client) CommitTransaction() error

CommitTransaction updates the state for a successfully committed transaction and returns an error if not permissible. It does not actually perform the commit.

func (*Client) EndSession

func (c *Client) EndSession()

EndSession ends the session.

func (*Client) SetServer

func (c *Client) SetServer() error

SetServer will check out a session from the client session pool.

func (*Client) StartCommand

func (c *Client) StartCommand() error

StartCommand updates the session's internal state at the beginning of an operation. This must be called before server selection is done for the operation as the session's state can impact the result of that process.

func (*Client) StartTransaction

func (c *Client) StartTransaction(opts *TransactionOptions) error

StartTransaction initializes the transaction options and advances the state machine. It does not contact the server to start the transaction.

func (*Client) TransactionCommitted

func (c *Client) TransactionCommitted() bool

TransactionCommitted returns true of the client session just committed a transaction.

func (*Client) TransactionInProgress

func (c *Client) TransactionInProgress() bool

TransactionInProgress returns true if the client session is in an active transaction.

func (*Client) TransactionRunning

func (c *Client) TransactionRunning() bool

TransactionRunning returns true if the client session has started the transaction and it hasn't been committed or aborted

func (*Client) TransactionStarting

func (c *Client) TransactionStarting() bool

TransactionStarting returns true if the client session is starting a transaction.

func (*Client) UpdateCommitTransactionWriteConcern

func (c *Client) UpdateCommitTransactionWriteConcern()

UpdateCommitTransactionWriteConcern will set the write concern to majority and potentially set a w timeout of 10 seconds. This should be called after a commit transaction operation fails with a retryable error or after a successful commit transaction operation.

func (*Client) UpdateRecoveryToken

func (c *Client) UpdateRecoveryToken(response bson.Raw)

UpdateRecoveryToken updates the session's recovery token from the server response.

func (*Client) UpdateSnapshotTime

func (c *Client) UpdateSnapshotTime(response bsoncore.Document)

UpdateSnapshotTime updates the session's value for the atClusterTime field of ReadConcern.

func (*Client) UpdateUseTime

func (c *Client) UpdateUseTime() error

UpdateUseTime sets the session's last used time to the current time. This must be called whenever the session is used to send a command to the server to ensure that the session is not prematurely marked expired in the driver's session pool. If the session has already been ended, this method will return ErrSessionEnded.

type ClientOptions

type ClientOptions struct {
	CausalConsistency     *bool
	DefaultReadConcern    *readconcern.ReadConcern
	DefaultWriteConcern   *writeconcern.WriteConcern
	DefaultReadPreference *readpref.ReadPref
	DefaultMaxCommitTime  *time.Duration
	Snapshot              *bool
}

ClientOptions represents all possible options for creating a client session.

type ClusterClock

type ClusterClock struct {
	// contains filtered or unexported fields
}

ClusterClock represents a logical clock for keeping track of cluster time.

func (*ClusterClock) AdvanceClusterTime

func (cc *ClusterClock) AdvanceClusterTime(clusterTime bson.Raw)

AdvanceClusterTime updates the cluster's current time.

func (*ClusterClock) GetClusterTime

func (cc *ClusterClock) GetClusterTime() bson.Raw

GetClusterTime returns the cluster's current time.

type LoadBalancedTransactionConnection

type LoadBalancedTransactionConnection interface {
	// Functions copied over from driver.Connection.
	WriteWireMessage(context.Context, []byte) error
	ReadWireMessage(ctx context.Context) ([]byte, error)
	Description() description.Server
	Close() error
	ID() string
	ServerConnectionID() *int64
	DriverConnectionID() uint64 // TODO(GODRIVER-2824): change type to int64.
	Address() address.Address
	Stale() bool
	OIDCTokenGenID() uint64
	SetOIDCTokenGenID(uint64)

	// Functions copied over from driver.PinnedConnection that are not part of Connection or Expirable.
	PinToCursor() error
	PinToTransaction() error
	UnpinFromCursor() error
	UnpinFromTransaction() error
}

LoadBalancedTransactionConnection represents a connection that's pinned by a ClientSession because it's being used to execute a transaction when running against a load balancer. This interface is a copy of driver.PinnedConnection and exists to be able to pin transactions to a connection without causing an import cycle.

type Node

type Node struct {
	*Server
	// contains filtered or unexported fields
}

Node represents a server session in a linked list

type Pool

type Pool struct {
	// contains filtered or unexported fields
}

Pool is a pool of server sessions that can be reused.

func NewPool

func NewPool(descChan <-chan description.Topology) *Pool

NewPool creates a new server session pool

func (*Pool) CheckedOut

func (p *Pool) CheckedOut() int64

CheckedOut returns number of sessions checked out from pool.

func (*Pool) GetSession

func (p *Pool) GetSession() (*Server, error)

GetSession retrieves an unexpired session from the pool.

func (*Pool) IDSlice

func (p *Pool) IDSlice() []bsoncore.Document

IDSlice returns a slice of session IDs for each session in the pool

func (*Pool) ReturnSession

func (p *Pool) ReturnSession(ss *Server)

ReturnSession returns a session to the pool if it has not expired.

func (*Pool) String

func (p *Pool) String() string

String implements the Stringer interface

type Server

type Server struct {
	SessionID bsoncore.Document
	TxnNumber int64
	LastUsed  time.Time
	Dirty     bool
}

Server is an open session with the server.

func (*Server) IncrementTxnNumber

func (ss *Server) IncrementTxnNumber()

IncrementTxnNumber increments the transaction number.

func (*Server) MarkDirty

func (ss *Server) MarkDirty()

MarkDirty marks the session as dirty.

type TransactionOptions

type TransactionOptions struct {
	ReadConcern    *readconcern.ReadConcern
	WriteConcern   *writeconcern.WriteConcern
	ReadPreference *readpref.ReadPref
	MaxCommitTime  *time.Duration
}

TransactionOptions represents all possible options for starting a transaction in a session.

type TransactionState

type TransactionState uint8

TransactionState indicates the state of the transactions FSM.

const (
	None TransactionState = iota
	Starting
	InProgress
	Committed
	Aborted
)

Client Session states

func (TransactionState) String

func (s TransactionState) String() string

String implements the fmt.Stringer interface.