bson 4.2.2 → 4.12.1

data/lib/bson/code.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.
@@ -55,7 +55,19 @@ module BSON
     # @return [ Hash ] The code 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)
       { "$code" => javascript }
     end
 
@@ -89,12 +101,14 @@ module BSON
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ TrueClass, FalseClass ] The decoded code.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
+    def self.from_bson(buffer, **options)
       new(buffer.get_string)
     end
 

data/lib/bson/code_with_scope.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.
@@ -59,8 +59,20 @@ module BSON
     # @return [ Hash ] The code with scope as a JSON hash.
     #
     # @since 2.0.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
-      { "$code" => javascript, "$scope" => scope }
+      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)
+      { "$code" => javascript, "$scope" => scope.as_extended_json(**options) }
     end
 
     # Instantiate the new code with scope.
@@ -99,14 +111,29 @@ module BSON
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ TrueClass, FalseClass ] The decoded code with scope.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
-      buffer.get_int32 # Throw away the total length.
-      new(buffer.get_string, ::Hash.from_bson(buffer))
+    def self.from_bson(buffer, **options)
+      # Code with scope has a length (?) field which is not needed for
+      # decoding, but spec tests want this field validated.
+      start_position = buffer.read_position
+      length = buffer.get_int32
+      javascript = buffer.get_string
+      scope = if options.empty?
+        ::Hash.from_bson(buffer)
+      else
+        ::Hash.from_bson(buffer, **options)
+      end
+      read_bytes = buffer.read_position - start_position
+      if read_bytes != length
+        raise Error::BSONDecodeError, "CodeWithScope invalid: claimed length #{length}, actual length #{read_bytes}"
+      end
+      new(javascript, scope)
     end
 
     # Register this type when the module is loaded.

data/lib/bson/config.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2016 MongoDB Inc.
+# 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.

data/lib/bson/date.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.
@@ -16,6 +16,16 @@ require 'date'
 
 module BSON
 
+  # Julian day of Date 1970-01-01 - UNIX timestamp reference.
+  #
+  # @api private
+  DATE_REFERENCE = ::Date.new(1970, 1, 1).jd
+
+  # Number of miliseconds in a day.
+  #
+  # @api private
+  MILLISECONDS_IN_DAY = 60 * 60 * 24 * 1_000
+
   # Injects behaviour for encoding date values to raw bytes as specified by
   # the BSON spec for time.
   #
@@ -35,7 +45,7 @@ module BSON
     #
     # @since 2.1.0
     def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      ::Time.utc(year, month, day).to_bson(buffer)
+      buffer.put_int64((jd - DATE_REFERENCE) * MILLISECONDS_IN_DAY)
     end
 
     # Get the BSON type for the date.

data/lib/bson/date_time.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.
@@ -35,7 +35,7 @@ module BSON
     #
     # @since 2.1.0
     def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      to_time.to_bson(buffer)
+      gregorian.to_time.to_bson(buffer)
     end
   end
 

data/lib/bson/db_pointer.rb

@@ -0,0 +1,110 @@
+# Copyright (C) 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 and decoding DBPointer values to and from
+  # raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  class DbPointer
+    include JSON
+
+    # A DBPointer is type 0x0C in the BSON spec.
+    BSON_TYPE = 0x0C.chr.force_encoding(BINARY).freeze
+
+    # Create a new DBPointer object.
+    #
+    # @param [ String ] ref The database collection name.
+    # @param [ BSON::ObjectId ] id The DBPointer id.
+    def initialize(ref, id)
+      @ref = ref
+      @id = id
+    end
+
+    # Return the collection name.
+    #
+    # @return [ String ] The database collection name.
+    attr_reader :ref
+
+    # Return the DbPointer's id.
+    #
+    # @return [ BSON::ObjectId ] The id of the DbPointer instance
+    attr_reader :id
+
+    # Determine if this DBPointer object is equal to another object.
+    #
+    # @param [ Object ] other The object to compare against.
+    #
+    # @return [ true | false ] If the objects are equal
+    def ==(other)
+      return false unless other.is_a?(DbPointer)
+      ref == other.ref && id == other.id
+    end
+
+    # Get the DBPointer as JSON hash data
+    #
+    # @return [ Hash ] The DBPointer as a JSON hash.
+    #
+    # @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 options [ true | false ] :relaxed Whether to produce relaxed
+    #   extended JSON representation.
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
+      {'$dbPointer' => { "$ref" => ref, '$id' => id.as_extended_json }}
+    end
+
+    # Encode the DBPointer.
+    #
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
+    #
+    # @see http://bsonspec.org/#/specification
+    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+      buffer.put_string(ref)
+      id.to_bson(buffer, validating_keys)
+      buffer
+    end
+
+    # Deserialize a DBPointer from BSON.
+    #
+    # @param [ ByteBuffer ] buffer The byte buffer.
+    # @param [ Hash ] options
+    #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
+    # @return [ BSON::DbPointer ] The decoded DBPointer.
+    #
+    # @see http://bsonspec.org/#/specification
+    def self.from_bson(buffer, **options)
+      ref = buffer.get_string
+      id = if options.empty?
+        ObjectId.from_bson(buffer)
+      else
+        ObjectId.from_bson(buffer, **options)
+      end
+      new(ref, id)
+    end
+
+    # Register this type when the module is loaded.
+    Registry.register(BSON_TYPE, self)
+  end
+end

