Class: Mongo::URI

Inherits:
Object
  • Object
show all
Includes:
Address::Validator, Loggable
Defined in:
lib/mongo/uri.rb,
lib/mongo/uri/srv_protocol.rb,
lib/mongo/uri/options_mapper.rb

Overview

The URI class provides a way for users to parse the MongoDB uri as defined in the connection string format spec.

https://www.mongodb.com/docs/manual/reference/connection-string/

Examples:

Use the uri string to make a client connection.

uri = Mongo::URI.new('mongodb://localhost:27017')
client = Mongo::Client.new(uri.servers, uri.options)
client.(uri.credentials)
client[uri.database]

Since:

  • 2.0.0

Defined Under Namespace

Classes: OptionsMapper, SRVProtocol

Constant Summary collapse

SCHEME =
Deprecated.

Will be removed in 3.0.

The mongodb connection string scheme.

Since:

  • 2.0.0

'mongodb://'
MONGODB_SCHEME =

The mongodb connection string scheme root.

Since:

  • 2.5.0

'mongodb'
MONGODB_SRV_SCHEME =

The mongodb srv protocol connection string scheme root.

Since:

  • 2.5.0

'mongodb+srv'
INVALID_SCHEME =
Deprecated.

Error details for an invalid scheme.

Since:

  • 2.1.0

"Invalid scheme. Scheme must be '#{MONGODB_SCHEME}' or '#{MONGODB_SRV_SCHEME}'"
FORMAT =

MongoDB URI format specification.

Since:

  • 2.0.0

'mongodb://[username:password@]host1[:port1][,host2[:port2]' +
',...[,hostN[:portN]]][/[database][?options]]'
HELP =

MongoDB URI (connection string) documentation url

Since:

  • 2.0.0

'https://www.mongodb.com/docs/manual/reference/connection-string/'
UNSAFE =

Unsafe characters that must be urlencoded.

Since:

  • 2.1.0

%r{[:/@]}
PERCENT_CHAR =

Percent sign that must be encoded in user creds.

Since:

  • 2.5.1

/%/
UNIX_SOCKET =

Unix socket suffix.

Since:

  • 2.1.0

/.sock/
HOST_DELIM =

The character delimiting hosts.

Since:

  • 2.1.0

','
HOST_PORT_DELIM =

The character separating a host and port.

Since:

  • 2.1.0

':'
DATABASE_DELIM =

The character delimiting a database.

Since:

  • 2.1.0

'/'
URI_OPTS_DELIM =

The character delimiting options.

Since:

  • 2.1.0

'?'
INDIV_URI_OPTS_DELIM =
Deprecated.

The character delimiting multiple options.

Since:

  • 2.1.0

'&'
URI_OPTS_VALUE_DELIM =

The character delimiting an option and its value.

Since:

  • 2.1.0

'='
AUTH_USER_PWD_DELIM =

The character separating a username from the password.

Since:

  • 2.1.0

':'
AUTH_DELIM =

The character delimiting auth credentials.

Since:

  • 2.1.0

'@'
SCHEME_DELIM =

Scheme delimiter.

Since:

  • 2.5.0

'://'
CREDENTIALS_PLACEHOLDER =

Placeholder used in place of cleartext credentials when a URI is rendered for display, logging, or error reporting.

Since:

  • 2.0.0

'<credentials>'
USERINFO_REDACTION_REGEX =

Pattern matching the userinfo portion of a MongoDB connection string. Anchors at the start and is bounded to the authority component (stops at the first '/', '?', or '#'), but matches greedily up to the last '@' in that component so passwords containing an unescaped '@' are still fully redacted. Case-insensitive so an unusual scheme like 'MongoDB://' is redacted too — the parser will reject it, and the redactor must not be the thing that leaks the credentials in the resulting error.

Since:

  • 2.0.0

