bson 4.15.0 → 5.0.0

data/lib/bson/binary.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,7 +17,6 @@
 require 'base64'
 
 module BSON
-
   # Represents binary data.
   #
   # @see http://bsonspec.org/#/specification
@@ -40,17 +40,21 @@ module BSON
     #
     # @since 2.0.0
     SUBTYPES = {
-      :generic => 0.chr,
-      :function => 1.chr,
-      :old =>  2.chr,
-      :uuid_old => 3.chr,
-      :uuid => 4.chr,
-      :md5 => 5.chr,
-      :ciphertext => 6.chr,
-      :column => 7.chr,
-      :user => 128.chr,
+      generic: 0.chr,
+      function: 1.chr,
+      old: 2.chr,
+      uuid_old: 3.chr,
+      uuid: 4.chr,
+      md5: 5.chr,
+      ciphertext: 6.chr,
+      column: 7.chr,
+      sensitive: 8.chr,
+      user: 128.chr,
     }.freeze
 
+    # The starting point of the user-defined subtype range.
+    USER_SUBTYPE = 0x80
+
     # The mappings of single byte subtypes to their symbol counterparts.
     #
     # @since 2.0.0
@@ -64,10 +68,11 @@ module BSON
     attr_reader :data
 
     # @return [ Symbol ] The binary type.
-    #
-    # @since 2.0.0
     attr_reader :type
 
+    # @return [ String ] The raw type value, as an encoded integer.
+    attr_reader :raw_type
+
     # Determine if this binary object is equal to another object.
     #
     # @example Check the binary equality.
@@ -80,6 +85,7 @@ module BSON
     # @since 2.0.0
     def ==(other)
       return false unless other.is_a?(Binary)
+
       type == other.type && data == other.data
     end
     alias eql? ==
@@ -92,19 +98,16 @@ module BSON
     #
     # @since 2.3.1
     def hash
-      data.hash + type.hash
+      [ data, type ].hash
     end
 
-    # Get the binary as JSON hash data.
-    #
-    # @example Get the binary as a JSON hash.
-    #   binary.as_json
+    # Return a representation of the object for use in
+    # application-level JSON serialization. Since BSON::Binary
+    # is used exclusively in BSON-related contexts, this
+    # method returns the canonical Extended JSON representation.
     #
-    # @return [ Hash ] The binary as a JSON hash.
-    #
-    # @since 2.0.0
-    # @deprecated Use as_extended_json instead.
-    def as_json(*args)
+    # @return [ Hash ] The extended json representation.
+    def as_json(*_args)
       as_extended_json
     end
 
@@ -116,17 +119,15 @@ module BSON
     #
     # @return [ Hash ] The extended json representation.
     def as_extended_json(**options)
-      subtype = SUBTYPES[type].each_byte.map { |c| c.to_s(16) }.join
-      if subtype.length == 1
-        subtype = "0#{subtype}"
-      end
+      subtype = @raw_type.each_byte.map { |c| c.to_s(16) }.join
+      subtype = "0#{subtype}" if subtype.length == 1
 
       value = Base64.encode64(data).strip
 
       if options[:mode] == :legacy
-        { "$binary" => value, "$type" => subtype }
+        { '$binary' => value, '$type' => subtype }
       else
-        { "$binary" => {'base64' => value, "subType" => subtype }}
+        { '$binary' => { 'base64' => value, 'subType' => subtype } }
       end
     end
 
@@ -146,20 +147,17 @@ module BSON
     # @param [ Symbol ] type The binary type.
     #
     # @since 2.0.0
-    def initialize(data = "", type = :generic)
-      validate_type!(type)
-
-      # The Binary class used to force encoding to BINARY when serializing to
-      # BSON. Instead of doing that during serialization, perform this
-      # operation during Binary construction to make it clear that once
-      # the string is given to the Binary, the data is treated as a binary
-      # string and not a text string in any encoding.
-      unless data.encoding == Encoding.find('BINARY')
-        data = data.dup.force_encoding('BINARY')
-      end
+    def initialize(data = '', type = :generic)
+      initialize_instance(data, type)
+    end
 
