bson 4.1.1 → 5.2.0

data/lib/bson/boolean.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.
@@ -25,19 +27,28 @@ module BSON
     # A boolean is type 0x08 in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 8.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(8.chr, encoding: BINARY).freeze
 
     # Deserialize a boolean from BSON.
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ TrueClass, FalseClass ] The decoded boolean.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
-      buffer.get_byte == TrueClass::TRUE_BYTE
+    def self.from_bson(buffer, **options)
+      case v = buffer.get_byte
+      when TrueClass::TRUE_BYTE
+        true
+      when FalseClass::FALSE_BYTE
+        false
+      else
+        raise Error::BSONDecodeError, "Invalid boolean byte value: #{v}"
+      end
     end
 
     # Register this type when the module is loaded.

data/lib/bson/code.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.
@@ -25,7 +27,7 @@ module BSON
     # A code is type 0x0D in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 13.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(13.chr, encoding: BINARY).freeze
 
     # @!attribute javascript
     #   @return [ String ] The javascript code.
@@ -47,15 +49,24 @@ module BSON
       javascript == other.javascript
     end
 
-    # Get the code as JSON hash data.
-    #
-    # @example Get the code as a JSON hash.
-    #   code.as_json
+    # Return a representation of the object for use in
+    # application-level JSON serialization. Since BSON::Code
+    # is used exclusively in BSON-related contexts, this
+    # method returns the canonical Extended JSON representation.
+    #
+    # @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 code 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)
       { "$code" => javascript }
     end
 
@@ -76,12 +87,12 @@ module BSON
     # @example Encode the code.
     #   code.to_bson
     #
-    # @return [ String ] The encoded string.
+    # @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_string(javascript) # @todo: was formerly to_bson_string
     end
 
@@ -89,12 +100,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,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 code with scope is type 0x0F in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 15.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(15.chr, encoding: BINARY).freeze
 
     # @!attribute javascript
     #   @return [ String ] The javascript code.
@@ -51,16 +53,25 @@ module BSON
       javascript == other.javascript && scope == other.scope
     end
 
-    # Get the code with scope as JSON hash data.
-    #
-    # @example Get the code with scope as a JSON hash.
-    #   code_with_scope.as_json
+    # Return a representation of the object for use in
+    # application-level JSON serialization. Since BSON::CodeWithScope
+    # is used exclusively in BSON-related contexts, this
+    # method returns the canonical Extended JSON representation.
+    #
+    # @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 code with scope 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)
-      { "$code" => javascript, "$scope" => scope }
+    # @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.
@@ -82,12 +93,12 @@ module BSON
     # @example Encode the code with scope.
     #   code_with_scope.to_bson
     #
-    # @return [ String ] The encoded string.
+    # @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)
       position = buffer.length
       buffer.put_int32(0)
       buffer.put_string(javascript)
@@ -99,14 +110,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,6 @@
-# Copyright (C) 2016 MongoDB Inc.
+# 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.
@@ -20,32 +22,5 @@ module BSON
   module Config
     extend self
 
-    # Set the configuration option for BSON to validate keys or not.
-    #
-    # @example Set the config option.
-    #   BSON::Config.validating_keys = true
-    #
-    # @param [ true, false ] value The value to set.
-    #
-    # @return [ true, false ] The value.
-    #
-    # @since 4.1.0
-    def validating_keys=(value)
-      @validating_keys = value
-    end
-
-    # Returns true if BSON will validate the document keys on serialization to
-    # determine if they contain invalid MongoDB values. Invalid keys start with
-    # '$' or contain a '.' in them.
-    #
-    # @example Is BSON validating keys?
-    #   BSON::Config.validating_keys?
-    #
-    # @return [ true, false ] If BSON is validating keys?
-    #
-    # @since 4.1.0
-    def validating_keys?
-      !!@validating_keys
-    end
   end
 end

data/lib/bson/date.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.
@@ -16,6 +18,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.
   #
@@ -29,13 +41,13 @@ module BSON
     # @example Get the date as encoded BSON.
     #   Date.new(2012, 1, 1).to_bson
     #
-    # @return [ String ] The encoded string.
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.1.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      ::Time.utc(year, month, day).to_bson(buffer)
+    def to_bson(buffer = ByteBuffer.new)
+      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,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.
@@ -29,13 +31,13 @@ module BSON
     # @example Get the date time as encoded BSON.
     #   DateTime.new(2012, 1, 1, 0, 0, 0).to_bson
     #
-    # @return [ String ] The encoded string.
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.1.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      to_time.to_bson(buffer)
+    def to_bson(buffer = ByteBuffer.new)
+      gregorian.to_time.to_bson(buffer)
     end
   end
 

