Class: Mongo::Server::Connection

Inherits:
ConnectionBase show all
Extended by:
Forwardable
Includes:
Monitoring::Publishable, Retryable, Connectable
Defined in:
lib/mongo/server/connection.rb

Overview

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

Since:

  • 2.0.0

Constant Summary collapse

PING =
Deprecated.

No longer necessary with Server Selection specification.

The ping command.

Since:

  • 2.1.0

{ :ping => 1 }.freeze
PING_OP_MSG =
Deprecated.

No longer necessary with Server Selection specification.

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

Since:

  • 2.5.0

{ :ping => 1, '$db' => Database::ADMIN }.freeze
PING_MESSAGE =
Deprecated.

No longer necessary with Server Selection specification.

Ping message.

Since:

  • 2.1.0

Protocol::Query.new(Database::ADMIN, Database::COMMAND, PING, :limit => -1)
PING_OP_MSG_MESSAGE =
Deprecated.

No longer necessary with Server Selection specification.

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

Since:

  • 2.5.0

Protocol::Msg.new([], {}, PING_OP_MSG)
PING_BYTES =
Deprecated.

No longer necessary with Server Selection specification.

The ping message as raw bytes.

Since:

  • 2.1.0

PING_MESSAGE.serialize.to_s.freeze
PING_OP_MSG_BYTES =
Deprecated.

No longer necessary with Server Selection specification.

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

Since:

  • 2.5.0

PING_OP_MSG_MESSAGE.serialize.to_s.freeze

Constants included from Loggable

Loggable::PREFIX

Constants included from Connectable

Mongo::Server::Connectable::SSL, Mongo::Server::Connectable::TIMEOUT

Constants inherited from ConnectionBase

Mongo::Server::ConnectionBase::DEFAULT_MAX_BSON_OBJECT_SIZE, Mongo::Server::ConnectionBase::MAX_BSON_COMMAND_OVERHEAD, Mongo::Server::ConnectionBase::REDUCED_MAX_BSON_SIZE

Instance Attribute Summary collapse

Attributes included from Monitoring::Publishable

#monitoring

Attributes included from Connectable

#pid

Attributes inherited from ConnectionBase

#options, #server

Attributes inherited from ConnectionCommon

#compressor

Instance Method Summary collapse

Methods included from Retryable

#legacy_write_with_retry, #nro_write_with_retry, #read_with_one_retry, #read_with_retry, #read_with_retry_cursor, #write_with_retry

Methods included from Monitoring::Publishable

#publish_cmap_event, #publish_event, #publish_sdam_event

Methods included from Loggable

#log_debug, #log_error, #log_fatal, #log_info, #log_warn, #logger

Methods included from Connectable

#connectable?, #connected?

Methods inherited from ConnectionBase

#app_metadata, #dispatch

Constructor Details

#initialize(server, options = {}) ⇒ Connection

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

Connection must never be directly instantiated outside of a Server.

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.

Examples:

Create the connection.

Connection.new(server)

Parameters:

  • server (Mongo::Server) —

    The server the connection is for.

  • options (Hash) (defaults to: {}) —

    The connection options.

Options Hash (options):

  • :generation (Integer) —

    Connection pool’s generation for this connection.

Since:

  • 2.0.0



91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/mongo/server/connection.rb', line 91

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

Instance Attribute Details

#description ⇒ Server::Description (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns The server description obtained from the handshake on this connection.

Returns:

  • (Server::Description) —

    The server description obtained from the handshake on this connection.

Since:

  • 2.0.0



110
111
112
 
# File 'lib/mongo/server/connection.rb', line 110

def description
  @description
end

#id ⇒ Integer (readonly)

across connections to the same server object.

Returns:

  • (Integer) —

    The ID for the connection. This will be unique

Since:

  • 2.9.0



121
122
123
 
# File 'lib/mongo/server/connection.rb', line 121

def id
  @id
end

#last_checkin ⇒ Time (readonly)

Returns The last time the connection was checked back into a pool.

Returns:

  • (Time) —

    The last time the connection was checked back into a pool.

Since:

  • 2.5.0



115
116
117
 
# File 'lib/mongo/server/connection.rb', line 115

def last_checkin
  @last_checkin
end

Instance Method Details

#closed? ⇒ true | false

Whether the connection was closed.

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

Returns:

  • (true | false) —

    Whether connection was closed.

Since:

  • 2.9.0



148
149
150
 
# File 'lib/mongo/server/connection.rb', line 148

def closed?
  !!@closed
end

#connect! ⇒ true

Note:

This method mutates the connection object by setting a socket if one previously did not exist.

Establishes a network connection to the target address.

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

Examples:

Connect to the host.

connection.connect!

Returns:

  • (true) —

    If the connection succeeded.

Since:

  • 2.0.0



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/mongo/server/connection.rb', line 165

def connect!
  if closed?
    if Lint.enabled?
      raise Error::LintError, "Reconnecting closed connections is no longer supported (for #{address})"
    else
      log_warn("Reconnecting closed connections is deprecated (for #{address})")
    end
  end

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

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

    @close_event_published = false
  end
  true
end

#connection_pool ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Since:

  • 2.0.0



136
137
138
 
# File 'lib/mongo/server/connection.rb', line 136

def connection_pool
  options[:connection_pool]
end

#disconnect!(options = nil) ⇒ true

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.

Disconnect the connection.

Parameters:

  • options (Hash) (defaults to: nil) —

    a customizable set of options

Options Hash (options):

  • :reason (Symbol) —

    The reason why the connection is being closed.

Returns:

  • (true) —

    If the disconnect succeeded.

Since:

  • 2.0.0



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/mongo/server/connection.rb', line 228

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
    @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

#generation ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Connection pool generation from which this connection was created. May be nil.

Since:

  • 2.7.0



128
129
130
 
# File 'lib/mongo/server/connection.rb', line 128

def generation
  options[:generation]
end

#ping ⇒ true, false

Deprecated.

No longer necessary with Server Selection specification.

Note:

This uses a pre-serialized ping message for optimization.

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

Examples:

Ping the connection.

connection.ping

Returns:

  • (true, false) —

    If the server is accepting connections.

Since:

  • 2.1.0



272
273
274
275
276
277
278
279
 
# File 'lib/mongo/server/connection.rb', line 272

def ping
  bytes = features.op_msg_enabled? ? PING_OP_MSG_BYTES : PING_BYTES
  ensure_connected do |socket|
    socket.write(bytes)
    reply = Protocol::Message.deserialize(socket, max_message_size)
    reply.documents[0][Operation::Result::OK] == 1
  end
end

#record_checkin! ⇒ self

Record the last checkin time.

Examples:

Record the checkin time on this connection.

connection.record_checkin!

Returns:

  • (self)

Since:

  • 2.5.0



303
304
305
306
 
# File 'lib/mongo/server/connection.rb', line 303

def record_checkin!
  @last_checkin = Time.now
  self
end

#socket_timeout ⇒ Float Also known as: timeout

Get the timeout to execute an operation on a socket.

Examples:

Get the timeout to execute an operation on a socket.

connection.timeout

Returns:

  • (Float) —

    The operation timeout in seconds.

Since:

  • 2.0.0



289
290
291
 
# File 'lib/mongo/server/connection.rb', line 289

def socket_timeout
  @timeout ||= options[:socket_timeout]
end