Class: Mongo::Address

Relationships & Source Files
Namespace Children
Modules: `Validator`
Classes: `IPv4`, `IPv6`, `Unix`
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Forwardable
Inherits:	Object
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

Constant Summary

FAMILY_MAP =

Mapping from socket family to resolver class.

Since:

2.0.0

# File 'lib/mongo/address.rb', line 33

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

LOCALHOST =

The localhost constant.
Since:
- 2.1.0
# File 'lib/mongo/address.rb', line 42
```
'localhost'
```

Class Method Summary

.new(seed, options = {}) ⇒ Address constructor

Initialize the address.

Instance Attribute Summary

#host ⇒ String readonly
#options readonly Internal use only Internal use only
#port ⇒ Integer readonly
#seed ⇒ String readonly

Instance Method Summary

#==(other) ⇒ true, false

Check equality of the address to another.
#eql?(other) ⇒ true, false

Check equality for hashing.
#hash ⇒ Integer

Calculate the hash value for the address.
#inspect ⇒ String

Get a pretty printed address inspection.
#socket(socket_timeout, opts = {}) ⇒ Mongo::Socket::SSL | Mongo::Socket::TCP | Mongo::Socket::Unix Internal use only Internal use only

Get a socket for the address stored in this object, given the options.
#to_s ⇒ String

Get the address as a string.
#getaddrinfo(host, family) private

This is a simple wrapper around Socket.getaddrinfo added to make testing easier.
#map_exceptions(csot) private

Maps some errors to different ones, mostly low-level errors to driver level errors.
#parse_host_port private

Constructor Details

