Class: Mongo::Address

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/mongo/address.rb,
lib/mongo/address/ipv4.rb,
lib/mongo/address/ipv6.rb,
lib/mongo/address/unix.rb,
lib/mongo/address/validator.rb

Overview

Represents an address to a server, either with an IP address or socket path.

Since:

  • 2.0.0

Defined Under Namespace

Modules: Validator Classes: IPv4, IPv6, Unix

Constant Summary collapse

FAMILY_MAP =

Mapping from socket family to resolver class.

Since:

  • 2.0.0

{
  ::Socket::PF_UNIX => Unix,
  ::Socket::AF_INET6 => IPv6,
  ::Socket::AF_INET => IPv4
}.freeze
LOCALHOST =

The localhost constant.

Since:

  • 2.1.0

'localhost'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(seed, options = {}) ⇒ Address

Initialize the address.

Examples:

Initialize the address with a DNS entry and port.

Mongo::Address.new("app.example.com:27017")

Initialize the address with a DNS entry and no port.

Mongo::Address.new("app.example.com")

Initialize the address with an IPV4 address and port.

Mongo::Address.new("127.0.0.1:27017")

Initialize the address with an IPV4 address and no port.

Mongo::Address.new("127.0.0.1")

Initialize the address with an IPV6 address and port.

Mongo::Address.new("[::1]:27017")

Initialize the address with an IPV6 address and no port.

Mongo::Address.new("[::1]")

Initialize the address with a unix socket.

Mongo::Address.new("/path/to/socket.sock")

Parameters:

  • seed (String) —

    The provided address.

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

    The address options.

Options Hash (options):

  • :connect_timeout (Float) —

    Connect timeout.

Since:

  • 2.0.0



72
73
74
75
76
77
78
79
 
# File 'lib/mongo/address.rb', line 72

def initialize(seed, options = {})
  if seed.nil?
    raise ArgumentError, "address must be not nil"
  end
  @seed = seed
  @host, @port = parse_host_port
  @options = options
end

Instance Attribute Details

#host ⇒ String (readonly)

Returns host The original host name.

Returns:

  • (String) —

    host The original host name.

Since:

  • 2.0.0



85
86
87
 
# File 'lib/mongo/address.rb', line 85

def host
  @host
end

#options ⇒ Object (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.

Since:

  • 2.0.0



91
92
93
 
# File 'lib/mongo/address.rb', line 91

def options
  @options
end

#port ⇒ Integer (readonly)

Returns port The port.

Returns:

  • (Integer) —

    port The port.

Since:

  • 2.0.0



88
89
90
 
# File 'lib/mongo/address.rb', line 88

def port
  @port
end

#seed ⇒ String (readonly)

Returns seed The seed address.

Returns:

  • (String) —

    seed The seed address.

Since:

  • 2.0.0



82
83
84
 
# File 'lib/mongo/address.rb', line 82

def seed
  @seed
end

Instance Method Details

#==(other) ⇒ true, false

Check equality of the address to another.

Examples:

Check address equality.

address == other

Parameters:

  • other (Object) —

    The other object.

Returns:

  • (true, false) —

    If the objects are equal.

Since:

  • 2.0.0



103
104
105
106
 
# File 'lib/mongo/address.rb', line 103

def ==(other)
  return false unless other.is_a?(Address)
  host == other.host && port == other.port
end

#eql?(other) ⇒ true, false

Check equality for hashing.

Examples:

Check hashing equality.

address.eql?(other)

Parameters:

  • other (Object) —

    The other object.

Returns:

  • (true, false) —

    If the objects are equal.

Since:

  • 2.2.0



118
119
120
 
# File 'lib/mongo/address.rb', line 118

def eql?(other)
  self == other
end

#hash ⇒ Integer

Calculate the hash value for the address.

Examples:

Calculate the hash value.

address.hash

Returns:

  • (Integer) —

    The hash value.

Since:

  • 2.0.0



130
131
132
 
# File 'lib/mongo/address.rb', line 130

def hash
  [ host, port ].hash
end

#inspect ⇒ String

Get a pretty printed address inspection.

Examples:

Get the address inspection.

address.inspect

Returns:

  • (String) —

    The nice inspection string.

Since:

  • 2.0.0



142
143
144
 
# File 'lib/mongo/address.rb', line 142

def inspect
  "#<Mongo::Address:0x#{object_id} address=#{to_s}>"
end

#socket(socket_timeout, ssl_options = {}, options = {}) ⇒ Mongo::Socket::SSL | Mongo::Socket::TCP | Mongo::Socket::Unix

Get a socket for the address stored in this object, given the options.

If the address stored in this object looks like a Unix path, this method returns a Unix domain socket for this path.

Otherwise, this method attempts to resolve the address stored in this object to IPv4 and IPv6 addresses using Socket#getaddrinfo, then connects to the resulting addresses and returns the socket of the first successful connection. The order in which address families (IPv4/IPV6) are tried is the same order in which the addresses are returned by getaddrinfo, and is determined by the host system.

Name resolution is performed on each socket call. This is done so that any changes to which addresses the host names used as seeds or in server configuration resolve to are immediately noticed by the driver, even if a socket has been connected to the affected host name/address before. However, note that DNS TTL values may still affect when a change to a host address is noticed by the driver.

This method propagates any exceptions raised during DNS resolution and subsequent connection attempts. In case of a host name resolving to multiple IP addresses, the error raised by the last attempt is propagated to the caller. This method does not map exceptions to Mongo::Error subclasses, and may raise any subclass of Exception.

Examples:

Get a socket.

address.socket(5, :ssl => true)

Parameters:

  • socket_timeout (Float) —

    The socket timeout.

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

    SSL options.

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

    The options.

Options Hash (options):

  • :connect_timeout (Float) —

    Connect timeout.

Returns:

Raises:

  • (Exception) —

    If network connection failed.

Since:

  • 2.0.0



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/mongo/address.rb', line 186

def socket(socket_timeout, ssl_options = {}, options = {})
  if seed.downcase =~ Unix::MATCH
    specific_address = Unix.new(seed.downcase)
    return specific_address.socket(socket_timeout, ssl_options, options)
  end

  options = {
    connect_timeout: Server::CONNECT_TIMEOUT,
  }.update(options)

  # When the driver connects to "localhost", it only attempts IPv4
  # connections. When the driver connects to other hosts, it will
  # attempt both IPv4 and IPv6 connections.
  family = (host == LOCALHOST) ? ::Socket::AF_INET : ::Socket::AF_UNSPEC
  error = nil
  # Sometimes Socket#getaddrinfo returns the same info more than once
  # (multiple identical items in the returned array). It does not make
  # sense to try to connect to the same address more than once, thus
  # eliminate duplicates here.
  infos = ::Socket.getaddrinfo(host, nil, family, ::Socket::SOCK_STREAM)
  results = infos.map do |info|
    [info[4], info[3]]
  end.uniq
  results.each do |family, address_str|
    begin
      specific_address = FAMILY_MAP[family].new(address_str, port, host)
      socket = specific_address.socket(socket_timeout, ssl_options, options)
      return socket
    rescue IOError, SystemCallError, Error::SocketTimeoutError, Error::SocketError => e
      error = e
    end
  end
  raise error
end

#to_s ⇒ String

Get the address as a string.

Examples:

Get the address as a string.

address.to_s

Returns:

  • (String) —

    The nice string.

Since:

  • 2.0.0



229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/mongo/address.rb', line 229

def to_s
  if port
    if host.include?(':')
      "[#{host}]:#{port}"
    else
      "#{host}:#{port}"
    end
  else
    host
  end
end