%r{\A(mongodb(?:\+srv)?://)[^/?#]*@}i.freeze
INVALID_OPTS_VALUE_DELIM =

Error details for an invalid options format.

Since:

  • 2.1.0

'Options and their values must be delimited' +
" by '#{URI_OPTS_VALUE_DELIM}'"
UNESCAPED_USER_PWD =

Error details for an non-urlencoded user name or password.

Since:

  • 2.1.0

'User name and password must be urlencoded.'
UNESCAPED_UNIX_SOCKET =

Error details for a non-urlencoded unix socket path.

Since:

  • 2.1.0

'UNIX domain sockets must be urlencoded.'
UNESCAPED_DATABASE =

Error details for a non-urlencoded auth database name.

Since:

  • 2.1.0

'Auth database must be urlencoded.'
INVALID_OPTS_DELIM =

Error details for providing options without a database delimiter.

Since:

  • 2.1.0

"Database delimiter '#{DATABASE_DELIM}' must be present if options are specified."
INVALID_HOST =

Error details for a missing host.

Since:

  • 2.1.0

'Missing host; at least one must be provided.'
INVALID_PORT =

Error details for an invalid port.

Since:

  • 2.1.0

'Invalid port. Port must be an integer greater than 0 and less than 65536'
READ_MODE_MAP =

Map of URI read preference modes to Ruby driver read preference modes

Since:

  • 2.0.0

{
  'primary' => :primary,
  'primarypreferred' => :primary_preferred,
  'secondary' => :secondary,
  'secondarypreferred' => :secondary_preferred,
  'nearest' => :nearest
}.freeze
AUTH_MECH_MAP =

Map of URI authentication mechanisms to Ruby driver mechanisms

Since:

  • 2.0.0

{
  'GSSAPI' => :gssapi,
  'MONGODB-AWS' => :aws,
  # MONGODB-CR is deprecated and will be removed in driver version 3.0
  'MONGODB-CR' => :mongodb_cr,
  'MONGODB-X509' => :mongodb_x509,
  'PLAIN' => :plain,
  'SCRAM-SHA-1' => :scram,
  'SCRAM-SHA-256' => :scram256,
}.freeze
SERVER_MONITORING_MODES =

Valid values for the serverMonitoringMode URI option.

Since:

  • 2.0.0

%w[stream poll auto].freeze
REPEATABLE_OPTIONS =

Options that are allowed to appear more than once in the uri.

In order to follow the URI options spec requirement that all instances of 'tls' and 'ssl' have the same value, we need to keep track of all of the values passed in for those options. Assuming they don't conflict, they will be condensed to a single value immediately after parsing the URI.

Since:

  • 2.1.0

%i[tag_sets ssl]

Constants included from Loggable

Loggable::PREFIX

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Address::Validator

#validate_address_str!

Methods included from Loggable

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

Constructor Details

#initialize(string, options = {}) ⇒ URI

Create the new uri from the provided string.

Examples:

Create the new URI.

URI.new('mongodb://localhost:27017')

Parameters:

  • string (String) —

    The URI to parse.

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

    The options.

Options Hash (options):

  • :logger (Logger) —

    A custom logger to use.

Raises:

Since:

  • 2.0.0



313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/mongo/uri.rb', line 313

def initialize(string, options = {})
  raise Error::InvalidURI.new(string, 'URI must be a string, not nil.') unless string
  raise Error::InvalidURI.new(string, 'Cannot parse an empty URI.') if string.empty?

  @string = string
  @options = options
  parsed_scheme, _, remaining = string.partition(SCHEME_DELIM)
  unless parsed_scheme == scheme
    raise_invalid_error!("Invalid scheme '#{parsed_scheme}'. Scheme must be '#{MONGODB_SCHEME}'. Use URI#get to parse SRV URIs.")
  end
  raise_invalid_error!('No hosts in the URI') if remaining.empty?
  parse!(remaining)
  validate_uri_options!
end

Instance Attribute Details

#options ⇒ Object (readonly)

The uri parser object options.

Since:

  • 2.0.0



37
38
39
 
# File 'lib/mongo/uri.rb', line 37

def options
  @options
end

#servers ⇒ Object (readonly)

The servers specified in the uri.

Since:

  • 2.0.0



47
48
49
 
# File 'lib/mongo/uri.rb', line 47

def servers
  @servers
end

#uri_options ⇒ Object (readonly)

Mongo::Options::Redacted of the options specified in the uri.

Since:

  • 2.1.0



42
43
44
 
# File 'lib/mongo/uri.rb', line 42

def uri_options
  @uri_options
end

Class Method Details

.get(string, opts = {}) ⇒ URI, URI::SRVProtocol

Get either a URI object or a SRVProtocol URI object.

Examples:

Get the uri object.

URI.get(string)

Parameters:

  • string (String) —

    The URI to parse.

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

    The options.

  • options (Hash) —

    a customizable set of options

Returns:

Raises:

Since:

  • 2.5.0



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/mongo/uri.rb', line 262

def self.get(string, opts = {})
  raise Error::InvalidURI.new(string, 'URI must be a string, not nil.') unless string
  raise Error::InvalidURI.new(string, 'Cannot parse an empty URI.') if string.empty?

  scheme, = string.partition(SCHEME_DELIM)
  case scheme
  when MONGODB_SCHEME
    URI.new(string, opts)
  when MONGODB_SRV_SCHEME
    SRVProtocol.new(string, opts)
  else
    raise Error::InvalidURI.new(string,
                                "Invalid scheme '#{scheme}'. Scheme must be '#{MONGODB_SCHEME}' or '#{MONGODB_SRV_SCHEME}'")
  end
end

.redact(string) ⇒ String

Replace the userinfo portion of a MongoDB connection string with a placeholder so the result can safely be logged, displayed, or embedded in an exception message.

The input is matched as a string, not parsed, so this is safe to call on malformed URIs (which is exactly when InvalidURI is raised).

Parameters:

  • string (String) —

    The raw URI string.

Returns:

  • (String) —

    The URI with any userinfo replaced by CREDENTIALS_PLACEHOLDER, or the input unchanged if it is not a string or has no userinfo.

Since:

  • 2.0.0



243
244
245
246
247
 
# File 'lib/mongo/uri.rb', line 243

def self.redact(string)
  return string unless string.is_a?(String)

  string.sub(USERINFO_REDACTION_REGEX, "\\1#{CREDENTIALS_PLACEHOLDER}@")
end

Instance Method Details

#client_options ⇒ Mongo::Options::Redacted

Gets the options hash that needs to be passed to a Mongo::Client on instantiation, so we don't have to merge the credentials and database in at that point - we only have a single point here.

Examples:

Get the client options.

uri.client_options

Returns:

Since:

  • 2.0.0



288
289
290
291
292
293
294
 
# File 'lib/mongo/uri.rb', line 288

def client_options
  opts = uri_options.tap do |opts|
    opts[:database] = @database if @database
  end

  @user ? opts.merge(credentials) : opts
end

#credentials ⇒ Hash

Get the credentials provided in the URI.

Examples:

Get the credentials.

uri.credentials

Returns:

  • (Hash) —

    The credentials.

    • :user [ String ] The user.
    • :password [ String ] The provided password.

Since:

  • 2.0.0



338
339
340
 
# File 'lib/mongo/uri.rb', line 338

def credentials
  { user: @user, password: @password }
end

#database ⇒ String

Get the database provided in the URI.

Examples:

Get the database.

uri.database

Returns:

  • (String) —

    The database.

Since:

  • 2.0.0



350
351
352
 
# File 'lib/mongo/uri.rb', line 350

def database
  @database || Database::ADMIN
end

#inspect ⇒ String

Return a redacted, human-readable representation of the URI. The default Object#inspect would dump @string and @password as instance variables, leaking credentials.

Returns:

  • (String) —

    The redacted inspect string.

Since:

  • 2.0.0



373
374
375
 
# File 'lib/mongo/uri.rb', line 373

def inspect
  "#<#{self.class.name}: #{reconstruct_uri}>"
end

#srv_records ⇒ Object

Since:

  • 2.0.0



296
297
298
 
# File 'lib/mongo/uri.rb', line 296

def srv_records
  nil
end

#to_s ⇒ String

Get the uri as a string with any credentials redacted.

Credentials are replaced with CREDENTIALS_PLACEHOLDER so the result is safe to log or display. Use #credentials to recover the original user and password.

Examples:

Get the uri as a string.

uri.to_s

Returns:

  • (String) —

    The redacted uri string.

Since:

  • 2.0.0



364
365
366
 
# File 'lib/mongo/uri.rb', line 364

def to_s
  reconstruct_uri
end