data/lib/bson/db_pointer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+# rubocop:todo all
+# 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 = ::String.new(0x0C.chr, 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
+
+    # Return a representation of the object for use in
+    # application-level JSON serialization. Since BSON::DbPointer
+    # is used exclusively in BSON-related contexts, this
+    # method returns the canonical Extended JSON representation.
+    #
+    # @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 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)
+      buffer.put_string(ref)
+      id.to_bson(buffer)
+      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/dbref.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+# Copyright (C) 2015-2021 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
+
+  # Represents a DBRef document in the database.
+  class DBRef < Document
+    include JSON
+
+    # The constant for the collection reference field.
+    #
+    # @deprecated
+    COLLECTION = '$ref'.freeze
+
+    # The constant for the id field.
+    #
+    # @deprecated
+    ID = '$id'.freeze
+
+    # The constant for the database field.
+    #
+    # @deprecated
+    DATABASE = '$db'.freeze
+
+    # @return [ String ] collection The collection name.
+    def collection
+      self['$ref']
+    end
+
+    # @return [ BSON::ObjectId ] id The referenced document id.
+    def id
+      self['$id']
+    end
+
+    # @return [ String ] database The database name.
+    def database
+      self['$db']
+    end
+
+    # Get the DBRef as a JSON document
+    #
+    # @example Get the DBRef as a JSON hash.
+    #   dbref.as_json
+    #
+    # @return [ Hash ] The max key as a JSON hash.
+    def as_json(*args)
+      {}.update(self)
+    end
+
+    # Instantiate a new DBRef.
+    #
+    # @example Create the DBRef - hash API.
+    #   BSON::DBRef.new({'$ref' => 'users', '$id' => id, '$db' => 'database'})
+    #
+    # @example Create the DBRef - legacy API.
+    #   BSON::DBRef.new('users', id, 'database')
+    #
+    # @param [ Hash | String ] hash_or_collection The DBRef hash, when using
+    #   the hash API. It must contain $ref and $id. When using the legacy API,
+    #   this parameter must be a String containing the collection name.
+    # @param [ Object ] id The object id, when using the legacy API.
+    # @param [ String ] database The database name, when using the legacy API.
+    #
+    # @raise [ BSON::Error::InvalidDBRefArgument ] if giving invalid arguments
+    #   to the constructor.
+    def initialize(hash_or_collection, id = nil, database = nil)
+      if hash_or_collection.is_a?(Hash)
+        hash = hash_or_collection
+
+        unless id.nil? && database.nil?
+          raise Error::InvalidDBRefArgument, 'When using the hash API, DBRef constructor accepts only one argument'
+        end
+      else
+        warn("BSON::DBRef constructor called with the legacy API - please use the hash API instead")
+
+        if id.nil?
+          raise Error::InvalidDBRefArgument, 'When using the legacy constructor API, id must be provided'
+        end
+
+        hash = {
+          :$ref => hash_or_collection,
+          :$id => id,
+          :$db => database,
+        }
+      end
+
+      hash = reorder_fields(hash)
+      %w($ref $id).each do |key|
+        unless hash[key]
+          raise Error::InvalidDBRefArgument, "DBRef must have #{key}: #{hash}"
+        end
+      end
+
+      unless hash['$ref'].is_a?(String)
+        raise Error::InvalidDBRefArgument, "The value for key $ref must be a string, got: #{hash['$ref']}"
+      end
+
+      if db = hash['$db']
+        unless db.is_a?(String)
+          raise Error::InvalidDBRefArgument, "The value for key $db must be a string, got: #{hash['$db']}"
+        end
+      end
+
+      super(hash)
+    end
+
+    # Converts the DBRef to raw BSON.
+    #
+    # @example Convert the DBRef to raw BSON.
+    #   dbref.to_bson
+    #
+    # @param [ BSON::ByteBuffer ] buffer The encoded BSON buffer to append to.
+    #
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
+    def to_bson(buffer = ByteBuffer.new)
+      as_json.to_bson(buffer)
+    end
+
+    private
+
+    # Reorder the fields of the given Hash to have $ref first, $id second,
+    # and $db third. The rest of the fields in the hash can come in any
+    # order after that.
+    #
+    # @param [ Hash ] hash The input hash. Must be a valid dbref.
+    #
+    # @return [ Hash ] The hash with it's fields reordered.
+    def reorder_fields(hash)
+      hash = BSON::Document.new(hash)
+      reordered = {}
+      reordered['$ref'] = hash.delete('$ref')
+      reordered['$id'] = hash.delete('$id')
+      if db = hash.delete('$db')
+        reordered['$db'] = db
+      end
+
+      reordered.update(hash)
+    end
+  end
+end