.new(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.

Raises:

(ArgumentError)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/address.rb', line 73


def initialize(seed, options = {})
  raise ArgumentError, 'address must be not nil' if seed.nil?

  @seed = seed
  @host, @port = parse_host_port
  @options = Hash[options.map { |k, v| [ k.to_sym, v ] }]
end

Instance Attribute Details

#host ⇒ `String` (readonly)

Returns:

(String) —

host The original host name.

Since:

2.0.0

[ GitHub ]

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


attr_reader :host

#options (readonly)

This method is for internal use only.

Since:

2.0.0

[ GitHub ]

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


attr_reader :options

#port ⇒ `Integer` (readonly)

Returns:

(Integer) —

port The port.

Since:

2.0.0

[ GitHub ]

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


attr_reader :port

#seed ⇒ `String` (readonly)

Returns:

(String) —

seed The seed address.

Since:

2.0.0

[ GitHub ]

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


attr_reader :seed

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

[ GitHub ]

# 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

[ GitHub ]

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


def eql?(other)
  self == other
end

#getaddrinfo(host, family) (private)

This is a simple wrapper around Socket.getaddrinfo added to make testing easier.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/address.rb', line 277


def getaddrinfo(host, family)
  ::Socket.getaddrinfo(host, nil, family, ::Socket::SOCK_STREAM)
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

[ GitHub ]

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


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

[ GitHub ]

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


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

#map_exceptions(csot) (private)

Maps some errors to different ones, mostly low-level errors to driver level errors

Parameters:

csot (Boolean) —

Whether the client-side operation timeout should be considered when connecting the socket.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/address.rb', line 295


def map_exceptions(csot)
  yield
rescue Errno::ETIMEDOUT => e
  raise Error::TimeoutError, "#{e.class}: #{e} (for #{self})" if csot

  raise Error::SocketTimeoutError, "#{e.class}: #{e} (for #{self})"
rescue Error::SocketTimeoutError => e
  raise Error::TimeoutError, "#{e.class}: #{e} (for #{self})" if csot

  raise e
rescue IOError, SystemCallError, ::SocketError => e
  raise Error::SocketError, "#{e.class}: #{e} (for #{self})"
rescue OpenSSL::SSL::SSLError => e
  raise Error::SocketError, "#{e.class}: #{e} (for #{self})"
end

#parse_host_port (private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/address.rb', line 281


def parse_host_port
  address = seed.downcase
  case address
  when Unix::MATCH then Unix.parse(address)
  when IPv6::MATCH then IPv6.parse(address)
  else IPv4.parse(address)
  end
end

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

This method is for internal use only.

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

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

Otherwise, this method attempts to resolve the address stored in this object to Address::IPv4 and Address::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 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.
opts (Hash) (defaults to: {}) —

The options.

Options Hash (opts):

:connect_timeout (Float) —

Connect timeout.
:csot (Boolean) —

Whether the client-side operation timeout should be considered when connecting the socket. This option influences only what errors will be raised if timeout expires.
:ssl (true | false) —

Whether to use SSL.
:ssl_ca_cert (String) —

Same as the corresponding Client/Socket::SSL option.
:ssl_ca_cert_object (Array<OpenSSL::X509::Certificate>) —

Same as the corresponding Client/Socket::SSL option.
:ssl_ca_cert_string (String) —

Same as the corresponding Client/Socket::SSL option.
:ssl_cert (String) —

Same as the corresponding Client/Socket::SSL option.
:ssl_cert_object (OpenSSL::X509::Certificate) —

Same as the corresponding Client/Socket::SSL option.
:ssl_cert_string (String) —

Same as the corresponding Client/Socket::SSL option.
:ssl_key (String) —

Same as the corresponding Client/Socket::SSL option.
:ssl_key_object (OpenSSL::PKey) —

Same as the corresponding Client/Socket::SSL option.
:ssl_key_pass_phrase (String) —

Same as the corresponding Client/Socket::SSL option.
:ssl_key_string (String) —

Same as the corresponding Client/Socket::SSL option.
:ssl_verify (true, false) —

Same as the corresponding Client/Socket::SSL option.
:ssl_verify_certificate (true, false) —

Same as the corresponding Client/Socket::SSL option.
:ssl_verify_hostname (true, false) —

Same as the corresponding Client/Socket::SSL option.

Returns:

(Mongo::Socket::SSL | Mongo::Socket::TCP | Mongo::Socket::Unix) —

The socket.

Raises:

(Mongo::Error) —

If network connection failed.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/address.rb', line 217


def socket(socket_timeout, opts = {})
  csot = !!opts[:csot]
  opts = {
    connect_timeout: Server::CONNECT_TIMEOUT,
  }.update(options).update(Hash[opts.map { |k, v| [ k.to_sym, v ] }])

  map_exceptions(csot) do
    if Unix::MATCH.match?(seed.downcase)
      specific_address = Unix.new(seed.downcase)
      return specific_address.socket(socket_timeout, opts)
    end

    # 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 = getaddrinfo(host, family)
    results = infos.map do |info|
      [ info[4], info[3] ]
    end.uniq
    results.each do |family, address_str|
      specific_address = FAMILY_MAP[family].new(address_str, port, host)
      socket = specific_address.socket(socket_timeout, opts)
      return socket
    rescue IOError, SystemCallError, Error::SocketTimeoutError, Error::SocketError => e
      error = e
    end
    raise error
  end
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

[ GitHub ]

# File 'lib/mongo/address.rb', line 261


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

Class: Mongo::Address

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(seed, options = {}) ⇒ Address

Instance Attribute Details

#host ⇒ String (readonly)

#options (readonly)

#port ⇒ Integer (readonly)

#seed ⇒ String (readonly)

Instance Method Details

#==(other) ⇒ true, false

#eql?(other) ⇒ true, false

#getaddrinfo(host, family) (private)

#hash ⇒ Integer

#inspect ⇒ String

#map_exceptions(csot) (private)

#parse_host_port (private)

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

#to_s ⇒ String

.new(seed, options = {}) ⇒ `Address`

#host ⇒ `String` (readonly)

#port ⇒ `Integer` (readonly)

#seed ⇒ `String` (readonly)

#==(other) ⇒ `true`, `false`

#eql?(other) ⇒ `true`, `false`

#hash ⇒ `Integer`

#inspect ⇒ `String`

#to_s ⇒ `String`