class Mongo::URI::OptionsMapper
Performs mapping between URI
options and Ruby options.
This class contains:
-
The mapping defining how
URI
options are converted to Ruby options. -
The mapping from downcased
URI
option names to canonical-casedURI
option names. -
Methods to perform conversion of
URI
option values to Ruby option values (the convert_* methods). These generally warn and return nil when input given is invalid. -
Methods to perform conversion of Ruby option values to standardized MongoClient options (revert_* methods). These assume the input is valid and generally do not perform validation.
URI
option names are case insensitive. Ruby options are specified as symbols (though in Client
options use indifferent access).
@api private
Constants
Attributes
@return [ Hash ] The options.
Public Class Methods
Instantates the options mapper.
@option opts [ Logger
] :logger A custom logger to use.
# File lib/mongo/uri/options_mapper.rb, line 43 def initialize(**opts) @options = opts end
Private Class Methods
Simple internal dsl to register a MongoDB URI
option in the URI_OPTION_MAP
.
@param uri_key [String] The MongoDB URI
option to register. @param name [Symbol] The name of the option in the driver. @param extra [Hash] Extra options.
* :group [Symbol] Nested hash where option will go. * :type [Symbol] Name of function to transform value.
# File lib/mongo/uri/options_mapper.rb, line 181 def self.uri_option(uri_key, name, **extra) URI_OPTION_MAP[uri_key.downcase] = { name: name }.update(extra) URI_OPTION_CANONICAL_NAMES[uri_key.downcase] = uri_key end
Public Instance Methods
Adds an option to the uri options hash.
Acquires a target for the option based on group. Transforms the value. Merges the option into the target.
@param [ String ] key URI
option name. @param [ String ] value The value of the option. @param [ Hash ] uri_options The base option target.
# File lib/mongo/uri/options_mapper.rb, line 59 def add_uri_option(key, value, uri_options) strategy = URI_OPTION_MAP[key.downcase] if strategy.nil? log_warn("Unsupported URI option '#{key}' on URI '#{@string}'. It will be ignored.") return end group = strategy[:group] target = if group uri_options[group] || {} else uri_options end value = apply_transform(key, value, strategy[:type]) # Sometimes the value here would be nil, for example if we are processing # read preference tags or auth mechanism properties and all of the # data within is invalid. Ignore such options. unless value.nil? merge_uri_option(target, value, strategy[:name]) end if group && !target.empty? && !uri_options.key?(group) uri_options[group] = target end end
Converts Ruby options provided to “standardized MongoClient options”.
@param [ Hash ] opts Ruby options to convert.
@return [ Hash ] Standardized MongoClient options.
# File lib/mongo/uri/options_mapper.rb, line 90 def ruby_to_smc(opts) rv = {} URI_OPTION_MAP.each do |uri_key, spec| if spec[:group] v = opts[spec[:group]] v = v && v[spec[:name]] else v = opts[spec[:name]] end unless v.nil? if spec[:type] v = send("revert_#{spec[:type]}", v) end canonical_key = URI_OPTION_CANONICAL_NAMES[uri_key] unless canonical_key raise ArgumentError, "Option #{uri_key} is not known" end rv[canonical_key] = v end end # For options that default to true, remove the value if it is true. %w(retryReads retryWrites).each do |k| if rv[k] rv.delete(k) end end # Remove auth source when it is $external for mechanisms that default # (or require) that auth source. if %w(MONGODB-AWS).include?(rv['authMechanism']) && rv['authSource'] == '$external' rv.delete('authSource') end # ssl and tls are aliases, remove ssl ones rv.delete('ssl') # TODO remove authSource if it is the same as the database, # requires this method to know the database specified in the client. rv end
Private Instance Methods
Applies URI
value transformation by either using the default cast or a transformation appropriate for the given type.
@param key [String] URI
option name. @param value [String] The value to be transformed. @param type [Symbol] The transform method.
# File lib/mongo/uri/options_mapper.rb, line 136 def apply_transform(key, value, type) if type send("convert_#{type}", key, value) else value end end
Extract values from the string and put them into an array.
@param [ String ] name Name of the URI
option being processed. @param [ String ] value The string to build an array from.
@return [ Array ] The array built from the string.
# File lib/mongo/uri/options_mapper.rb, line 373 def convert_array(name, value) value.split(',') end
Authentication mechanism transformation.
@param [ String ] name Name of the URI
option being processed. @param value [String] The authentication mechanism.
@return [Symbol] The transformed authentication mechanism.
# File lib/mongo/uri/options_mapper.rb, line 387 def convert_auth_mech(name, value) (AUTH_MECH_MAP[value.upcase] || value).tap do |mech| log_warn("#{value} is not a valid auth mechanism") unless mech end end
Auth
mechanism properties extractor.
@param [ String ] name Name of the URI
option being processed. @param value [ String ] The auth mechanism properties string.
@return [ Hash ] The auth mechanism properties hash.
# File lib/mongo/uri/options_mapper.rb, line 410 def convert_auth_mech_props(name, value) properties = hash_extractor('authMechanismProperties', value) if properties properties.each do |k, v| if k.to_s.downcase == 'canonicalize_host_name' && v properties[k] = (v.downcase == 'true') end end end properties end
Converts value
to a boolean.
Returns true for ‘true’, false for ‘false’, otherwise nil.
@param [ String ] name Name of the URI
option being processed. @param value [ String ] URI
option value.
@return [ true | false | nil ] Converted value.
# File lib/mongo/uri/options_mapper.rb, line 252 def convert_bool(name, value) case value when "true", 'TRUE' true when "false", 'FALSE' false else log_warn("invalid boolean option for #{name}: #{value}") nil end end
Converts value
into an integer.
If the value is not a valid integer, warns and returns nil.
@param [ String ] name Name of the URI
option being processed. @param value [ String ] URI
option value.
@return [ nil | Integer ] Converted value.
# File lib/mongo/uri/options_mapper.rb, line 312 def convert_integer(name, value) unless /\A\d+\z/ =~ value log_warn("#{value} is not a valid integer for #{name}") return nil end value.to_i end
Parses a boolean value and returns its inverse.
@param [ String ] name Name of the URI
option being processed. @param value [ String ] The URI
option value.
@return [ true | false | nil ] The inverse of the boolean value parsed out, otherwise nil
(and a warning will be logged).
# File lib/mongo/uri/options_mapper.rb, line 290 def convert_inverse_bool(name, value) b = convert_bool(name, value) if b.nil? nil else !b end end
Parses the max staleness value, which must be either “0” or an integer greater or equal to 90.
@param [ String ] name Name of the URI
option being processed. @param value [ String ] The max staleness string.
@return [ Integer | nil ] The max staleness integer parsed out if it is valid, otherwise nil
(and a warning will be logged).
# File lib/mongo/uri/options_mapper.rb, line 434 def convert_max_staleness(name, value) if /\A-?\d+\z/ =~ value int = value.to_i if int == -1 int = nil end if int && (int >= 0 && int < 90 || int < 0) log_warn("max staleness should be either 0 or greater than 90: #{value}") int = nil end return int end log_warn("Invalid max staleness value: #{value}") nil end
Ruby’s convention is to provide timeouts in seconds, not milliseconds and to use fractions where more precision is necessary. The connection string options are always in MS so we provide an easy conversion type.
@param [ String ] name Name of the URI
option being processed. @param [ Integer ] value The millisecond value.
@return [ Float ] The seconds value.
@since 2.0.0
# File lib/mongo/uri/options_mapper.rb, line 335 def convert_ms(name, value) unless /\A-?\d+(\.\d+)?\z/ =~ value log_warn("Invalid ms value for #{name}: #{value}") return nil end if value[0] == '-' log_warn("#{name} cannot be a negative number") return nil end value.to_f / 1000 end
Read preference mode transformation.
@param [ String ] name Name of the URI
option being processed. @param value [String] The read mode string value.
@return [Symbol] The read mode symbol.
# File lib/mongo/uri/options_mapper.rb, line 464 def convert_read_mode(name, value) READ_MODE_MAP[value.downcase] || value end
Read preference tag set extractor.
@param [ String ] name Name of the URI
option being processed. @param value [String] The tag set string.
@return [Hash] The tag set hash.
# File lib/mongo/uri/options_mapper.rb, line 497 def convert_read_set(name, value) hash_extractor('readPreferenceTags', value) end
Converts the value into a boolean and returns it wrapped in an array.
@param name [ String ] Name of the URI
option being processed. @param value [ String ] URI
option value.
@return [ Array<true | false> ] The boolean value parsed and wraped
in an array.
# File lib/mongo/uri/options_mapper.rb, line 275 def convert_repeated_bool(name, value) [convert_bool(name, value)] end
Converts value
as a write concern.
If value
is the word “majority”, returns the symbol :majority. If value
is a number, returns the number as an integer. Otherwise returns the string value
unchanged.
@param [ String ] name Name of the URI
option being processed. @param value [ String ] URI
option value.
@return [ Integer | Symbol
| String ] Converted value.
# File lib/mongo/uri/options_mapper.rb, line 511 def convert_w(name, value) case value when 'majority' :majority when /\A[0-9]+\z/ value.to_i else value end end
Parses the zlib compression level.
@param [ String ] name Name of the URI
option being processed. @param value [ String ] The zlib compression level string.
@return [ Integer | nil ] The compression level value if it is between -1 and 9 (inclusive),
otherwise nil (and a warning will be logged).
# File lib/mongo/uri/options_mapper.rb, line 538 def convert_zlib_compression_level(name, value) if /\A-?\d+\z/ =~ value i = value.to_i if i >= -1 && i <= 9 return i end end log_warn("#{value} is not a valid zlibCompressionLevel") nil end
Extract values from the string and put them into a nested hash.
@param [ String ] name Name of the URI
option being processed. @param value [ String ] The string to build a hash from.
@return [ Hash ] The hash built from the string.
# File lib/mongo/uri/options_mapper.rb, line 561 def hash_extractor(name, value) h = {} value.split(',').each do |tag| k, v = tag.split(':') if v.nil? log_warn("Invalid hash value for #{name}: key `#{k}` does not have a value: #{value}") next end h[k.to_sym] = v end if h.empty? nil else h end end
Merges a new option into the target.
If the option exists at the target destination the merge will be an addition.
Specifically required to append an additional tag set to the array of tag sets without overwriting the original.
@param target [Hash] The destination. @param value [Object] The value to be merged. @param name [Symbol] The name of the option.
# File lib/mongo/uri/options_mapper.rb, line 155 def merge_uri_option(target, value, name) if target.key?(name) if REPEATABLE_OPTIONS.include?(name) target[name] += value else log_warn("Repeated option key: #{name}.") end else target.merge!(name => value) end end
# File lib/mongo/uri/options_mapper.rb, line 377 def revert_array(value) value end
# File lib/mongo/uri/options_mapper.rb, line 393 def revert_auth_mech(value) found = AUTH_MECH_MAP.detect do |k, v| v == value end if found found.first else raise ArgumentError, "Unknown auth mechanism #{value}" end end
# File lib/mongo/uri/options_mapper.rb, line 422 def revert_auth_mech_props(value) value end
# File lib/mongo/uri/options_mapper.rb, line 264 def revert_bool(value) value end
# File lib/mongo/uri/options_mapper.rb, line 321 def revert_integer(value) value end
# File lib/mongo/uri/options_mapper.rb, line 300 def revert_inverse_bool(value) !value end
# File lib/mongo/uri/options_mapper.rb, line 454 def revert_max_staleness(value) value end
# File lib/mongo/uri/options_mapper.rb, line 349 def revert_ms(value) (value * 1000).round end
# File lib/mongo/uri/options_mapper.rb, line 468 def revert_read_mode(value) value.to_s.gsub(/_(\w)/) { $1.upcase } end
# File lib/mongo/uri/options_mapper.rb, line 279 def revert_repeated_bool(value) value end
# File lib/mongo/uri/options_mapper.rb, line 363 def revert_symbol(value) value.to_s end
# File lib/mongo/uri/options_mapper.rb, line 522 def revert_w(value) case value when Symbol value.to_s else value end end
# File lib/mongo/uri/options_mapper.rb, line 551 def revert_zlib_compression_level(value) value end