bson 4.2.2 → 4.12.1

data/lib/bson/hash.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# 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.
@@ -22,7 +22,7 @@ module BSON
   # @since 2.0.0
   module Hash
 
-    # An hash (embedded document) is type 0x03 in the BSON spec.
+    # A hash, also called an embedded document, is type 0x03 in the BSON spec.
     #
     # @since 2.0.0
     BSON_TYPE = 3.chr.force_encoding(BINARY).freeze
@@ -38,15 +38,31 @@ module BSON
     #
     # @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)
+      if buffer.respond_to?(:put_hash)
+        buffer.put_hash(self, validating_keys)
+      else
+        position = buffer.length
+        buffer.put_int32(0)
+        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(validating_keys)
+          begin
+            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
+          value.to_bson(buffer, validating_keys)
+        end
+        buffer.put_byte(NULL_BYTE)
+        buffer.replace_int32(position, buffer.length - position)
       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.
@@ -61,25 +77,60 @@ module BSON
       Document.new(self)
     end
 
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # 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)
+      ::Hash[map do |key, value|
+        [key, value.as_extended_json(**options)]
+      end]
+    end
+
     module ClassMethods
 
       # Deserialize the hash from BSON.
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ Array ] The decoded hash.
       #
       # @see http://bsonspec.org/#/specification
       #
       # @since 2.0.0
-      def from_bson(buffer)
-        hash = Document.allocate
-        buffer.get_int32 # Throw away the size.
-        while (type = buffer.get_byte) != NULL_BYTE
-          field = buffer.get_cstring
-          hash.store(field, BSON::Registry.get(type, field).from_bson(buffer))
+      def from_bson(buffer, **options)
+        if buffer.respond_to?(:get_hash)
+          buffer.get_hash(**options)
+        else
+          hash = Document.allocate
+          start_position = buffer.read_position
+          expected_byte_size = buffer.get_int32
+          while (type = buffer.get_byte) != NULL_BYTE
+            field = buffer.get_cstring
+            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
+          actual_byte_size = buffer.read_position - start_position
+          if 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
+          hash
         end
-        hash
       end
     end
 

data/lib/bson/int32.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# 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,8 +14,7 @@
 
 module BSON
 
-  # Represents a $maxKey type, which compares less than any other value in the
-  # specification.
+  # Represents int32 type.
   #
   # @see http://bsonspec.org/#/specification
   #
@@ -41,27 +40,41 @@ module 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 ] integer The 32-bit integer.
+    # @param [ Integer ] value The 32-bit integer.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 4.2.0
-    def initialize(integer)
-      out_of_range! unless integer.bson_int32?
-      @integer = integer.freeze
+    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.
@@ -73,7 +86,7 @@ module BSON
     #
     # @since 4.2.0
     def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      buffer.put_int32(@integer)
+      buffer.put_int32(value)
     end
 
     # Convert the integer to a BSON string key.
@@ -87,13 +100,39 @@ module BSON
     #
     # @since 4.2.0
     def to_bson_key(validating_keys = Config.validating_keys?)
-      @integer.to_bson_key(validating_keys)
+      value
     end
 
-    private
+    # 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 :=== :==
 
-    def out_of_range!
-      raise RangeError.new("#{self} is not a valid 4 byte integer value.")
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # 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.

data/lib/bson/int64.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# 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,8 +14,7 @@
 
 module BSON
 
-  # Represents a $maxKey type, which compares less than any other value in the
-  # specification.
+  # Represents int64 type.
   #
   # @see http://bsonspec.org/#/specification
   #
@@ -36,27 +35,46 @@ module 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 ] integer The 64-bit integer.
+    # @param [ Integer ] value The 64-bit integer.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 4.2.0
-    def initialize(integer)
-      out_of_range! unless integer.bson_int64?
-      @integer = integer.freeze
+    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.
@@ -68,7 +86,7 @@ module BSON
     #
     # @since 4.2.0
     def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      buffer.put_int64(@integer)
+      buffer.put_int64(value)
     end
 
     # Convert the integer to a BSON string key.
@@ -82,13 +100,39 @@ module BSON
     #
     # @since 4.2.0
     def to_bson_key(validating_keys = Config.validating_keys?)
-      @integer.to_bson_key(validating_keys)
+      value
     end
 
-    private
+    # 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 :=== :==
 
-    def out_of_range!
-      raise RangeError.new("#{self} is not a valid 8 byte integer value.")
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # 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,4 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# 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.
@@ -156,7 +156,41 @@ module BSON
     #
     # @since 2.0.0
     def to_bson_key(validating_keys = Config.validating_keys?)
-      to_s.to_bson_key(validating_keys)
+      self
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # 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,4 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# 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.

data/lib/bson/max_key.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# 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.
@@ -58,7 +58,19 @@ module BSON
     # @return [ Hash ] The max key as a JSON hash.
     #
     # @since 2.0.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
+      as_extended_json
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
       { "$maxKey" => 1 }
     end
 

data/lib/bson/min_key.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# 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.
@@ -58,7 +58,19 @@ module BSON
     # @return [ Hash ] The min key as a JSON hash.
     #
     # @since 2.0.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
+      as_extended_json
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
       { "$minKey" => 1 }
     end