bson 4.1.1 → 5.2.0

data/lib/bson/hash.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,41 +14,32 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# The top-level BSON module.
 module BSON
-
   # Injects behaviour for encoding and decoding hashes to
   # and from raw bytes as specified by the BSON spec.
   #
   # @see http://bsonspec.org/#/specification
-  #
-  # @since 2.0.0
   module Hash
-
-    # An hash (embedded document) is type 0x03 in the BSON spec.
-    #
-    # @since 2.0.0
-    BSON_TYPE = 3.chr.force_encoding(BINARY).freeze
+    # A hash, also called an embedded document, is type 0x03 in the BSON spec.
+    BSON_TYPE = ::String.new(3.chr, encoding: BINARY).freeze
 
     # Get the hash as encoded BSON.
     #
     # @example Get the hash as encoded BSON.
     #   { "field" => "value" }.to_bson
     #
-    # @return [ String ] The encoded string.
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
     # @see http://bsonspec.org/#/specification
-    #
-    # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      position = buffer.length
-      buffer.put_int32(0)
-      each do |field, value|
-        buffer.put_byte(value.bson_type)
-        buffer.put_cstring(field.to_bson_key(validating_keys))
-        value.to_bson(buffer, validating_keys)
+    def to_bson(buffer = ByteBuffer.new)
+      # If the native buffer version has an optimized version, we'll call
+      # it directly. Otherwise, we'll serialize the hash the hard way.
+      if buffer.respond_to?(:put_hash)
+        buffer.put_hash(self)
+      else
+        serialize_to_buffer(buffer)
       end
-      buffer.put_byte(NULL_BYTE)
-      buffer.replace_int32(position, buffer.length - position)
     end
 
     # Converts the hash to a normalized value in a BSON document.
@@ -54,44 +47,166 @@ module BSON
     # @example Convert the hash to a normalized value.
     #   hash.to_bson_normalized_value
     #
-    # @return [ BSON::Document ] The normazlied hash.
-    #
-    # @since 3.0.0
+    # @return [ BSON::Document ] The normalized hash.
     def to_bson_normalized_value
       Document.new(self)
     end
 
-    module ClassMethods
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
+    #
+    # This method recursively invokes +as_extended_json+ with the provided
+    # options on each hash value.
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] This hash converted to extended json representation.
+    def as_extended_json(**options)
+      transform_values { |value| value.as_extended_json(**options) }
+    end
+
+    private
+
+    # Serialize this hash instance to the given buffer.
+    #
+    # @param [ ByteBuf ] buffer The buffer to receive the serialized hash.
+    def serialize_to_buffer(buffer)
+      position = buffer.length
+      buffer.put_int32(0)
+      serialize_key_value_pairs(buffer)
+      buffer.put_byte(NULL_BYTE)
+      buffer.replace_int32(position, buffer.length - position)
+    end
+
+    # Serialize the key/value pairs in this hash instance to the given
+    # buffer.
+    #
+    # @param [ ByteBuf ] buffer The buffer to received the serialized
+    #   key/value pairs.
+    #
+    # @raise [ Error::UnserializableClass ] if a value cannot be serialized
+    def serialize_key_value_pairs(buffer)
+      each do |field, value|
+        unless value.respond_to?(:bson_type)
+          raise Error::UnserializableClass,
+                "Hash value for key '#{field}' does not define its BSON serialized type: #{value}"
+        end
 
+        buffer.put_byte(value.bson_type)
+        key = field.to_bson_key
+        serialize_key(buffer, key)
+        value.to_bson(buffer)
+      end
+    end
+
+    # Serialize the key/value pairs in this hash instance to the given
+    # buffer.
+    #
+    # @param [ ByteBuf ] buffer The buffer to received the serialized
+    #   key/value pairs.
+    #
+    # @raise [ ArgumentError ] if the string cannot be serialized
+    # @raise [ EncodingError ] if the string is not a valid encoding
+    def serialize_key(buffer, key)
+      buffer.put_cstring(key)
+    rescue ArgumentError => e
+      raise ArgumentError, "Error serializing key #{key}: #{e.class}: #{e}"
+    rescue EncodingError => e
+      # Note this may convert exception class from a subclass of
+      # EncodingError to EncodingError itself
+      raise EncodingError, "Error serializing key #{key}: #{e.class}: #{e}"
+    end
+
+    # The methods to augment the Hash class with (class-level methods).
+    module ClassMethods
       # Deserialize the hash from BSON.
       #
