bson 4.15.0 → 5.0.0

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)
-    #
     # @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,26 @@ 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).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.
+      # Returns an integer timestamp (seconds since the Epoch). Primarily used
+      # by the generator to produce object ids.
       #
-      # @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
-
-      # Generate object id data for a given time using the provided counter.
-      #
-      # @example Generate the object id bytes.
-      #   generator.generate(time)
-      #
-      # @param [ Integer ] time The time since epoch in seconds.
-      # @param [ Integer ] counter The optional counter.
-      #
-      # @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
       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.

data/lib/bson/regexp.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,8 +14,8 @@
 # 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 regular expression values to
   # and from raw bytes as specified by the BSON spec.
   #
@@ -62,10 +63,8 @@ module BSON
     #   regexp.as_json
     #
     # @return [ Hash ] The regexp as a JSON hash.
-    #
-    # @since 2.0.0
-    def as_json(*args)
-      { "$regex" => source, "$options" => bson_options }
+    def as_json(*)
+      { '$regex' => source, '$options' => bson_options }
     end
 
     # Get the regular expression as encoded BSON.
@@ -83,14 +82,11 @@ module BSON
     #   and 'u' to make \w, \W, etc. match unicode.
     #
     # @param [ BSON::ByteBuffer ] buffer The byte buffer to append to.
-    # @param [ true, false ] validating_keys
     #
     # @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_cstring(source)
       buffer.put_cstring(bson_options)
     end
@@ -103,30 +99,28 @@ module BSON
     end
 
     def bson_extended
-      (options & ::Regexp::EXTENDED != 0) ? EXTENDED_VALUE : NO_VALUE
+      (options & ::Regexp::EXTENDED).zero? ? NO_VALUE : EXTENDED_VALUE
     end
 
     def bson_ignorecase
-      (options & ::Regexp::IGNORECASE != 0) ? IGNORECASE_VALUE : NO_VALUE
+      (options & ::Regexp::IGNORECASE).zero? ? NO_VALUE : IGNORECASE_VALUE
     end
 
     def bson_dotall
       # Ruby Regexp's MULTILINE is equivalent to BSON's dotall value
-      (options & ::Regexp::MULTILINE != 0) ? NEWLINE_VALUE : NO_VALUE
+      (options & ::Regexp::MULTILINE).zero? ? NO_VALUE : NEWLINE_VALUE
     end
 
     # Represents the raw values for the regular expression.
     #
     # @see https://jira.mongodb.org/browse/RUBY-698
-    #
-    # @since 3.0.0
     class Raw
       include JSON
 
       # @return [ String ] pattern The regex pattern.
       attr_reader :pattern
 
-      # @return [ Integer ] options The options.
+      # @return [ String ] options The options.
       attr_reader :options
 
       # Compile the Regular expression into the native type.
@@ -135,10 +129,8 @@ module BSON
       #   raw.compile
       #
       # @return [ ::Regexp ] The compiled regular expression.
-      #
-      # @since 3.0.0
       def compile
-        @compiled ||= ::Regexp.new(pattern, options_to_int)
+        @compile ||= ::Regexp.new(pattern, options_to_int)
       end
 
       # Initialize the new raw regular expression.
@@ -147,13 +139,7 @@ module BSON
       #   Raw.new(pattern, options)
       #
       # @param [ String ] pattern The regular expression pattern.
-      # @param [ String, Integer ] options The options.
-      #
-      # @note The ability to specify options as an Integer is deprecated.
-      #  Please specify options as a String. The ability to pass options as
-      #  as Integer will be removed in version 5.0.0.
-      #
-      # @since 3.0.0
+      # @param [ String | Symbol ] options The options.
       def initialize(pattern, options = '')
         if pattern.include?(NULL_BYTE)
           raise Error::InvalidRegexpPattern, "Regexp pattern cannot contain a null byte: #{pattern}"
@@ -161,28 +147,22 @@ module BSON
           if options.to_s.include?(NULL_BYTE)
             raise Error::InvalidRegexpPattern, "Regexp options cannot contain a null byte: #{options}"
           end
-        elsif !options.is_a?(Integer)
-          raise ArgumentError, "Regexp options must be a String, Symbol, or Integer"
+        else
+          raise ArgumentError, 'Regexp options must be a String or Symbol'
         end
 
         @pattern = pattern
-        @options = options
+        @options = options.to_s
       end
 
       # Allow automatic delegation of methods to the Regexp object
       # returned by +compile+.
       #
       # @param [ String] method The name of a method.
