class Mongo::Server::Connection

This class models the socket connections for servers and their behavior.

@since 2.0.0

Constants

PING

The ping command.

@since 2.1.0

@deprecated No longer necessary with Server Selection specification.

PING_BYTES

The ping message as raw bytes.

@since 2.1.0

@deprecated No longer necessary with Server Selection specification.

PING_MESSAGE

Ping message.

@since 2.1.0

@deprecated No longer necessary with Server Selection specification.

PING_OP_MSG

The ping command for an OP_MSG (server versions >= 3.6).

@since 2.5.0

@deprecated No longer necessary with Server Selection specification.

PING_OP_MSG_BYTES

The ping OP_MSG message as raw bytes (server versions >= 3.6).

@since 2.5.0

@deprecated No longer necessary with Server Selection specification.

PING_OP_MSG_MESSAGE

Ping message as an OP_MSG (server versions >= 3.6).

@since 2.5.0

@deprecated No longer necessary with Server Selection specification.

Attributes

id[R]

@return [ Integer ] The ID for the connection. This will be unique across connections to the same server object.

@since 2.9.0

last_checkin[R]

@return [ Time ] The last time the connection was checked back into a pool.

@since 2.5.0

Public Class Methods

new(server, options = {}) click to toggle source

Creates a new connection object to the specified target address with the specified options.

The constructor does not perform any I/O (and thus does not create sockets, handshakes nor authenticates); call connect! method on the connection object to create the network connection.

@api private

@example Create the connection.

Connection.new(server)

@note Connection must never be directly instantiated outside of a

Server.

@param [ Mongo::Server ] server The server the connection is for. @param [ Hash ] options The connection options.

@option options [ Integer ] :generation Connection pool’s generation

for this connection.

@since 2.0.0

# File lib/mongo/server/connection.rb, line 90
def initialize(server, options = {})
  @id = server.next_connection_id
  @monitoring = server.monitoring
  @options = options.freeze
  @server = server
  @socket = nil
  @last_checkin = nil
  @auth_mechanism = nil
  @pid = Process.pid

  publish_cmap_event(
    Monitoring::Event::Cmap::ConnectionCreated.new(address, id)
  )
end

Public Instance Methods

closed?() click to toggle source

Whether the connection was closed.

Closed connections should no longer be used. Instead obtain a new connection from the connection pool.

@return [ true | false ] Whether connection was closed.

@since 2.9.0

# File lib/mongo/server/connection.rb, line 132
def closed?
  !!@closed
end
connect!() click to toggle source

Establishes a network connection to the target address.

If the connection is already established, this method does nothing.

@example Connect to the host.

connection.connect!

@note This method mutates the connection object by setting a socket if

one previously did not exist.

@return [ true ] If the connection succeeded.

@since 2.0.0

# File lib/mongo/server/connection.rb, line 154
def connect!
  if error?
    raise Error::ConnectionPerished, "Connection #{generation}:#{id} for #{address.seed} is perished. Reconnecting closed or errored connections is no longer supported"
  end

  if closed?
    raise Error::ConnectionPerished, "Connection #{generation}:#{id} for #{address.seed} is closed. Reconnecting closed or errored connections is no longer supported"
  end

  unless @socket
    # When @socket is assigned, the socket should have handshaken and
    # authenticated and be usable.
    @socket, @description, @compressor = do_connect

    publish_cmap_event(
      Monitoring::Event::Cmap::ConnectionReady.new(address, id)
    )

    @close_event_published = false
  end
  true
end
connection_pool() click to toggle source

The connection pool from which this connection was created. May be nil.

@api private

# File lib/mongo/server/connection.rb, line 120
def connection_pool
  options[:connection_pool]
end
disconnect!(options = nil) click to toggle source

Disconnect the connection.

@note Once a connection is disconnected, it should no longer be used.

A new connection should be obtained from the connection pool which
will either return a ready connection or create a new connection.
If linting is enabled, reusing a disconnected connection will raise
Error::LintError. If linting is not enabled, a warning will be logged.