+      # @note If the argument cannot be parsed, an exception will be raised
+      #   and the argument will be left in an undefined state. The caller
+      #   must explicitly call `rewind` on the buffer before trying to parse
+      #   it again.
+      #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
-      # @return [ Array ] The decoded hash.
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
+      # @return [ Hash ] The decoded hash.
       #
       # @see http://bsonspec.org/#/specification
+      def from_bson(buffer, **options)
+        if buffer.respond_to?(:get_hash)
+          buffer.get_hash(**options)
+        else
+          hash = parse_hash_from_buffer(buffer, **options)
+          maybe_dbref(hash)
+        end
+      end
+
+      private
+
+      # If the hash looks like a DBRef, try and decode it as such. If
+      # is turns out to be invalid--or if it doesn't look like a DBRef
+      # to begin with--return the hash itself.
       #
-      # @since 2.0.0
-      def from_bson(buffer)
+      # @param [ Hash ] hash the hash to try and decode
+      #
+      # @return [ DBRef | Hash ] the result of decoding the hash
+      def maybe_dbref(hash)
+        return DBRef.new(hash) if hash['$ref'] && hash['$id']
+
+        hash
+      rescue Error::InvalidDBRefArgument
+        hash
+      end
+
+      # Given a byte buffer, extract and return a hash from it.
+      #
+      # @param [ ByteBuf ] buffer the buffer to read data from
+      # @param [ Hash ] options the keyword arguments
+      #
+      # @return [ Hash ] the hash parsed from the buffer
+      def parse_hash_from_buffer(buffer, **options)
         hash = Document.allocate
-        buffer.get_int32 # Throw away the size.
+        start_position = buffer.read_position
+        expected_byte_size = buffer.get_int32
+
+        parse_hash_contents(hash, buffer, **options)
+
+        actual_byte_size = buffer.read_position - start_position
+        return hash unless actual_byte_size != expected_byte_size
+
+        raise Error::BSONDecodeError,
+              "Expected hash to take #{expected_byte_size} bytes but it took #{actual_byte_size} bytes"
+      end
+
+      # Given an empty hash and a byte buffer, parse the key/value pairs from
+      # the buffer and populate the hash with them.
+      #
+      # @param [ Hash ] hash the hash to populate
+      # @param [ ByteBuf ] buffer the buffer to read data from
+      # @param [ Hash ] options the keyword arguments
+      def parse_hash_contents(hash, buffer, **options)
         while (type = buffer.get_byte) != NULL_BYTE
           field = buffer.get_cstring
-          hash.store(field, BSON::Registry.get(type, field).from_bson(buffer))
+          cls = BSON::Registry.get(type, field)
+          value = if options.empty?
+                    # Compatibility with the older Ruby driver versions which define
+                    # a DBRef class with from_bson accepting a single argument.
+                    cls.from_bson(buffer)
+                  else
+                    cls.from_bson(buffer, **options)
+                  end
+          hash.store(field, value)
         end
-        hash
       end
     end
 
     # Register this type when the module is loaded.
-    #
-    # @since 2.0.0
     Registry.register(BSON_TYPE, ::Hash)
   end
 
   # Enrich the core Hash class with this module.
-  #
-  # @since 2.0.0
-  ::Hash.send(:include, Hash)
-  ::Hash.send(:extend, Hash::ClassMethods)
+  ::Hash.include Hash
+  ::Hash.extend Hash::ClassMethods
 end

data/lib/bson/int32.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,18 +16,18 @@
 
 module BSON
 
-  # Represents a $maxKey type, which compares less than any other value in the
-  # specification.
+  # Represents int32 type.
   #
   # @see http://bsonspec.org/#/specification
   #
   # @since 2.0.0
   class Int32
