bson 4.2.2 → 4.12.1

data/lib/bson.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.
@@ -57,6 +57,7 @@ module BSON
 end
 
 require "bson/config"
+require "bson/error"
 require "bson/registry"
 require "bson/specialized"
 require "bson/json"
@@ -70,8 +71,10 @@ require "bson/code"
 require "bson/code_with_scope"
 require "bson/date"
 require "bson/date_time"
+require "bson/db_pointer"
 require "bson/decimal128"
 require "bson/document"
+require "bson/ext_json"
 require "bson/false_class"
 require "bson/float"
 require "bson/hash"
@@ -101,7 +104,7 @@ begin
   else
     require "bson_native"
   end
-rescue LoadError
-  $stderr.puts("Failed to load the necessary extensions.")
+rescue LoadError => e
+  $stderr.puts("Failed to load the necessary extensions: #{e.class}: #{e}")
   raise
 end

data/lib/bson/active_support.rb

@@ -0,0 +1,17 @@
+# Copyright (C) 2018-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.
+
+# Require this file if using BSON with ActiveSupport.
+
+require "bson/time_with_zone"

data/lib/bson/array.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.
@@ -41,15 +41,22 @@ module BSON
     #
     # @since 2.0.0
     def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      position = buffer.length
-      buffer.put_int32(0)
-      each_with_index do |value, index|
-        buffer.put_byte(value.bson_type)
-        buffer.put_cstring(index.to_s)
-        value.to_bson(buffer, validating_keys)
+      if buffer.respond_to?(:put_array)
+        buffer.put_array(self, validating_keys)
+      else
+        position = buffer.length
+        buffer.put_int32(0)
+        each_with_index do |value, index|
+          unless value.respond_to?(:bson_type)
+            raise Error::UnserializableClass, "Array element at position #{index} does not define its BSON serialized type: #{value}"
+          end
+          buffer.put_byte(value.bson_type)
+          buffer.put_cstring(index.to_s)
+          value.to_bson(buffer, validating_keys)
+        end
+        buffer.put_byte(NULL_BYTE)
+        buffer.replace_int32(position, buffer.length - position)
       end
-      buffer.put_byte(NULL_BYTE)
-      buffer.replace_int32(position, buffer.length - position)
     end
 
     # Convert the array to an object id. This will only work for arrays of size
@@ -60,7 +67,7 @@ module BSON
     #
     # @note This is used for repairing legacy bson data.
     #
-    # @raise [ InvalidObjectId ] If the array is not 12 elements.
+    # @raise [ BSON::ObjectId::Invalid ] If the array is not 12 elements.
     #
     # @return [ String ] The raw object id bytes.
     #
@@ -81,25 +88,58 @@ module BSON
       map { |value| value.to_bson_normalized_value }
     end
 
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # This method recursively invokes +as_extended_json+ with the provided
+    # options on each array element.
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Array ] This array converted to extended json representation.
+    def as_extended_json(**options)
+      map do |item|
+        item.as_extended_json(**options)
+      end
+    end
+
     module ClassMethods
 
       # Deserialize the array from BSON.
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ Array ] The decoded array.
       #
       # @see http://bsonspec.org/#/specification
       #
       # @since 2.0.0
-      def from_bson(buffer)
-        array = new
-        buffer.get_int32 # throw away the length
-        while (type = buffer.get_byte) != NULL_BYTE
-          buffer.get_cstring
-          array << BSON::Registry.get(type).from_bson(buffer)
+      def from_bson(buffer, **options)
+        if buffer.respond_to?(:get_array)
+          buffer.get_array(**options)
+        else
+          array = new
+          start_position = buffer.read_position
+          expected_byte_size = buffer.get_int32
+          while (type = buffer.get_byte) != NULL_BYTE
+            buffer.get_cstring
+            cls = BSON::Registry.get(type)
+            value = if options.empty?
+              cls.from_bson(buffer)
+            else
+              cls.from_bson(buffer, **options)
+            end
+            array << value
+          end
+          actual_byte_size = buffer.read_position - start_position
+          if actual_byte_size != expected_byte_size
+            raise Error::BSONDecodeError, "Expected array to take #{expected_byte_size} bytes but it took #{actual_byte_size} bytes"
+          end
+          array
         end
-        array
       end
     end
 

data/lib/bson/binary.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.
@@ -31,6 +31,12 @@ module BSON
 
     # The mappings of subtypes to their single byte identifiers.
     #
+    # @note subtype 6 (ciphertext) is used for the Client-Side Encryption
+    #   feature. Data represented by this subtype is often encrypted, but
+    #   may also be plaintext. All instances of this subtype necessary for
+    #   Client-Side Encryption will be created internally by the Ruby driver.
+    #   An application should not create new BSON::Binary objects of this subtype.
+    #
     # @since 2.0.0
     SUBTYPES = {
       :generic => 0.chr,
@@ -39,6 +45,7 @@ module BSON
       :uuid_old => 3.chr,
       :uuid => 4.chr,
       :md5 => 5.chr,
+      :ciphertext => 6.chr,
       :user => 128.chr
     }.freeze
 
