bson 4.15.0 → 5.0.2

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,21 +52,18 @@ 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
 
     # Converts this object to a representation directly serializable to
-    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
     #
     # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
     #   (default is canonical extended JSON)

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,21 +52,18 @@ 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
 
     # Converts this object to a representation directly serializable to
-    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
     #
     # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
     #   (default is canonical extended JSON)

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.
@@ -61,7 +62,7 @@ module BSON
     end
 
     # Serializes this object to Extended JSON
-    # (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    # (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
     #
     # Subclasses should override +as_extended_json+ rather than this method.
     #
@@ -74,38 +75,17 @@ module BSON
     end
 
     # Converts this object to a representation directly serializable to
-    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
     #
     # 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

data/lib/bson/object_id.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,12 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "digest/md5"
-require "socket"
-require "thread"
-
 module BSON
-
   # Represents object_id data.
   #
   # @see http://bsonspec.org/#/specification
@@ -45,9 +41,10 @@ module BSON
     # @since 2.0.0
     def ==(other)
       return false unless other.is_a?(ObjectId)
+
       generate_data == other.send(:generate_data)
     end
-    alias :eql? :==
+    alias eql? ==
 
     # Check case equality on the object id.
     #
@@ -60,32 +57,29 @@ module BSON
     #
     # @since 2.0.0
     def ===(other)
-      return to_str === other.to_str if other.respond_to?(:to_str)
+      return to_str == other.to_str if other.respond_to?(:to_str)
+
       super
     end
 
-    # Return the object id as a JSON hash representation.
+    # Return a string representation of the object id for use in
+    # application-level JSON serialization. This method is intentionally
+    # different from #as_extended_json.
     #
-    # @example Get the object id as JSON.
+    # @example Get the object id as a JSON-serializable object.
     #   object_id.as_json
     #
-    # @return [ Hash ] The object id as a JSON hash.
-    #
-    # @since 2.0.0
-    # @deprecated Use as_extended_json instead.
-    def as_json(*args)
-      as_extended_json
+    # @return [ String ] The object id as a string.
+    def as_json(*_)
+      to_s
     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)
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
     #
     # @return [ Hash ] The extended json representation.
-    def as_extended_json(**options)
-      { "$oid" => to_s }
+    def as_extended_json(**_)
+      { '$oid' => to_s }
     end
 
     # Compare this object id with another object for use in sorting.
@@ -113,9 +107,9 @@ module BSON
     #
     # @since 2.0.0
     def generation_time
-      ::Time.at(generate_data.unpack1("N")).utc
+      ::Time.at(generate_data.unpack1('N')).utc
     end
-    alias :to_time :generation_time
+    alias to_time generation_time
 
     # Get the hash value for the object id.
     #
@@ -138,7 +132,7 @@ module BSON
     #
     # @since 2.0.0
     def inspect
-      "BSON::ObjectId('#{to_s}')"
+      "BSON::ObjectId('#{self}')"
     end
 
     # Dump the raw bson when calling Marshal.dump.
@@ -182,7 +176,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_bytes(generate_data)
     end
 
@@ -197,12 +191,46 @@ module BSON
     def to_s
       generate_data.to_hex_string.force_encoding(UTF8)
     end
-    alias :to_str :to_s
+    alias to_str to_s
 
-    # Raised when trying to create an object id with invalid data.
+    # Extract the process-specific part of the object id. This is used only
+    # internally, for testing, and should not be used elsewhere.
     #
-    # @since 2.0.0
-    class Invalid < RuntimeError; end
+    # @return [ String ] The process portion of the id.
+    #
+    # @api private
+    def _process_part
+      to_s[8, 10]
+    end
+
+    # Extract the counter-specific part of the object id. This is used only
+    # internally, for testing, and should not be used elsewhere.
+    #
+    # @return [ String ] The counter portion of the id.
+    #
+    # @api private
+    def _counter_part
+      to_s[18, 6]
+    end
+
+    # Extended by native code (see init.c, util.c, GeneratorExtension.java)
+    #
+    # @api private
+    #
+    # rubocop:disable Lint/EmptyClass
+    class Generator
+    end
+    # rubocop:enable Lint/EmptyClass
+
+    # We keep one global generator for object ids.
+    @@generator = Generator.new
+
+    # Accessor for querying the generator directly; used in testing.
+    #
+    # @api private
+    def self._generator
+      @@generator
+    end
 
     private
 
@@ -213,7 +241,10 @@ module BSON
 
     def generate_data
       repair if defined?(@data)
+
+      # rubocop:disable Naming/MemoizedInstanceVariableName
       @raw_data ||= @@generator.next_object_id
+      # rubocop:enable Naming/MemoizedInstanceVariableName
     end
 
     def repair
@@ -222,20 +253,18 @@ module BSON
     end
 
     class << self
-
       # Deserialize the object id from raw BSON bytes.
       #
       # @example Get the object id from BSON.
       #   ObjectId.from_bson(bson)
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
-      #
-      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      # @param [ Hash ] _ An optional hash of keyword arguments (unused).
       #
       # @return [ BSON::ObjectId ] The object id.
       #
       # @since 2.0.0
-      def from_bson(buffer, **options)
+      def from_bson(buffer, **_)
         from_data(buffer.get_bytes(12))
       end
 
@@ -262,16 +291,15 @@ module BSON
       #
       # @param [ String ] string The string to create the id from.
       #