+    include JSON
 
     # A boolean is type 0x08 in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 16.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(16.chr, encoding: BINARY).freeze
 
     # The number of bytes constant.
     #
@@ -35,21 +37,117 @@ module BSON
     # Constant for the int 32 pack directive.
     #
     # @since 2.0.0
-    PACK = "l<".freeze
+    PACK = "l<"
 
     # Deserialize an Integer from BSON.
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ Integer ] The decoded Integer.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
+    def self.from_bson(buffer, **options)
       buffer.get_int32
     end
 
+    # Instantiate a BSON Int32.
+    #
+    # @param [ Integer ] value The 32-bit integer.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 4.2.0
+    def initialize(value)
+      if value.is_a?(self.class)
+        @value = value.value
+        return
+      end
+
+      unless value.bson_int32?
+        raise RangeError.new("#{value} cannot be stored in 32 bits")
+      end
+      @value = value.freeze
+    end
+
+    # Returns the value of this Int32.
+    #
+    # @return [ Integer ] The integer value.
+    attr_reader :value
+
+    # Append the integer as encoded BSON to a ByteBuffer.
+    #
+    # @example Encoded the integer and append to a ByteBuffer.
+    #   int32.to_bson
+    #
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded integer.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 4.2.0
+    def to_bson(buffer = ByteBuffer.new)
+      buffer.put_int32(value)
+    end
+
+    # Convert the integer to a BSON string key.
+    #
+    # @example Convert the integer to a BSON key string.
+    #   int.to_bson_key
+    #
+    # @return [ String ] The string key.
+    #
+    # @since 4.2.0
+    def to_bson_key
+      value
+    end
+
+    # Check equality of the int32 with another object.
+    #
+    # @param [ Object ] other The object to check against.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 4.4.0
+    def ==(other)
+      return false unless other.is_a?(Int32)
+      value == other.value
+    end
+    alias :eql? :==
+    alias :=== :==
+
+    # Return a string representation of the Int32 for use in
+    # application-level JSON serialization. This method is intentionally
+    # different from #as_extended_json.
+    #
+    # @example Get the Int32 as a JSON-serializable object.
+    #   int32.as_json
+    #
+    # @return [ Integer ] The Int32 as an Integer.
+    def as_json(**options)
+      value
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
+    #
+    # This method returns the integer value if relaxed representation is
+    # requested, otherwise a $numberInt hash.
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash | Integer ] The extended json representation.
+    def as_extended_json(**options)
+      if options[:mode] == :relaxed || options[:mode] == :legacy
+        value
+      else
+        {'$numberInt' => value.to_s}
+      end
+    end
+
     # Register this type when the module is loaded.
     #
     # @since 2.0.0

data/lib/bson/int64.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,35 +16,136 @@
 
 module BSON
 
-  # Represents a $maxKey type, which compares less than any other value in the
-  # specification.
+  # Represents int64 type.
   #
   # @see http://bsonspec.org/#/specification
   #
   # @since 2.0.0
   class Int64
+    include JSON
 
     # A boolean is type 0x08 in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 18.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(18.chr, encoding: BINARY).freeze
 
     # Constant for the int 64 pack directive.
     #
     # @since 2.0.0
