bson 4.1.1 → 5.2.0

data/lib/bson/max_key.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.
@@ -28,12 +30,12 @@ module BSON
     # A $maxKey is type 0x7F in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 127.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(127.chr, encoding: BINARY).freeze
 
     # Constant for always evaluating greater in a comparison.
     #
     # @since 2.0.0
-    GREATER = 1.freeze
+    GREATER = 1
 
     # When comparing a max key with any other object, the max key will always
     # be greater.
@@ -41,7 +43,7 @@ module BSON
     # @example Compare with another object.
     #   max_key <=> 1000
     #
-    # @param [ Object ] The object to compare against.
+    # @param [ Object ] other The object to compare against.
     #
     # @return [ Integer ] Always 1.
     #
@@ -50,15 +52,24 @@ 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 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/extended-json.md).
     #
-    # @return [ Hash ] The max key as a JSON hash.
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
     #
-    # @since 2.0.0
-    def as_json(*args)
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
       { "$maxKey" => 1 }
     end
 

data/lib/bson/min_key.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.
@@ -28,12 +30,12 @@ module BSON
     # A $minKey is type 0xFF in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 255.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(255.chr, encoding: BINARY).freeze
 
     # Constant for always evaluating lesser in a comparison.
     #
     # @since 2.0.0
-    LESSER = -1.freeze
+    LESSER = -1
 
     # When comparing a min key with any other object, the min key will always
     # be lesser.
@@ -41,7 +43,7 @@ module BSON
     # @example Compare with another object.
     #   min_key <=> 1000
     #
-    # @param [ Object ] The object to compare against.
+    # @param [ Object ] other The object to compare against.
     #
     # @return [ Integer ] Always -1.
     #
@@ -50,15 +52,24 @@ 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 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/extended-json.md).
     #
-    # @return [ Hash ] The min key as a JSON hash.
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
     #
-    # @since 2.0.0
-    def as_json(*args)
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
       { "$minKey" => 1 }
     end
 

data/lib/bson/nil_class.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.
@@ -26,7 +28,7 @@ module BSON
     # A nil is type 0x0A in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 10.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(10.chr, encoding: BINARY).freeze
 
     module ClassMethods
 
@@ -34,12 +36,14 @@ module BSON
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ nil ] The decoded nil value.
       #
       # @see http://bsonspec.org/#/specification
       #
       # @since 2.0.0
-      def from_bson(buffer)
+      def from_bson(buffer, **options)
         nil
       end
     end

data/lib/bson/object.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.
@@ -26,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.
@@ -58,23 +60,29 @@ module BSON
     def to_bson_normalized_value
       self
     end
-  end
 
-  # Raised when trying to serialize an object into a key.
-  #
-  # @since 2.2.4
-  class InvalidKey < RuntimeError
-
-    # Instantiate the exception.
+    # Serializes this object to Extended JSON
+    # (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
     #
-    # @example Instantiate the exception.
-    #   BSON::Object::InvalidKey.new(object)
+    # Subclasses should override +as_extended_json+ rather than this method.
     #
-    # @param [ Object ] object The object that was meant for the key.
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
     #
-    # @since 2.2.4
-    def initialize(object)
-      super("#{object.class} instances are not allowed as keys in a BSON document.")
+    # @return [ String ] The extended json serialization.
+    def to_extended_json(**options)
+      as_extended_json(**options).to_json
+    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).
+    #
+    # Subclasses should override this method to provide custom serialization
+    # to Extended JSON.
+    #
+    # @return [ Object ] The extended json representation.
+    def as_extended_json(**_options)
+      self
     end
   end
 

data/lib/bson/object_id.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,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
@@ -30,7 +27,7 @@ module BSON
     # A object_id is type 0x07 in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 7.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(7.chr, encoding: BINARY).freeze
 
     # Check equality of the object id with another object.
     #
@@ -44,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.
     #
@@ -59,20 +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.
+    # @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/extended-json.md).
     #
-    # @since 2.0.0
-    def as_json(*args)
-      { "$oid" => to_s }
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**_)
+      { '$oid' => to_s }
     end
 
     # Compare this object id with another object for use in sorting.
@@ -100,8 +107,9 @@ module BSON
     #
     # @since 2.0.0
     def generation_time
-      ::Time.at(generate_data.unpack("N")[0]).utc
+      ::Time.at(generate_data.unpack1('N')).utc
     end
+    alias to_time generation_time
 
     # Get the hash value for the object id.
     #
@@ -124,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.
@@ -163,12 +171,12 @@ module BSON
     #   where the object was instantiated in a non-standard way. (Like a
     #   Marshal.load)
     #
-    # @return [ String ] The raw bytes.
+    # @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)
       buffer.put_bytes(generate_data)
     end
 
@@ -183,18 +191,60 @@ 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
 
+    def initialize_copy(other)
+      generate_data
+      other.instance_variable_set(:@raw_data, @raw_data)
+    end
+
     def generate_data
       repair if defined?(@data)
+
+      # rubocop:disable Naming/MemoizedInstanceVariableName
       @raw_data ||= @@generator.next_object_id
+      # rubocop:enable Naming/MemoizedInstanceVariableName
     end
 
     def repair
@@ -203,18 +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.
+      # @param [ Hash ] _ An optional hash of keyword arguments (unused).
       #
       # @return [ BSON::ObjectId ] The object id.
       #
       # @since 2.0.0
-      def from_bson(buffer)
+      def from_bson(buffer, **_)
         from_data(buffer.get_bytes(12))
       end
 
@@ -241,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.
@@ -271,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.
@@ -279,13 +328,13 @@ module BSON
       # @example Is the string a legal object id?
       #   BSON::ObjectId.legal?(string)
       #
-      # @param [ String ] The string to check.
+      # @param [ String ] string The string to check.
       #
       # @return [ true, false ] If the string is legal.
       #
       # @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
@@ -296,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
+        raise Error::InvalidObjectId, "#{object.inspect} is not a valid object id." if object.size != 12
 
-    # 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
-
-      # 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).unpack("N")[0]
-        @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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2016-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.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module BSON
+
+  # Injects behaviour for encoding OpenStruct objects using hashes
+  # to raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 4.2.0
+  module OpenStruct
+
+    # Get the OpenStruct as encoded BSON.
+    #
+    # @example Get the OpenStruct object as encoded BSON.
+    #   OpenStruct.new({ "field" => "value" }).to_bson
+    #
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 4.2.0
+    def to_bson(buffer = ByteBuffer.new)
+      if Environment.ruby_1_9?
+        marshal_dump.dup
+      else
+        to_h
+      end.to_bson(buffer)
+    end
+
+    # The BSON type for OpenStruct objects is the Hash type of 0x03.
+    #
+    # @example Get the bson type.
+    #   struct.bson_type
+    #
+    # @return [ String ] The character 0x03.
+    #
+    # @since 4.2.0
+    def bson_type
+      ::Hash::BSON_TYPE
+    end
+  end
+
+  ::OpenStruct.send(:include, OpenStruct) if defined?(::OpenStruct)
+end