-      @data = data
-      @type = type
+    # For legacy deserialization support where BSON::Binary objects are
+    # expected to have a specific internal representation (with only
+    # @type and @data instance variables).
+    #
+    # @api private
+    def init_with(coder)
+      initialize_instance(coder['data'], coder['type'])
     end
 
     # Get a nice string for use with object inspection.
@@ -202,37 +200,15 @@ module BSON
     # @api experimental
     def to_uuid(representation = nil)
       if representation.is_a?(String)
-        raise ArgumentError, "Representation must be given as a symbol: #{representation}"
+        raise ArgumentError,
+              "Representation must be given as a symbol: #{representation.inspect}"
       end
+
       case type
       when :uuid
-        if representation && representation != :standard
-          raise ArgumentError, "Binary of type :uuid can only be stringified to :standard representation, requested: #{representation.inspect}"
-        end
-
-        data.split('').map { |n| '%02x' % n.ord }.join.sub(/\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/, '\1-\2-\3-\4-\5')
+        from_uuid_to_uuid(representation || :standard)
       when :uuid_old
-        if representation.nil?
-          raise ArgumentError, 'Representation must be specified for BSON::Binary objects of type :uuid_old'
-        end
-
-        hex = data.split('').map { |n| '%02x' % n.ord }.join
-
-        case representation
-        when :standard
-          raise ArgumentError, 'BSON::Binary objects of type :uuid_old cannot be stringified to :standard representation'
-        when :csharp_legacy
-          hex.sub(/\A(..)(..)(..)(..)(..)(..)(..)(..)(.{16})\z/, '\4\3\2\1\6\5\8\7\9')
-        when :java_legacy
-          hex.sub(/\A(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)\z/) do |m|
-            "#{$8}#{$7}#{$6}#{$5}#{$4}#{$3}#{$2}#{$1}" +
-            "#{$16}#{$15}#{$14}#{$13}#{$12}#{$11}#{$10}#{$9}"
-          end
-        when :python_legacy
-          hex
-        else
-          raise ArgumentError, "Invalid representation: #{representation}"
-        end.sub(/\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/, '\1-\2-\3-\4-\5')
+        from_uuid_old_to_uuid(representation)
       else
         raise TypeError, "The type of Binary must be :uuid or :uuid_old, this object is: #{type.inspect}"
       end
@@ -248,10 +224,10 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       position = buffer.length
       buffer.put_int32(0)
-      buffer.put_byte(SUBTYPES[type])
+      buffer.put_byte(@raw_type)
       buffer.put_int32(data.bytesize) if type == :old
       buffer.put_bytes(data)
       buffer.replace_int32(position, buffer.length - position - 5)
@@ -268,13 +244,19 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer, **options)
+    def self.from_bson(buffer, **_options)
       length = buffer.get_int32
       type_byte = buffer.get_byte
-      type = TYPES[type_byte]
-      if type.nil?
-        raise Error::UnsupportedBinarySubtype,
-          "BSON data contains unsupported binary subtype #{'0x%02x' % type_byte.ord}"
+
+      if type_byte.bytes.first < USER_SUBTYPE
+        type = TYPES[type_byte]
+
+        if type.nil?
+          raise Error::UnsupportedBinarySubtype,
+                "BSON data contains unsupported binary subtype #{'0x%02x' % type_byte.ord}"
+        end
+      else
+        type = type_byte
       end
 
       length = buffer.get_int32 if type == :old
@@ -308,66 +290,166 @@ module BSON
     #
     # @api experimental
     def self.from_uuid(uuid, representation = nil)