-      #
-      # @since 3.1.0
-      def respond_to?(method, include_private = false)
-        if defined?(@pattern)
-          compile.respond_to?(method, include_private) || super
-        else
-          # YAML calls #respond_to? during deserialization, before the object
-          # is initialized.
-          super
-        end
+      def respond_to_missing?(method, include_private = false)
+        # YAML calls #respond_to? during deserialization, before the object
+        # is initialized.
+        defined?(@pattern) && compile.respond_to?(method, include_private)
       end
 
       # Encode the Raw Regexp object to BSON.
@@ -200,15 +180,11 @@ module BSON
       #   and 'u' to make \w, \W, etc. match unicode.
       #
       # @param [ BSON::ByteBuffer ] buffer The byte buffer to append to.
-      # @param [ true, false ] validating_keys
       #
       # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
       #
       # @see http://bsonspec.org/#/specification
-      #
-      # @since 4.2.0
-      def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-        return compile.to_bson(buffer, validating_keys) if options.is_a?(Integer)
+      def to_bson(buffer = ByteBuffer.new)
         buffer.put_cstring(source)
         buffer.put_cstring(options.chars.sort.join)
       end
@@ -219,9 +195,7 @@ module BSON
       #   raw_regexp.as_json
       #
       # @return [ Hash ] The raw regexp as a JSON hash.
-      #
-      # @since 4.2.0
-      def as_json(*args)
+      def as_json(*)
         as_extended_json(mode: :legacy)
       end
 
@@ -234,9 +208,9 @@ module BSON
       # @return [ Hash ] The extended json representation.
       def as_extended_json(**opts)
         if opts[:mode] == :legacy
-          { "$regex" => source, "$options" => options }
+          { '$regex' => source, '$options' => options }
         else
-          {"$regularExpression" => {'pattern' => source, "options" => options}}
+          { '$regularExpression' => { 'pattern' => source, 'options' => options } }
         end
       end
 
@@ -248,24 +222,22 @@ module BSON
       # @param [ Object ] other The object to check against.
       #
       # @return [ true, false ] If the objects are equal.
-      #
-      # @since 4.2.0
       def ==(other)
         return false unless other.is_a?(::Regexp::Raw)
-        pattern == other.pattern &&
-          options == other.options
+
+        pattern == other.pattern && options == other.options
       end
-      alias :eql? :==
+      alias eql? ==
 
       private
 
       def method_missing(method, *arguments)
         return super unless respond_to?(method)
+
         compile.send(method, *arguments)
       end
 
       def options_to_int
-        return options if options.is_a?(Integer)
         opts = 0
         opts |= ::Regexp::IGNORECASE if options.include?(IGNORECASE_VALUE)
         opts |= ::Regexp::MULTILINE if options.include?(NEWLINE_VALUE)
@@ -274,10 +246,15 @@ module BSON
       end
     end
 
+    # Class-level methods to be added to the Regexp class.
     module ClassMethods
-
       # Deserialize the regular expression 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 opts [ nil | :bson ] :mode Decoding mode to use.
@@ -285,9 +262,7 @@ module BSON
       # @return [ Regexp ] The decoded regular expression.
       #
       # @see http://bsonspec.org/#/specification
-      #
-      # @since 2.0.0
-      def from_bson(buffer, **opts)
+      def from_bson(buffer, **_)
         pattern = buffer.get_cstring
         options = buffer.get_cstring
         Raw.new(pattern, options)
@@ -295,14 +270,10 @@ module BSON
     end
 
     # Register this type when the module is loaded.
-    #
-    # @since 2.0.0
     Registry.register(BSON_TYPE, ::Regexp)
   end
 
   # Enrich the core Regexp class with this module.
-  #
-  # @since 2.0.0
-  ::Regexp.send(:include, Regexp)
-  ::Regexp.send(:extend, Regexp::ClassMethods)
+  ::Regexp.include Regexp
+  ::Regexp.extend Regexp::ClassMethods
 end

data/lib/bson/registry.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");
@@ -64,11 +65,6 @@ module BSON
       define_type_reader(type)
     end
 
-    # Raised when trying to get a type from the registry that doesn't exist.
-    #
-    # @since 4.1.0
-    class UnsupportedType < RuntimeError; end
-
     private
 
     def define_type_reader(type)
@@ -81,7 +77,7 @@ module BSON
       message = "Detected unknown BSON type #{byte.inspect} "
       message += (field ? "for fieldname \"#{field}\". " : "in array. ")
       message +="Are you using the latest BSON version?"
-      raise UnsupportedType.new(message)
+      raise Error::UnsupportedType.new(message)
     end
   end
 end

data/lib/bson/specialized.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");
@@ -46,7 +47,7 @@ module BSON
     # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
     # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       buffer
     end