Initialize a Session.

@note Applications should use Client#start_session to begin a session.

@example

  Session.new(server_session, client, options)

@param [ ServerSession ] server_session The server session this session is associated with. @param [ Client ] client The client through which this session is created. @param [ Hash ] options The options for this session.

@option options [ true|false ] :causal_consistency Whether to enable

  causal consistency for this session.

@option options [ Hash ] :default_transaction_options Options to pass

  to start_transaction by default, can contain any of the options that
  start_transaction accepts.

@option options [ true|false ] :implicit For internal driver use only -

  specifies whether the session is implicit.

@option options [ Hash ] :read_preference The read preference options hash,

  with the following optional keys:
  - *:mode* -- the read preference as a string or symbol; valid values are
    *:primary*, *:primary_preferred*, *:secondary*, *:secondary_preferred*
    and *:nearest*.

@since 2.5.0 @api private

Abort the currently active transaction without making any changes to the database.

@example Abort the transaction.

  session.abort_transaction

@raise [ Error::InvalidTransactionOperation ] If there is no active transaction.

@since 2.6.0

Add the autocommit field to a command document if applicable.

@example

  session.add_autocommit!(cmd)

@return [ Hash, BSON::Document ] The command document.

@since 2.6.0 @api private

Add this session‘s id to a command document.

@example

  session.add_id!(cmd)

@return [ Hash, BSON::Document ] The command document.

@since 2.5.0 @api private

Add the startTransaction field to a command document if applicable.

@example

  session.add_start_transaction!(cmd)

@return [ Hash, BSON::Document ] The command document.

@since 2.6.0 @api private

Add the transaction number to a command document if applicable.

@example

  session.add_txn_num!(cmd)

@return [ Hash, BSON::Document ] The command document.

@since 2.6.0 @api private

Add the transactions options if applicable.

@example

  session.add_txn_opts!(cmd)

@return [ Hash, BSON::Document ] The command document.

@since 2.6.0 @api private

Advance the cached cluster time document for this session.

@example Advance the cluster time.

  session.advance_cluster_time(doc)

@param [ BSON::Document, Hash ] new_cluster_time The new cluster time.

@return [ BSON::Document, Hash ] The new cluster time.

@since 2.5.0

Advance the cached operation time for this session.

@example Advance the operation time.

  session.advance_operation_time(timestamp)

@param [ BSON::Timestamp ] new_operation_time The new operation time.

@return [ BSON::Timestamp ] The max operation time, considering the current and new times.

@since 2.5.0

Commit the currently active transaction on the session.

@example Commits the transaction.

  session.commit_transaction

@option options :write_concern [ nil | WriteConcern::Base ] The write

  concern to use for this operation.

@raise [ Error::InvalidTransactionOperation ] If there is no active transaction.

@since 2.6.0

End this session.

@example

  session.end_session

@return [ nil ] Always nil.

@since 2.5.0

Whether this session has ended.

@example

  session.ended?

@return [ true, false ] Whether the session has ended.

@since 2.5.0

Is this session an explicit one (i.e. user-created).

@example Is the session explicit?

  session.explicit?

@return [ true, false ] Whether this session is explicit.

@since 2.5.2

Is this session an implicit one (not user-created).

@example Is the session implicit?

  session.implicit?

@return [ true, false ] Whether this session is implicit.

@since 2.5.1

Whether or not the session is currently in a transaction.

@example Is the session in a transaction?

  session.in_transaction?

@return [ true | false ] Whether or not the session in a transaction.

@since 2.6.0

Get a formatted string for use in inspection.

@example Inspect the session object.

  session.inspect

@return [ String ] The session inspection.

@since 2.5.0

Increment and return the next transaction number.

@example Get the next transaction number.

  session.next_txn_num

@return [ Integer ] The next transaction number.

@since 2.5.0 @api private

Process a response from the server that used this session.

@example Process a response from the server.

  session.process(result)

@param [ Operation::Result ] result The result from the operation.

@return [ Operation::Result ] The result.

@since 2.5.0 @api private

Will writes executed with this session be retried.

@example Will writes be retried.

  session.retry_writes?

@return [ true, false ] If writes will be retried.