-      if representation.is_a?(String)
-        raise ArgumentError, "Representation must be given as a symbol: #{representation}"
+      raise ArgumentError, "Representation must be given as a symbol: #{representation}" if representation.is_a?(String)
+
+      uuid_binary = uuid.delete('-').scan(/../).map(&:hex).map(&:chr).join
+      representation ||= :standard
+
+      handler = :"from_#{representation}_uuid"
+      raise ArgumentError, "Invalid representation: #{representation}" unless respond_to?(handler)
+
+      send(handler, uuid_binary)
+    end
+
+    # Constructs a new binary object from a standard-format binary UUID
+    # representation.
+    #
+    # @param [ String ] uuid_binary the UUID data
+    #
+    # @return [ BSON::Binary ] the Binary object
+    #
+    # @api private
+    def self.from_standard_uuid(uuid_binary)
+      new(uuid_binary, :uuid)
+    end
+
+    # Constructs a new binary object from a csharp legacy-format binary UUID
+    # representation.
+    #
+    # @param [ String ] uuid_binary the UUID data
+    #
+    # @return [ BSON::Binary ] the Binary object
+    #
+    # @api private
+    def self.from_csharp_legacy_uuid(uuid_binary)
+      uuid_binary.sub!(/\A(.)(.)(.)(.)(.)(.)(.)(.)(.{8})\z/, '\4\3\2\1\6\5\8\7\9')
+      new(uuid_binary, :uuid_old)
+    end
+
+    # Constructs a new binary object from a java legacy-format binary UUID
+    # representation.
+    #
+    # @param [ String ] uuid_binary the UUID data
+    #
+    # @return [ BSON::Binary ] the Binary object
+    #
+    # @api private
+    def self.from_java_legacy_uuid(uuid_binary)
+      uuid_binary.sub!(/\A(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)\z/) do
+        (::Regexp.last_match[1..8].reverse + ::Regexp.last_match[9..16].reverse).join
       end
-      uuid_binary = uuid.gsub('-', '').scan(/../).map(&:hex).map(&:chr).join
-      case representation && representation
-      when nil, :standard
-        new(uuid_binary, :uuid)
-      when :csharp_legacy
-        uuid_binary.sub!(/\A(.)(.)(.)(.)(.)(.)(.)(.)(.{8})\z/, '\4\3\2\1\6\5\8\7\9')
-        new(uuid_binary, :uuid_old)
-      when :java_legacy
-        uuid_binary.sub!(/\A(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)\z/) do |m|
-          "#{$8}#{$7}#{$6}#{$5}#{$4}#{$3}#{$2}#{$1}" +
-          "#{$16}#{$15}#{$14}#{$13}#{$12}#{$11}#{$10}#{$9}"
-        end
-        new(uuid_binary, :uuid_old)
-      when :python_legacy
-        new(uuid_binary, :uuid_old)
-      else
-        raise ArgumentError, "Invalid representation: #{representation}"
+      new(uuid_binary, :uuid_old)
+    end
+
+    # Constructs a new binary object from a python legacy-format binary UUID
+    # representation.
+    #
+    # @param [ String ] uuid_binary the UUID data
+    #
+    # @return [ BSON::Binary ] the Binary object
+    #
+    # @api private
+    def self.from_python_legacy_uuid(uuid_binary)
+      new(uuid_binary, :uuid_old)
+    end
+
+    private
+
+    # initializes an instance of BSON::Binary.
+    #
+    # @param [ String ] data the data to initialize the object with
+    # @param [ Symbol ] type the type to assign the binary object
+    def initialize_instance(data, type)
+      @type = validate_type!(type)
+
+      # The Binary class used to force encoding to BINARY when serializing to
+      # BSON. Instead of doing that during serialization, perform this
+      # operation during Binary construction to make it clear that once
+      # the string is given to the Binary, the data is treated as a binary
+      # string and not a text string in any encoding.
+      data = data.dup.force_encoding('BINARY') unless data.encoding == Encoding.find('BINARY')
+
+      @data = data
+    end
+
+    # Converts the Binary UUID object to a UUID of the given representation.
+    # Currently, only :standard representation is supported.
+    #
+    # @param [ Symbol ] representation The representation to target (must be
+    #   :standard)
+    #
+    # @return [ String ] the UUID as a string
+    def from_uuid_to_uuid(representation)
+      if representation != :standard
+        raise ArgumentError,
+              'Binary of type :uuid can only be stringified to :standard representation, ' \
+              "requested: #{representation.inspect}"
       end
+
+      data
+        .chars
+        .map { |n| '%02x' % n.ord }
+        .join
+        .sub(/\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/, '\1-\2-\3-\4-\5')
     end
 
-    # Raised when providing an invalid type to the Binary.
+    # Converts the UUID-old object to a UUID of the given representation.
     #