@@ -47,13 +54,17 @@ module BSON
     # @since 2.0.0
     TYPES = SUBTYPES.invert.freeze
 
-    # @!attribute data
-    #   @return [ Object ] The raw binary data.
-    #   @since 2.0.0
-    # @!attribute type
-    #   @return [ Symbol ] The binary type.
-    #   @since 2.0.0
-    attr_reader :data, :type
+    # @return [ String ] The raw binary data.
+    #
+    # The string is always stored in BINARY encoding.
+    #
+    # @since 2.0.0
+    attr_reader :data
+
+    # @return [ Symbol ] The binary type.
+    #
+    # @since 2.0.0
+    attr_reader :type
 
     # Determine if this binary object is equal to another object.
     #
@@ -90,21 +101,61 @@ module BSON
     # @return [ Hash ] The binary as a JSON hash.
     #
     # @since 2.0.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
-      { "$binary" => Base64.encode64(data), "$type" => type }
+      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)
+      subtype = SUBTYPES[type].each_byte.map { |c| c.to_s(16) }.join
+      if subtype.length == 1
+        subtype = "0#{subtype}"
+      end
+
+      value = Base64.encode64(data).strip
+
+      if options[:mode] == :legacy
+        { "$binary" => value, "$type" => subtype }
+      else
+        { "$binary" => {'base64' => value, "subType" => subtype }}
+      end
     end
 
     # Instantiate the new binary object.
     #
+    # This method accepts a string in any encoding; however, if a string is
+    # of a non-BINARY encoding, the encoding is set to BINARY. This does not
+    # change the bytes of the string but it means that applications referencing
+    # the data of a Binary instance cannot assume it is in a non-binary
+    # encoding, even if the string given to the constructor was in such an
+    # encoding.
+    #
     # @example Instantiate a binary.
     #   BSON::Binary.new(data, :md5)
     #
-    # @param [ Object ] data The raw binary data.
+    # @param [ String ] data The raw binary data.
     # @param [ Symbol ] type The binary type.
     #
     # @since 2.0.0
     def initialize(data = "", type = :generic)
       validate_type!(type)
+
+      # The Binary class used to force encoding to BINARY when serializing to
+      # BSON. Instead of doing that during serialization, perform this
+      # operation during Binary construction to make it clear that once
+      # the string is given to the Binary, the data is treated as a binary
+      # string and not a text string in any encoding.
+      unless data.encoding == Encoding.find('BINARY')
+        data = data.dup.force_encoding('BINARY')
+      end
+
       @data = data
       @type = type
     end
@@ -121,6 +172,70 @@ module BSON
       "<BSON::Binary:0x#{object_id} type=#{type} data=0x#{data[0, 8].unpack('H*').first}...>"
     end
 
+    # Returns a string representation of the UUID stored in this Binary.
+    #
+    # If the Binary is of subtype 4 (:uuid), this method returns the UUID
+    # in RFC 4122 format. If the representation parameter is provided, it
+    # must be the value :standard as a symbol or a string.
+    #
+    # If the Binary is of subtype 3 (:uuid_old), this method requires that
+    # the representation parameter is provided and is one of :csharp_legacy,
+    # :java_legacy or :python_legacy or the equivalent strings. In this case
+    # the method assumes the Binary stores the UUID in the specified format,
+    # transforms the stored bytes to the standard RFC 4122 representation
+    # and returns the UUID in RFC 4122 format.
+    #
+    # If the Binary is of another subtype, this method raises TypeError.
+    #
+    # @param [ Symbol ] representation How to interpret the UUID.
+    #
+    # @return [ String ] The string representation of the UUID.
+    #
+    # @raise [ TypeError ] If the subtype of Binary is not :uuid nor :uuid_old.
+    # @raise [ ArgumentError ] If the representation other than :standard
+    #   is requested for Binary subtype 4 (:uuid), if :standard representation
+    #   is requested for Binary subtype 3 (:uuid_old), or if an invalid
+    #   representation is requested.
+    #
+    # @api experimental
+    def to_uuid(representation = nil)
+      if representation.is_a?(String)
+        raise ArgumentError, "Representation must be given as a symbol: #{representation}"
+      end
+      case type
+      when :uuid
+        if representation && representation != :standard
+          raise ArgumentError, "Binary of type :uuid can only be stringified to :standard representation, requested: #{representation.inspect}"
+        end
+
+        data.split('').map { |n| '%02x' % n.ord }.join.sub(/\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/, '\1-\2-\3-\4-\5')
+      when :uuid_old
+        if representation.nil?
+          raise ArgumentError, 'Representation must be specified for BSON::Binary objects of type :uuid_old'
+        end
+
+        hex = data.split('').map { |n| '%02x' % n.ord }.join
+
+        case representation
+        when :standard
+          raise ArgumentError, 'BSON::Binary objects of type :uuid_old cannot be stringified to :standard representation'
+        when :csharp_legacy
+          hex.sub(/\A(..)(..)(..)(..)(..)(..)(..)(..)(.{16})\z/, '\4\3\2\1\6\5\8\7\9')
+        when :java_legacy
+          hex.sub(/\A(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)\z/) do |m|
+            "#{$8}#{$7}#{$6}#{$5}#{$4}#{$3}#{$2}#{$1}" +
+            "#{$16}#{$15}#{$14}#{$13}#{$12}#{$11}#{$10}#{$9}"
+          end
+        when :python_legacy
+          hex
+        else
+          raise ArgumentError, "Invalid representation: #{representation}"
+        end.sub(/\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/, '\1-\2-\3-\4-\5')
+      else
+        raise TypeError, "The type of Binary must be :uuid or :uuid_old, this object is: #{type.inspect}"
+      end
+    end
+
     # Encode the binary type
     #
     # @example Encode the binary.