data/lib/bson/decimal128.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2016 MongoDB Inc.
+# 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.
@@ -63,7 +63,19 @@ module BSON
     # @return [ Hash ] The number as a JSON hash.
     #
     # @since 4.2.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)
       { EXTENDED_JSON_KEY => to_s }
     end
 
@@ -178,7 +190,7 @@ module BSON
     #
     # @since 4.2.0
     def to_big_decimal
-      @big_decimal ||= BigDecimal.new(to_s)
+      @big_decimal ||= BigDecimal(to_s)
     end
 
     private
@@ -197,10 +209,12 @@ module BSON
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ BSON::Decimal128 ] The decimal object.
       #
       # @since 4.2.0
-      def from_bson(buffer)
+      def from_bson(buffer, **options)
         from_bits(*buffer.get_decimal128_bytes.unpack('Q<*'))
       end
 

data/lib/bson/decimal128/builder.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2016 MongoDB Inc.
+# 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.

data/lib/bson/document.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.
@@ -35,8 +35,43 @@ module BSON
   class Document < ::Hash
 
     # Get a value from the document for the provided key. Can use string or
-    # symbol access, but the fastest will be to always provide a key that is of
-    # the same type as the stored keys.
+    # symbol access, with string access being the faster of the two.
+    #
+    # @overload fetch(key)
+    #   Returns a value from the hash for the given key. If the key does
+    #   not exist, raises KeyError exception.
+    #
+    # @overload fetch(key, default)
+    #   Returns a value from the hash for the given key. If the key does not
+    #   exist, returns *default*.
+    #
+    # @overload fetch(key, &block)
+    #   Returns a value from the hash for the given key. If the key does not
+    #   exist, returns the value of the block called with the key.
+    #
+    # @example Get an element for the key.
+    #   document.fetch("field")
+    #
+    # @example Get an element for the key by symbol with a default.
+    #   document.fetch(:field, 'foo')
+    #
+    # @example Get an element for the key by symbol with a block default.
+    #   document.fetch(:field) { |key| key.upcase }
+    #
+    # @param [ String, Symbol ] key The key to look up.
+    # @param [ Object ] default Returned value if key does not exist.
+    # @yield [key] Block returning default value for the given key.
+    #
+    # @return [ Object ] The found value. Raises KeyError if none found.
+    #
+    # @since 4.4.0
+    def fetch(key, *args, &block)
+      key = convert_key(key)
+      super(key, *args, &block)
+    end
+
+    # Get a value from the document for the provided key. Can use string or
+    # symbol access, with string access being the faster of the two.
     #
     # @example Get an element for the key.
     #   document["field"]
@@ -44,7 +79,7 @@ module BSON
     # @example Get an element for the key by symbol.
     #   document[:field]
     #
-    # @param [ String, Symbol ] key The key to lookup.
+    # @param [ String, Symbol ] key The key to look up.
     #
     # @return [ Object ] The found value, or nil if none found.
     #
@@ -53,7 +88,49 @@ module BSON
       super(convert_key(key))
     end
 