-    # @since 2.0.0
-    class InvalidType < RuntimeError
-
-      # @!attribute type
-      #   @return [ Object ] The invalid type.
-      #   @since 2.0.0
-      attr_reader :type
-
-      # Instantiate the new error.
-      #
-      # @example Instantiate the error.
-      #   InvalidType.new(:error)
-      #
-      # @param [ Object ] type The invalid type.
-      #
-      # @since 2.0.0
-      def initialize(type)
-        @type = type
+    # @param [ Symbol ] representation The representation to target
+    #
+    # @return [ String ] the UUID as a string
+    def from_uuid_old_to_uuid(representation)
+      if representation.nil?
+        raise ArgumentError, 'Representation must be specified for BSON::Binary objects of type :uuid_old'
       end
 
-      # Get the custom error message for the exception.
-      #
-      # @example Get the message.
-      #   error.message
-      #
-      # @return [ String ] The error message.
-      #
-      # @since 2.0.0
-      def message
-        "#{type.inspect} is not a valid binary type. " +
-          "Please use one of #{SUBTYPES.keys.map(&:inspect).join(", ")}."
+      hex = data.chars.map { |n| '%02x' % n.ord }.join
+      handler = :"from_uuid_old_to_#{representation}_uuid"
+
+      raise ArgumentError, "Invalid representation: #{representation}" unless respond_to?(handler, true)
+
+      send(handler, hex)
+        .sub(/\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/, '\1-\2-\3-\4-\5')
+    end
+
+    # Tries to convert a UUID-old object to a standard representation, which is
+    # not supported.
+    #
+    # @param [ String ] hex The hexadecimal string to convert
+    #
+    # @raise [ ArgumentError ] because standard representation is not supported
+    def from_uuid_old_to_standard_uuid(_hex)
+      raise ArgumentError, 'BSON::Binary objects of type :uuid_old cannot be stringified to :standard representation'
+    end
+
+    # Converts a UUID-old object to a csharp-legacy representation.
+    #
+    # @param [ String ] hex The hexadecimal string to convert
+    #
+    # @return [ String ] the csharp-legacy-formatted UUID
+    def from_uuid_old_to_csharp_legacy_uuid(hex)
+      hex.sub(/\A(..)(..)(..)(..)(..)(..)(..)(..)(.{16})\z/, '\4\3\2\1\6\5\8\7\9')
+    end
+
+    # Converts a UUID-old object to a java-legacy representation.
+    #
+    # @param [ String ] hex The hexadecimal string to convert
+    #
+    # @return [ String ] the java-legacy-formatted UUID
+    def from_uuid_old_to_java_legacy_uuid(hex)
+      hex.sub(/\A(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)\z/) do
+        (::Regexp.last_match[1..8].reverse + ::Regexp.last_match[9..16].reverse).join
       end
     end
 
-    private
+    # Converts a UUID-old object to a python-legacy representation.
+    #
+    # @param [ String ] hex The hexadecimal string to convert
+    #
+    # @return [ String ] the python-legacy-formatted UUID
+    def from_uuid_old_to_python_legacy_uuid(hex)
+      hex
+    end
 
     # Validate the provided type is a valid type.
     #
@@ -376,13 +458,58 @@ module BSON
     # @example Validate the type.
     #   binary.validate_type!(:user)
     #
-    # @param [ Object ] type The provided type.
+    # @param [ Symbol | String | Integer ] type The provided type.
     #
-    # @raise [ InvalidType ] The the type is invalid.
+    # @return [ Symbol ] the symbolic type corresponding to the argument.
+    #
+    # @raise [ BSON::Error::InvalidBinaryType ] The the type is invalid.
     #
     # @since 2.0.0
     def validate_type!(type)