@@ -136,7 +251,7 @@ module BSON
       buffer.put_int32(0)
       buffer.put_byte(SUBTYPES[type])
       buffer.put_int32(data.bytesize) if type == :old
-      buffer.put_bytes(data.force_encoding(BINARY))
+      buffer.put_bytes(data)
       buffer.replace_int32(position, buffer.length - position - 5)
     end
 
@@ -144,19 +259,76 @@ module BSON
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ Binary ] The decoded binary data.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
+    def self.from_bson(buffer, **options)
       length = buffer.get_int32
-      type = TYPES[buffer.get_byte]
+      type_byte = buffer.get_byte
+      type = TYPES[type_byte]
+      if type.nil?
+        raise Error::UnsupportedBinarySubtype,
+          "BSON data contains unsupported binary subtype #{'0x%02x' % type_byte.ord}"
+      end
+
       length = buffer.get_int32 if type == :old
       data = buffer.get_bytes(length)
       new(data, type)
     end
 
+    # Creates a BSON::Binary from a string representation of a UUID.
+    #
+    # The UUID may be given in either 00112233-4455-6677-8899-aabbccddeeff or
+    # 00112233445566778899AABBCCDDEEFF format - specifically, any dashes in
+    # the UUID are removed and both upper and lower case letters are acceptable.
+    #
+    # The input UUID string is always interpreted to be in the RFC 4122 format.
+    #
+    # If representation is not provided, this method creates a BSON::Binary
+    # of subtype 4 (:uuid). If representation is provided, it must be one of
+    # :standard, :csharp_legacy, :java_legacy or :python_legacy. If
+    # representation is :standard, this method creates a subtype 4 (:uuid)
+    # binary which is the same behavior as if representation was not provided.
+    # For other representations, this method creates a Binary of subtype 3
+    # (:uuid_old) with the UUID converted to the appropriate legacy MongoDB
+    # UUID storage format.
+    #
+    # @param [ String ] uuid The string representation of the UUID.
+    # @param [ Symbol ] representation How to interpret the UUID.
+    #
+    # @return [ Binary ] The binary.
+    #
+    # @raise [ ArgumentError ] If invalid representation is requested.
+    #
+    # @api experimental
+    def self.from_uuid(uuid, representation = nil)
+      if representation.is_a?(String)
+        raise ArgumentError, "Representation must be given as a symbol: #{representation}"
+      end
+      uuid_binary = uuid.gsub('-', '').scan(/../).map(&:hex).map(&:chr).join
+      case representation && representation
+      when nil, :standard
+        new(uuid_binary, :uuid)
+      when :csharp_legacy
+        uuid_binary.sub!(/\A(.)(.)(.)(.)(.)(.)(.)(.)(.{8})\z/, '\4\3\2\1\6\5\8\7\9')
+        new(uuid_binary, :uuid_old)
+      when :java_legacy
+        uuid_binary.sub!(/\A(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)\z/) do |m|
+          "#{$8}#{$7}#{$6}#{$5}#{$4}#{$3}#{$2}#{$1}" +
+          "#{$16}#{$15}#{$14}#{$13}#{$12}#{$11}#{$10}#{$9}"
+        end
+        new(uuid_binary, :uuid_old)
+      when :python_legacy
+        new(uuid_binary, :uuid_old)
+      else
+        raise ArgumentError, "Invalid representation: #{representation}"
+      end
+    end
+
     # Raised when providing an invalid type to the Binary.
     #
     # @since 2.0.0

data/lib/bson/boolean.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.
@@ -31,13 +31,22 @@ module 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.