-    # Set a value on the document. Will normalize symbol keys into strings.
+    # Stores a key-value pair in the current document.
+    #
+    # Since BSON documents provide deep indifferent access (both strings and
+    # symbols are accepted as keys, recursively), the value may be converted
+    # to facilitate indifferent access. This conversion is performed for
+    # built-in Array and Hash classes, and other classes can override
+    # +to_bson_normalized_value+ method to provide custom conversion logic.
+    # For example:
+    #
+    #     doc = BSON::Document.new
+    #     doc[:a] = {b: {c: 'd'}}
+    #     doc['a']['b']['c']
+    #     # => "d"
+    #
+    # Note that due to this conversion, the object that is stored in the
+    # receiver Document may be different from the object supplied as the
+    # right hand side of the assignment. In Ruby, the result of assignment
+    # is the right hand side, not the return value of []= method.
+    # Because of this, modifying the result of assignment generally does not
+    # work as intended:
+    #
+    #     doc = BSON::Document.new
+    #     foo = (doc[:a] = {b: {c: 'd'}})
+    #     # foo is original Hash with symbol keys
+    #     foo['test'] = 'test'
+    #     # doc is not modified
+    #     doc
+    #     # => {"a"=>{"b"=>{"c"=>"d"}}}
+    #
+    # This behavior can be encountered when defaulting document contents with
+    # []= in a method, such as:
+    #
+    #     def foo
+    #       # @doc is a BSON::Document
+    #       @doc[:foo] ||= calculation
+    #     end
+    #
+    # The above method should be written as follows to allow chaining:
+    #
+    #     def foo
+    #       # @doc is a BSON::Document
+    #       @doc[:foo] ||= calculation and @doc[:foo]
+    #     end
     #
     # @example Set a value on the document.
     #   document[:test] = "value"
@@ -172,6 +249,76 @@ module BSON
 
     alias :update :merge!
 
+    if instance_methods.include?(:dig)
+      # Retrieves the value object corresponding to the each key objects repeatedly.
+      # Will normalize symbol keys into strings.
+      #
+      # @example Get value from nested sub-documents, handling missing levels.
+      #   document # => { :key1 => { "key2" => "value"}}
+      #   document.dig(:key1, :key2) # => "value"
+      #   document.dig("key1", "key2") # => "value"
+      #   document.dig("foo", "key2") # => nil
+      #
+      # @param [ Array<String, Symbol> ] *keys Keys, which constitute a "path" to the nested value.
+      #
+      # @return [ Object, NilClass ] The requested value or nil.
+      #
+      # @since 3.0.0
+      def dig(*keys)
+        super(*keys.map{|key| convert_key(key)})
+      end
+    end
+
+    # Slices a document to include only the given keys.
+    # Will normalize symbol keys into strings.
+    # (this method is backported from ActiveSupport::Hash)
+    #
+    # @example Get a document/hash with only the `name` and `age` fields present
+    #   document # => { _id: <ObjectId>, :name => "John", :age => 30, :location => "Earth" }
+    #   document.slice(:name, 'age') # => { "name": "John", "age" => 30 }
+    #   document.slice('name') # => { "name" => "John" }
+    #   document.slice(:foo) # => {}
+    #
+    # @param [ Array<String, Symbol> ] *keys Keys, that will be kept in the resulting document
+    #
+    # @return [ BSON::Document ] The document with only the selected keys
+    #
+    # @since 4.3.1
+    def slice(*keys)
+      keys.each_with_object(self.class.new) do |key, hash|
+        if key?(key)
+          hash[key] = self[key]
+        end
+      end
+    end
+
+    # Returns a new document consisting of the current document minus the
+    # specified keys.
+    #
+    # The keys to be removed can be specified as either strings or symbols.
+    #
+    # @example Get a document/hash with only the `name` and `age` fields removed
+    #   document # => { _id: <ObjectId>, :name => 'John', :age => 30, :location => 'Earth' }
+    #   document.except(:name, 'age') # => { _id: <ObjectId>, location: 'Earth' }
+    #
+    # @param [ Array<String, Symbol> ] *keys Keys, that will be removed in the resulting document
+    #
+    # @return [ BSON::Document ] The document with the specified keys removed.
+    #
+    # @note This method is always defined, even if Hash already contains a
+    #   definition of #except, because ActiveSupport unconditionally defines
+    #   its version of #except which doesn't work for BSON::Document which
+    #   causes problems if ActiveSupport is loaded after bson-ruby is.
+    def except(*keys)
+      copy = dup
+      keys.each {|key| copy.delete(key)}
+      copy
+    end
+
+    def symbolize_keys!
+      raise ArgumentError, 'symbolize_keys! is not supported on BSON::Document instances. Please convert the document to hash first (using #to_h), then call #symbolize_keys! on the Hash instance'
+    end
+
     private
 
     def convert_key(key)