-    PACK = "q<".freeze
+    PACK = "q<"
 
     # Deserialize an Integer from BSON.
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
-    # @return [ Integer ] The decoded Integer.
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
+    # @return [ Integer | BSON::Int64 ] The decoded Integer.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
-      buffer.get_int64
+    def self.from_bson(buffer, **options)
+      value = buffer.get_int64
+      if options[:mode] == :bson
+        new(value)
+      else
+        value
+      end
+    end
+
+    # Instantiate a BSON Int64.
+    #
+    # @param [ Integer ] value The 64-bit integer.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 4.2.0
+    def initialize(value)
+      if value.is_a?(self.class)
+        @value = value.value
+        return
+      end
+
+      unless value.bson_int64?
+        raise RangeError.new("#{value} cannot be stored in 64 bits")
+      end
+      @value = value.freeze
+    end
+
+    # Returns the value of this Int64.
+    #
+    # @return [ Integer ] The integer value.
+    attr_reader :value
+
+    # Append the integer as encoded BSON to a ByteBuffer.
+    #
+    # @example Encoded the integer and append to a ByteBuffer.
+    #   int64.to_bson
+    #
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded integer.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 4.2.0
+    def to_bson(buffer = ByteBuffer.new)
+      buffer.put_int64(value)
+    end
+
+    # Convert the integer to a BSON string key.
+    #
+    # @example Convert the integer to a BSON key string.
+    #   int.to_bson_key
+    #
+    # @return [ String ] The string key.
+    #
+    # @since 4.2.0
+    def to_bson_key
+      value
+    end
+
+    # Check equality of the int64 with another object.
+    #
+    # @param [ Object ] other The object to check against.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 4.4.0
+    def ==(other)
+      return false unless other.is_a?(Int64)
+      value == other.value
+    end
+    alias :eql? :==
+    alias :=== :==
+
+    # Return a string representation of the Int64 for use in
+    # application-level JSON serialization. This method is intentionally
+    # different from #as_extended_json.
+    #
+    # @example Get the Int64 as a JSON-serializable object.
+    #   int64.as_json
+    #
+    # @return [ Integer ] The Int64 as an Integer.
+    def as_json(**options)
+      value
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
+    #
+    # This method returns the integer value if relaxed representation is
+    # requested, otherwise a $numberLong hash.
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash | Integer ] The extended json representation.
+    def as_extended_json(**options)
+      if options[:mode] == :relaxed || options[:mode] == :legacy
+        value
+      else
+        {'$numberLong' => value.to_s}
+      end
     end
 
     # Register this type when the module is loaded.

data/lib/bson/integer.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -45,13 +47,13 @@ module BSON
     # The BSON index size.
     #
     # @since 2.0.0
-    BSON_INDEX_SIZE = 1024.freeze
+    BSON_INDEX_SIZE = 1024
 
     # A hash of index values for array optimization.
     #
     # @since 2.0.0
     BSON_ARRAY_INDEXES = ::Array.new(BSON_INDEX_SIZE) do |i|
-      (i.to_s.force_encoding(BINARY) << NULL_BYTE).freeze
+      (i.to_s.b << NULL_BYTE).freeze
     end.freeze
 
     # Is this integer a valid BSON 32 bit value?
@@ -98,12 +100,12 @@ module BSON
     # @example Get the integer as encoded BSON.
     #   1024.to_bson
     #
-    # @return [ String ] The encoded string.
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
     # @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)
       if bson_int32?
         buffer.put_int32(self)
       elsif bson_int64?
@@ -150,13 +152,45 @@ module BSON
     # @example Convert the integer to a BSON key string.
     #   1.to_bson_key
     #
-    # @param [ true, false ] validating_keys If BSON should validate the key.
-    #
     # @return [ String ] The string key.
     #
     # @since 2.0.0
-    def to_bson_key(validating_keys = Config.validating_keys?)
-      to_s.to_bson_key(validating_keys)
+    def to_bson_key
+      self
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
+    #
+    # This method returns the integer itself if relaxed representation is
+    # requested, otherwise a $numberInt hash if the value fits in 32 bits
+    # and a $numberLong otherwise. Regardless of which representation is
+    # requested, a value that does not fit in 64 bits raises RangeError.
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash | Integer ] The extended json representation.
+    def as_extended_json(**options)
+      # The behavior of native integers' serialization to extended json is
+      # not specified. Following our bson serialization logic in this file,
+      # produce explicit $numberInt or $numberLong, choosing $numberInt if
+      # the integer fits in 32 bits. In Ruby integers can be arbitrarily
+      # big; integers that do not fit into 64 bits raise an error as we do not
+      # want to silently perform an effective type conversion of integer ->
+      # decimal.
+
+      unless bson_int64?
+        raise RangeError, "Integer #{self} is too big to be represented as a MongoDB integer"
+      end
+
+      if options[:mode] == :relaxed || options[:mode] == :legacy
+        self
+      elsif bson_int32?
+        {'$numberInt' => to_s}
+      else
+        {'$numberLong' => to_s}
+      end
     end
 
     private

data/lib/bson/json.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.