@note This method mutates the connection object by setting the socket

to nil if the closing succeeded.

@option options [ Symbol ] :reason The reason why the connection is

being closed.

@return [ true ] If the disconnect succeeded.

@since 2.0.0

# File lib/mongo/server/connection.rb, line 217
def disconnect!(options = nil)
  # Note: @closed may be true here but we also may have a socket.
  # Check the socket and not @closed flag.
  @auth_mechanism = nil
  @last_checkin = nil
  if socket
    socket.close rescue nil
    @socket = nil
  end
  @closed = true

  # To satisfy CMAP spec tests, publish close events even if the
  # socket was never connected (and thus the ready event was never
  # published). But track whether we published close event and do not
  # publish it multiple times, unless the socket was reconnected -
  # in that case publish the close event once per socket close.
  unless @close_event_published
    reason = options && options[:reason]
    publish_cmap_event(
      Monitoring::Event::Cmap::ConnectionClosed.new(
        address,
        id,
        reason,
      ),
    )
    @close_event_published = true
  end

  true
end
error?() click to toggle source

@api private

# File lib/mongo/server/connection.rb, line 137
def error?
  !!@error
end
ping() click to toggle source

Ping the connection to see if the server is responding to commands. This is non-blocking on the server side.

@example Ping the connection.

connection.ping

@note This uses a pre-serialized ping message for optimization.

@return [ true, false ] If the server is accepting connections.

@since 2.1.0

@deprecated No longer necessary with Server Selection specification.

# File lib/mongo/server/connection.rb, line 261
def ping
  bytes = features.op_msg_enabled? ? PING_OP_MSG_BYTES : PING_BYTES
  ensure_connected do |socket|
    reply = add_server_diagnostics do
      socket.write(bytes)
      Protocol::Message.deserialize(socket, max_message_size)
    end
    reply.documents[0][Operation::Result::OK] == 1
  end
end
record_checkin!() click to toggle source

Record the last checkin time.

@example Record the checkin time on this connection.

connection.record_checkin!

@return [ self ]

@since 2.5.0

# File lib/mongo/server/connection.rb, line 291
def record_checkin!
  @last_checkin = Time.now
  self
end
socket_timeout() click to toggle source

Get the timeout to execute an operation on a socket.

@return [ Float ] The operation timeout in seconds.

@since 2.0.0

# File lib/mongo/server/connection.rb, line 277
def socket_timeout
  @timeout ||= options[:socket_timeout]
end
Also aliased as: timeout
timeout()

@deprecated Please use :socket_timeout instead. Will be removed in 3.0.0

Alias for: socket_timeout

Private Instance Methods

deliver(message, client, options = {}) click to toggle source
Calls superclass method
# File lib/mongo/server/connection.rb, line 298
def deliver(message, client, options = {})
  handle_errors do
    super
  end
end
do_connect() click to toggle source

Separate method to permit easier mocking in the test suite.

@return [ Array<Socket, Server::Description> ] Connected socket and

a server description instance from the ismaster response of the
returned socket.
# File lib/mongo/server/connection.rb, line 182
        def do_connect
  socket = add_server_diagnostics do
    address.socket(socket_timeout, ssl_options.merge(
      connection_address: address, connection_generation: generation))
  end

  begin
    pending_connection = PendingConnection.new(
      socket, @server, monitoring, options.merge(id: id))
    pending_connection.handshake_and_authenticate!
  rescue Exception
    socket.close
    raise
  end

  [socket, pending_connection.description, pending_connection.compressor]
end
handle_errors() { || ... } click to toggle source
# File lib/mongo/server/connection.rb, line 304
def handle_errors
  begin
    yield
  rescue Error::SocketError => e
    @error = e
    @server.unknown!(generation: e.generation, stop_push_monitor: true)
    raise
  rescue Error::SocketTimeoutError => e
    @error = e
    raise
  end
end