bson 4.15.0 → 5.0.0

data/lib/bson/error/unsupported_type.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module BSON
+  class Error
+
+    # Raised when trying to get a type from the registry that doesn't exist.
+    class UnsupportedType < Error; end
+  end
+end
+

data/lib/bson/error.rb

@@ -1,34 +1,22 @@
 # frozen_string_literal: true
+# rubocop:todo all
 module BSON
   # Base exception class for all BSON-related errors.
-  #
-  # @note Many existing exceptions raised by bson-ruby do not derive from
-  #   this base class. This will change in the next major version (5.0).
   class Error < StandardError
-
-    # Exception raised when Extended JSON parsing fails.
-    class ExtJSONParseError < Error
-    end
-
-    # Exception raised when decoding BSON and the data contains an
-    # unsupported binary subtype.
-    class UnsupportedBinarySubtype < Error
-    end
-
-    # Exception raised when BSON decoding fails.
-    class BSONDecodeError < Error
-    end
-
-    # Exception raised when serializing an Array or Hash to BSON and an
-    # array or hash element is of a class that does not define how to serialize
-    # itself to BSON.
-    class UnserializableClass < Error
-    end
-
-    # Exception raised when there is an invalid argument passed into the
-    # constructor of regexp object. This includes when the argument contains
-    # a null byte.
-    class InvalidRegexpPattern < Error
-    end
   end
 end
+
+require 'bson/error/bson_decode_error'
+require 'bson/error/ext_json_parse_error'
+require 'bson/error/invalid_binary_type'
+require 'bson/error/invalid_dbref_argument'
+require 'bson/error/invalid_decimal128_argument'
+require 'bson/error/invalid_decimal128_range'
+require 'bson/error/invalid_decimal128_string'
+require 'bson/error/invalid_key'
+require 'bson/error/invalid_object_id'
+require 'bson/error/invalid_regexp_pattern'
+require 'bson/error/unrepresentable_precision'
+require 'bson/error/unserializable_class'
+require 'bson/error/unsupported_binary_subtype'
+require 'bson/error/unsupported_type'

data/lib/bson/ext_json.rb

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

data/lib/bson/false_class.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");
@@ -50,7 +51,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_byte(FALSE_BYTE)
     end
   end

data/lib/bson/float.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");
@@ -43,7 +44,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_double(self)
     end
 

data/lib/bson/hash.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");
@@ -13,19 +14,14 @@
 # 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
-
     # A hash, also called an embedded document, is type 0x03 in the BSON spec.
-    #
-    # @since 2.0.0
     BSON_TYPE = ::String.new(3.chr, encoding: BINARY).freeze
 
     # Get the hash as encoded BSON.
@@ -36,33 +32,13 @@ module BSON
     # @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 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, validating_keys)
+        buffer.put_hash(self)
       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)
+        serialize_to_buffer(buffer)
       end
     end
 
@@ -72,8 +48,6 @@ module BSON
     #   hash.to_bson_normalized_value
     #
     # @return [ BSON::Document ] The normalized hash.
-    #
-    # @since 3.0.0
     def to_bson_normalized_value
       Document.new(self)
     end
@@ -92,10 +66,67 @@ module BSON
       transform_values { |value| value.as_extended_json(**options) }
     end
 
-    module ClassMethods
+    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.
       #
       # @option options [ nil | :bson ] :mode Decoding mode to use.
@@ -103,55 +134,79 @@ module BSON
       # @return [ Hash ] The decoded hash.
       #
       # @see http://bsonspec.org/#/specification
-      #
-      # @since 2.0.0
       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
-
-          if hash['$ref'] && hash['$id']
-            # We're doing implicit decoding here. If the document is an invalid
-            # dbref, we should decode it as a BSON::Document.
-            begin
-              hash = DBRef.new(hash)
-            rescue ArgumentError
-            end
-          end
-
-          hash
+          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.
+      #
+      # @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
+        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
+          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
       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,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 # Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -21,6 +22,7 @@ module BSON
   #
   # @since 2.0.0
   class Int32
+    include JSON
 
     # A boolean is type 0x08 in the BSON spec.
     #
@@ -86,7 +88,7 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 4.2.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       buffer.put_int32(value)
     end
 