@note Retryable writes are only available on server versions at least 3.6

  and with sharded clusters or replica sets.

@since 2.5.0

Get the server session id of this session, if the session was not ended. If the session was ended, returns nil.

@example Get the session id.

  session.session_id

@return [ BSON::Document ] The server session id.

@since 2.5.0

Places subsequent operations in this session into a new transaction.

Note that the transaction will not be started on the server until an operation is performed after start_transaction is called.

@example Start a new transaction

  session.start_transaction(options)

@param [ Hash ] options The options for the transaction being started.

@option options [ Hash ] read_concern The read concern options hash,

  with the following optional keys:
  - *:level* -- the read preference level as a symbol; valid values
     are *:local*, *:majority*, and *:snapshot*

@option options [ Hash ] :write_concern The write concern options. Can be :w =>

  Integer|String, :fsync => Boolean, :j => Boolean.

@option options [ Hash ] :read The read preference options. The hash may have the following

  items:
  - *:mode* -- read preference specified as a symbol; the only valid value is
    *:primary*.

@raise [ Error::InvalidTransactionOperation ] If a transaction is already in

  progress or if the write concern is unacknowledged.

@since 2.6.0

Remove the read concern and/or write concern from the command if not applicable.

@example

  session.suppress_read_write_concern!(cmd)

@return [ Hash, BSON::Document ] The command document.

@since 2.6.0 @api private

Get the current transaction number.

@example Get the current transaction number.

  session.txn_num

@return [ Integer ] The current transaction number.

@since 2.6.0

Get the read preference the session will use in the currently active transaction.

This is a driver style hash with underscore keys.

@example Get the transaction‘s read preference

  session.txn_read_preference

@return [ Hash ] The read preference of the transaction.

@since 2.6.0

Update the state of the session due to a (non-commit and non-abort) operation being run.

@since 2.6.0 @api private

Validate the session.

@example

  session.validate!(cluster)

@param [ Cluster ] cluster The cluster the session is attempted to be used with.

@return [ nil ] nil if the session is valid.

@raise [ Mongo::Error::InvalidSession ] Raise error if the session is not valid.

@since 2.5.0 @api private

Ensure that the read preference of a command primary.

@example

  session.validate_read_preference!(command)

@raise [ Mongo::Error::InvalidTransactionOperation ] If the read preference of the command is

  not primary.

@since 2.6.0 @api private

Executes the provided block in a transaction, retrying as necessary.

Returns the return value of the block.

Exact number of retries and when they are performed are implementation details of the driver; the provided block should be idempotent, and should be prepared to be called more than once. The driver may retry the commit command within an active transaction or it may repeat the transaction and invoke the block again, depending on the error encountered if any. Note also that the retries may be executed against different servers.

Transactions cannot be nested - InvalidTransactionOperation will be raised if this method is called when the session already has an active transaction.

Exceptions raised by the block which are not derived from Mongo::Error stop processing, abort the transaction and are propagated out of with_transaction. Exceptions derived from Mongo::Error may be handled by with_transaction, resulting in retries of the process.

Currently, with_transaction will retry commits and block invocations until at least 120 seconds have passed since with_transaction started executing. This timeout is not configurable and may change in a future driver version.

@note with_transaction contains a loop, therefore the if with_transaction

  itself is placed in a loop, its block should not call next or break to
  control the outer loop because this will instead affect the loop in
  with_transaction. The driver will warn and abort the transaction
  if it detects this situation.

@example Execute a statement in a transaction

  session.with_transaction(write_concern: {w: :majority}) do
    collection.update_one({ id: 3 }, { '$set' => { status: 'Inactive'} },
                          session: session)

  end

@example Execute a statement in a transaction, limiting total time consumed

  Timeout.timeout(5) do
    session.with_transaction(write_concern: {w: :majority}) do
      collection.update_one({ id: 3 }, { '$set' => { status: 'Inactive'} },
                            session: session)

    end
  end

@param [ Hash ] options The options for the transaction being started.

  These are the same options that start_transaction accepts.

@raise [ Error::InvalidTransactionOperation ] If a transaction is already in

  progress or if the write concern is unacknowledged.

@since 2.7.0