-      raise InvalidType.new(type) unless SUBTYPES.has_key?(type)
+      case type
+      when Integer then validate_integer_type!(type)
+      when String
+        if type.length > 1
+          validate_symbol_type!(type.to_sym)
+        else
+          validate_integer_type!(type.bytes.first)
+        end
+      when Symbol then validate_symbol_type!(type)
+      else raise BSON::Error::InvalidBinaryType, type
+      end
+    end
+
+    # Test that the given integer type is valid.
+    #
+    # @param [ Integer ] type the provided type
+    #
+    # @return [ Symbol ] the symbolic type corresponding to the argument.
+    #
+    # @raise [ BSON::Error::InvalidBinaryType] if the type is invalid.
+    def validate_integer_type!(type)
+      @raw_type = type.chr.force_encoding('BINARY').freeze
+
+      if type < USER_SUBTYPE
+        raise BSON::Error::InvalidBinaryType, type unless TYPES.key?(@raw_type)
+
+        return TYPES[@raw_type]
+      end
+
+      :user
+    end
+
+    # Test that the given symbol type is valid.
+    #
+    # @param [ Symbol ] type the provided type
+    #
+    # @return [ Symbol ] the symbolic type corresponding to the argument.
+    #
+    # @raise [ BSON::Error::InvalidBinaryType] if the type is invalid.
+    def validate_symbol_type!(type)
+      raise BSON::Error::InvalidBinaryType, type unless SUBTYPES.key?(type)
+
+      @raw_type = SUBTYPES[type]
+      type
     end
 
     # Register this type when the module is loaded.

data/lib/bson/boolean.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 # Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

data/lib/bson/code.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 # Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -48,16 +49,13 @@ module BSON
       javascript == other.javascript
     end
 
-    # Get the code as JSON hash data.
+    # Return a representation of the object for use in
+    # application-level JSON serialization. Since BSON::Code
+    # is used exclusively in BSON-related contexts, this
+    # method returns the canonical Extended JSON representation.
     #
-    # @example Get the code as a JSON hash.
-    #   code.as_json
-    #
-    # @return [ Hash ] The code as a JSON hash.
-    #
-    # @since 2.0.0
-    # @deprecated Use as_extended_json instead.
-    def as_json(*args)
+    # @return [ Hash ] The extended json representation.
+    def as_json(*_args)
       as_extended_json
     end
 
@@ -68,7 +66,7 @@ module BSON
     #   (default is canonical extended JSON)
     #
     # @return [ Hash ] The extended json representation.
-    def as_extended_json(**options)
+    def as_extended_json(**_options)
       { "$code" => javascript }
     end
 
@@ -94,7 +92,7 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       buffer.put_string(javascript) # @todo: was formerly to_bson_string
     end
 

data/lib/bson/code_with_scope.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 # Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -52,16 +53,13 @@ module BSON
       javascript == other.javascript && scope == other.scope
     end
 
-    # Get the code with scope as JSON hash data.
+    # Return a representation of the object for use in
+    # application-level JSON serialization. Since BSON::CodeWithScope
+    # is used exclusively in BSON-related contexts, this
+    # method returns the canonical Extended JSON representation.
     #
-    # @example Get the code with scope as a JSON hash.
-    #   code_with_scope.as_json
-    #
-    # @return [ Hash ] The code with scope as a JSON hash.
-    #
-    # @since 2.0.0
-    # @deprecated Use as_extended_json instead.
-    def as_json(*args)
+    # @return [ Hash ] The extended json representation.
+    def as_json(*_args)
       as_extended_json
     end
 
@@ -100,7 +98,7 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       position = buffer.length
       buffer.put_int32(0)
       buffer.put_string(javascript)

data/lib/bson/config.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 # Copyright (C) 2016-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -21,32 +22,5 @@ module BSON
   module Config
     extend self
 
-    # Set the configuration option for BSON to validate keys or not.
-    #
-    # @example Set the config option.
-    #   BSON::Config.validating_keys = true
-    #
-    # @param [ true, false ] value The value to set.
-    #
-    # @return [ true, false ] The value.
-    #
-    # @since 4.1.0
-    def validating_keys=(value)
-      @validating_keys = value
-    end
-
-    # Returns true if BSON will validate the document keys on serialization to
-    # determine if they contain invalid MongoDB values. Invalid keys start with
-    # '$' or contain a '.' in them.
-    #
-    # @example Is BSON validating keys?
-    #   BSON::Config.validating_keys?
-    #
-    # @return [ true, false ] If BSON is validating keys?
-    #
-    # @since 4.1.0
-    def validating_keys?
-      !!(@validating_keys||=nil)
-    end
   end
 end

data/lib/bson/date.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 # Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -45,7 +46,7 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.1.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       buffer.put_int64((jd - DATE_REFERENCE) * MILLISECONDS_IN_DAY)
     end
 

data/lib/bson/date_time.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 # Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -35,7 +36,7 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.1.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       gregorian.to_time.to_bson(buffer)
     end
   end