-      # @raise [ BSON::ObjectId::Invalid ] If the provided string is invalid.
+      # @raise [ BSON::Error::InvalidObjectId ] If the provided string is invalid.
       #
       # @return [ BSON::ObjectId ] The new object id.
       #
       # @since 2.0.0
       def from_string(string)
-        unless legal?(string)
-          raise Invalid.new("'#{string}' is an invalid ObjectId.")
-        end
-        from_data([ string ].pack("H*"))
+        raise Error::InvalidObjectId, "'#{string}' is an invalid ObjectId." unless legal?(string)
+
+        from_data([ string ].pack('H*'))
       end
 
       # Create a new object id from a time.
@@ -292,7 +320,7 @@ module BSON
       #
       # @since 2.0.0
       def from_time(time, options = {})
-        from_data(options[:unique] ? @@generator.next_object_id(time.to_i) : [ time.to_i ].pack("Nx8"))
+        from_data(options[:unique] ? @@generator.next_object_id(time.to_i) : [ time.to_i ].pack('Nx8'))
       end
 
       # Determine if the provided string is a legal object id.
@@ -306,7 +334,7 @@ module BSON
       #
       # @since 2.0.0
       def legal?(string)
-        string.to_s =~ /\A[0-9a-f]{24}\z/i ? true : false
+        (string.to_s =~ /\A[0-9a-f]{24}\z/i) ? true : false
       end
 
       # Executes the provided block only if the size of the provided object is
@@ -317,100 +345,36 @@ module BSON
       #
       # @param [ String, Array ] object The object to repair.
       #
-      # @raise [ Invalid ] If the array is not 12 elements.
+      # @raise [ BSON::Error::InvalidObjectId ] If the array is not 12 elements.
       #
       # @return [ String ] The result of the block.
       #
       # @since 2.0.0
       def repair(object)
-        if object.size == 12
-          block_given? ? yield(object) : object
-        else
-          raise Invalid.new("#{object.inspect} is not a valid object id.")
-        end
-      end
-    end
-
-    # Inner class that encapsulates the behaviour of actually generating each
-    # part of the ObjectId.
-    #
-    # @api private
-    #
-    # @since 2.0.0
-    class Generator
-
-      # @!attribute machine_id
-      #   @return [ String ] The unique machine id.
-      #   @since 2.0.0
-      attr_reader :machine_id
+        raise Error::InvalidObjectId, "#{object.inspect} is not a valid object id." if object.size != 12
 
-      # Instantiate the new object id generator. Will set the machine id once
-      # on the initial instantiation.
-      #
-      # @example Instantiate the generator.
-      #   BSON::ObjectId::Generator.new
-      #
-      # @since 2.0.0
-      def initialize
-        @counter = rand(0x1000000)
-        @machine_id = Digest::MD5.digest(Socket.gethostname).unpack1("N")
-        @mutex = Mutex.new
+        block_given? ? yield(object) : object
       end
 
-      # Return object id data based on the current time, incrementing the
-      # object id counter. Will use the provided time if not nil.
-      #
-      # @example Get the next object id data.
-      #   generator.next_object_id
-      #
-      # @param [ Time ] time The optional time to generate with.
-      #
-      # @return [ String ] The raw object id bytes.
-      #
-      # @since 2.0.0
-      def next_object_id(time = nil)
-        @mutex.lock
-        begin
-          count = @counter = (@counter + 1) % 0xFFFFFF
-        ensure
-          @mutex.unlock rescue nil
-        end
-        generate(time || ::Time.new.to_i, count)
-      end
+      # The largest numeric value that can be converted to an integer by MRI's
+      # NUM2UINT. Further, the spec dictates that the time component of an
+      # ObjectID must be no more than 4 bytes long, so the spec itself is
+      # constrained in this regard.
+      MAX_INTEGER = 2 ** 32
 
-      # Generate object id data for a given time using the provided counter.
-      #
-      # @example Generate the object id bytes.
-      #   generator.generate(time)
+      # Returns an integer timestamp (seconds since the Epoch). Primarily used
+      # by the generator to produce object ids.
       #
-      # @param [ Integer ] time The time since epoch in seconds.
-      # @param [ Integer ] counter The optional counter.
+      # @note This value is guaranteed to be no more than 4 bytes in length. A
+      #   time value far enough in the future to require a larger integer than
+      #   4 bytes will be truncated to 4 bytes.
       #
-      # @return [ String ] The raw object id bytes.
-      #
-      # @since 2.0.0
-      def generate(time, counter = 0)
-        [ time, machine_id, process_id, counter << 8 ].pack("N NX lXX NX")
-      end
-
-      private
-
-      if Environment.jruby?
-        def process_id
-          "#{Process.pid}#{Thread.current.object_id}".hash % 0xFFFF
-        end
-      else
-        def process_id
-          Process.pid % 0xFFFF
-        end
+      # @return [ Integer ] the number of seconds since the Epoch.
+      def timestamp
+        ::Time.now.to_i % MAX_INTEGER
       end
     end
 
-    # We keep one global generator for object ids.
-    #
-    # @since 2.0.0
-    @@generator = Generator.new
-
     # Register this type when the module is loaded.
     #
     # @since 2.0.0

data/lib/bson/open_struct.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");
@@ -33,12 +34,12 @@ 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)
       if Environment.ruby_1_9?
         marshal_dump.dup
       else
         to_h
-      end.to_bson(buffer, validating_keys)
+      end.to_bson(buffer)
     end
 
     # The BSON type for OpenStruct objects is the Hash type of 0x03.