@@ -95,12 +97,10 @@ module BSON
     # @example Convert the integer to a BSON key string.
     #   int.to_bson_key
     #
-    # @param [ true, false ] validating_keys If BSON should validate the key.
-    #
     # @return [ String ] The string key.
     #
     # @since 4.2.0
-    def to_bson_key(validating_keys = Config.validating_keys?)
+    def to_bson_key
       value
     end
 
@@ -118,6 +118,18 @@ module BSON
     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.rst).
     #

data/lib/bson/int64.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");
@@ -21,6 +22,7 @@ module BSON
   #
   # @since 2.0.0
   class Int64
+    include JSON
 
     # A boolean is type 0x08 in the BSON spec.
     #
@@ -86,7 +88,7 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 4.2.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       buffer.put_int64(value)
     end
 
@@ -95,12 +97,10 @@ module BSON
     # @example Convert the integer to a BSON key string.
     #   int.to_bson_key
     #
-    # @param [ true, false ] validating_keys If BSON should validate the key.
-    #
     # @return [ String ] The string key.
     #
     # @since 4.2.0
-    def to_bson_key(validating_keys = Config.validating_keys?)
+    def to_bson_key
       value
     end
 
@@ -118,6 +118,18 @@ module BSON
     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.rst).
     #

data/lib/bson/integer.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");
@@ -104,7 +105,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)
       if bson_int32?
         buffer.put_int32(self)
       elsif bson_int64?
@@ -151,12 +152,10 @@ 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?)
+    def to_bson_key
       self
     end
 

data/lib/bson/json.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/max_key.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");
@@ -51,16 +52,13 @@ module BSON
       GREATER
     end
 
-    # Get the max key as JSON hash data.
+    # Return a representation of the object for use in
+    # application-level JSON serialization. Since BSON::MaxKey
+    # is used exclusively in BSON-related contexts, this
+    # method returns the canonical Extended JSON representation.
     #
-    # @example Get the max key as a JSON hash.
-    #   max_key.as_json
-    #
-    # @return [ Hash ] The max key 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
 

data/lib/bson/min_key.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");
@@ -51,16 +52,13 @@ module BSON
       LESSER
     end
 
-    # Get the min key as JSON hash data.
+    # Return a representation of the object for use in
+    # application-level JSON serialization. Since BSON::MinKey
+    # is used exclusively in BSON-related contexts, this
+    # method returns the canonical Extended JSON representation.
     #
-    # @example Get the min key as a JSON hash.
-    #   min_key.as_json
-    #
-    # @return [ Hash ] The min key 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
 

data/lib/bson/nil_class.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/object.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");
@@ -27,13 +28,13 @@ module BSON
     # @example Convert the object to a BSON key.
     #   object.to_bson_key
     #
-    # @raise [ InvalidKey ] Always raises an exception.
+    # @raise [ BSON::Error::InvalidKey ] Always raises an exception.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.2.4
-    def to_bson_key(validating_keys = Config.validating_keys?)
-      raise InvalidKey.new(self)
+    def to_bson_key
+      raise Error::InvalidKey.new(self)
     end
 
     # Converts the object to a normalized key in a BSON document.
@@ -79,33 +80,12 @@ module BSON
     # Subclasses should override this method to provide custom serialization
     # to Extended JSON.
     #
-    # @option options [ true | false ] :relaxed Whether to produce relaxed
-    #   extended JSON representation.
-    #
     # @return [ Object ] The extended json representation.
-    def as_extended_json(**options)
+    def as_extended_json(**_options)
       self
     end
   end
 
-  # Raised when trying to serialize an object into a key.
-  #
-  # @since 2.2.4
-  class InvalidKey < RuntimeError
-
-    # Instantiate the exception.
-    #
-    # @example Instantiate the exception.
-    #   BSON::Object::InvalidKey.new(object)
-    #
-    # @param [ Object ] object The object that was meant for the key.
-    #
-    # @since 2.2.4
-    def initialize(object)
-      super("#{object.class} instances are not allowed as keys in a BSON document.")
-    end
-  end
-
   # Enrich the core Object class with this module.
   #
   # @since 2.2.4