bson 4.1.1 → 5.2.0

data/lib/bson/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.
@@ -17,6 +19,20 @@ module BSON
   # Injects behaviour for encoding and decoding time values to
   # and from raw bytes as specified by the BSON spec.
   #
+  # @note
+  #   Ruby time can have nanosecond precision:
+  #   +Time.utc(2020, 1, 1, 0, 0, 0, 999_999_999/1000r)+
+  #   +Time#usec+ returns the number of microseconds in the time, and
+  #   if the time has nanosecond precision the sub-microsecond part is
+  #   truncated (the value is floored to the nearest millisecond).
+  #   MongoDB only supports millisecond precision; we truncate the
+  #   sub-millisecond part of microseconds (floor to the nearest millisecond).
+  #   Note that if a time is constructed from a floating point value,
+  #   the microsecond value may round to the starting floating point value
+  #   but due to flooring, the time after serialization may end up to
+  #   be different than the starting floating point value.
+  #   It is recommended that time calculations use integer math only.
+  #
   # @see http://bsonspec.org/#/specification
   #
   # @since 2.0.0
@@ -25,20 +41,63 @@ module BSON
     # A time is type 0x09 in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 9.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(9.chr, encoding: BINARY).freeze
 
     # Get the time as encoded BSON.
     #
+    # @note The time is floored to the nearest millisecond.
+    #
     # @example Get the time as encoded BSON.
     #   Time.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.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      buffer.put_int64((to_i * 1000) + (usec / 1000))
+    def to_bson(buffer = ByteBuffer.new)
+      value = _bson_to_i * 1000 + usec.divmod(1000).first
+      buffer.put_int64(value)
+    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).
+    #
+    # @note The time is floored to the nearest millisecond.
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
+      utc_time = utc
+      if options[:mode] == :relaxed && (1970..9999).include?(utc_time.year)
+        if utc_time.usec != 0
+          if utc_time.respond_to?(:floor)
+            # Ruby 2.7+
+            utc_time = utc_time.floor(3)
+          else
+            utc_time -= utc_time.usec.divmod(1000).last.to_r / 1000000
+          end
+          {'$date' => utc_time.strftime('%Y-%m-%dT%H:%M:%S.%LZ')}
+        else
+          {'$date' => utc_time.strftime('%Y-%m-%dT%H:%M:%SZ')}
+        end
+      else
+        sec = utc_time._bson_to_i
+        msec = utc_time.usec.divmod(1000).first
+        {'$date' => {'$numberLong' => (sec * 1000 + msec).to_s}}
+      end
+    end
+
+    def _bson_to_i
+      # Workaround for JRuby's #to_i rounding negative timestamps up
+      # rather than down (https://github.com/jruby/jruby/issues/6104)
+      if BSON::Environment.jruby?
+        (self - usec.to_r/1000000).to_i
+      else
+        to_i
+      end
     end
 
     module ClassMethods
@@ -47,13 +106,15 @@ module BSON
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ Time ] The decoded UTC datetime.
       #
       # @see http://bsonspec.org/#/specification
       #
       # @since 2.0.0
-      def from_bson(buffer)
-        seconds, fragment = Int64.from_bson(buffer).divmod(1000)
+      def from_bson(buffer, **options)
+        seconds, fragment = Int64.from_bson(buffer, mode: nil).divmod(1000)
         at(seconds, fragment * 1000).utc
       end
     end

data/lib/bson/time_with_zone.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# rubocop:todo all
+# 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 "active_support/time_with_zone"
+
+module BSON
+
+  # Injects behaviour for encoding ActiveSupport::TimeWithZone values to
+  # raw bytes as specified by the BSON spec for time.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 4.4.0
+  module TimeWithZone
+
+    # Get the ActiveSupport::TimeWithZone as encoded BSON.
+    #
+    # @example Get the ActiveSupport::TimeWithZone as encoded BSON.
+    #   Time.utc(2012, 12, 12, 0, 0, 0).in_time_zone("Pacific Time (US & Canada)").to_bson
+    #
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 4.4.0
+    def to_bson(buffer = ByteBuffer.new)
+      buffer.put_int64((to_i * 1000) + (usec / 1000))
+    end
+
+    # Get the BSON type for the ActiveSupport::TimeWithZone.
+    #
+    # As the ActiveSupport::TimeWithZone is converted to a time, this returns
+    # the BSON type for time.
+    def bson_type
+      ::Time::BSON_TYPE
+    end
+
+    # @api private
+    def _bson_to_i
+      # Workaround for JRuby's #to_i rounding negative timestamps up
+      # rather than down (https://github.com/jruby/jruby/issues/6104)
+      if BSON::Environment.jruby?
+        (self - usec.to_r/1000000).to_i
+      else
+        to_i
+      end
+    end
+  end
+
+  # Enrich the ActiveSupport::TimeWithZone class with this module.
+  #
+  # @since 4.4.0
+  ActiveSupport::TimeWithZone.send(:include, TimeWithZone)
+end

data/lib/bson/timestamp.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.
@@ -21,11 +23,17 @@ module BSON
   # @since 2.0.0
   class Timestamp
     include JSON
+    include Comparable
 
     # A timestamp is type 0x11 in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 17.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(17.chr, encoding: BINARY).freeze
+
+    # Error message if an object other than a Timestamp is compared with this object.
+    #
+    # @since 4.3.0
+    COMPARISON_ERROR_MESSAGE = 'comparison of %s with Timestamp failed'
 
     # @!attribute seconds
     #   @return [ Integer ] The number of seconds.
@@ -52,6 +60,24 @@ module BSON
       seconds == other.seconds && increment == other.increment
     end
 
+    # Determine if this timestamp is greater or less than another object.
+    #
+    # @example Compare the timestamp.
+    #   timestamp < other
+    #
+    # @param [ Object ] other The object to compare against.
+    #
+    # @return [ true, false ] The result of the comparison.
+    #
+    # @since 4.3.0
+    def <=>(other)
+      raise ArgumentError.new(COMPARISON_ERROR_MESSAGE % other.class) unless other.is_a?(Timestamp)
+      return 0 if self == other
+      a = [ seconds, increment ]
+      b = [ other.seconds, other.increment ]
+      [ a, b ].sort[0] == a ? -1 : 1
+    end
+
     # Get the timestamp as JSON hash data.
     #
     # @example Get the timestamp as a JSON hash.
@@ -60,8 +86,20 @@ module BSON
     # @return [ Hash ] The timestamp as a JSON hash.
     #
     # @since 2.0.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
-      { "t" => seconds, "i" => increment }
+      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).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
+      { "$timestamp" => { "t" => seconds, "i" => increment } }
     end
 
     # Instantiate the new timestamp.
@@ -82,28 +120,30 @@ module BSON
     # @example Get the timestamp as BSON.
     #   timestamp.to_bson
     #
-    # @return [ String ] The raw BSON 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?)
-      buffer.put_int32(increment)
-      buffer.put_int32(seconds)
+    def to_bson(buffer = ByteBuffer.new)
+      buffer.put_uint32(increment)
+      buffer.put_uint32(seconds)
     end
 
     # Deserialize timestamp from BSON.
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ Timestamp ] The decoded timestamp.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
-      increment = buffer.get_int32
-      seconds = buffer.get_int32
+    def self.from_bson(buffer, **options)
+      increment = buffer.get_uint32
+      seconds = buffer.get_uint32
       new(seconds, increment)
     end
 

data/lib/bson/true_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.
@@ -25,7 +27,7 @@ module BSON
     # A true value in the BSON spec is 0x01.
     #
     # @since 2.0.0
-    TRUE_BYTE = 1.chr.force_encoding(BINARY).freeze
+    TRUE_BYTE = ::String.new(1.chr, encoding: BINARY).freeze
 
     # The BSON type for true values is the general boolean type of 0x08.
     #
@@ -44,12 +46,12 @@ module BSON
     # @example Get the true boolean as encoded BSON.
     #   true.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_byte(TRUE_BYTE)
     end
   end

data/lib/bson/undefined.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.
@@ -20,12 +22,13 @@ module BSON
   #
   # @since 2.0.0
   class Undefined
+    include JSON
     include Specialized
 
     # Undefined is type 0x06 in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 6.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(6.chr, encoding: BINARY).freeze
 
     # Determine if undefined is equal to another object.
     #
@@ -41,6 +44,29 @@ module BSON
       self.class == other.class
     end
 
+    # Return a string representation of the BSON::Undefined for use in
+    # application-level JSON serialization. This method is intentionally
+    # different from #as_extended_json.
+    #
+    # @example Get the undefined as a JSON-serializable object.
+    #   undefined.as_json
+    #
+    # @return [ nil ] The undefined as nil.
+    def as_json(*args)
+      nil
+    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).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
+      { "$undefined" => true }
+    end
+
     # Register this type when the module is loaded.
     #
     # @since 2.0.0

data/lib/bson/vector.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025-present 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
+  # Vector of numbers along with metadata for binary interoperability.
+  class Vector < ::Array
+    # @return [ Integer ] The data type stored in the vector.
+    attr_reader :dtype
+
+    # @return [ Integer ]  The number of bits in the final byte that are to
+    # be ignored when a vector element's size is less than a byte
+    # and the length of the vector is not a multiple of 8.
+    attr_reader :padding
+
+    # @return [ BSON::ByteBuffer ] The data in the vector.
+    def data
+      self
+    end
+
+    # @param [ ::Array ] data The data to initialize the vector with.
+    # @param [ Integer ] dtype The data type of the vector.
+    # @param [ Integer ] padding The number of bits in the final byte that are to
+    # be ignored when a vector element's size is less than a byte
+    # and the length of the vector is not a multiple of 8.
+    def initialize(data, dtype, padding = 0)
+      @dtype = dtype
+      @padding = padding
+      super(data.dup)
+    end
+  end
+end

data/lib/bson/version.rb

@@ -1,17 +1,9 @@
-# Copyright (C) 2009-2015 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.
+# frozen_string_literal: true
 
 module BSON
-  VERSION = "4.1.1".freeze
+  # The current version of the library.
+  #
+  # NOTE: this file is automatically updated via `rake candidate:create`.
+  # Manual changes to this file may be overwritten by that rake task.
+  VERSION = '5.2.0'
 end

data/lib/bson.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
   #
   # @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.
   #
@@ -38,25 +40,26 @@ module BSON
   # Constant for binary string encoding.
   #
   # @since 2.0.0
-  BINARY = "BINARY".freeze
+  BINARY = "BINARY"
 
   # Constant for bson types that don't actually serialize a value.
   #
   # @since 2.0.0
-  NO_VALUE = "".force_encoding(BINARY).freeze
+  NO_VALUE = ::String.new(encoding: BINARY).freeze
 
   # Constant for a null byte (0x00).
   #
   # @since 2.0.0
-  NULL_BYTE = 0.chr.force_encoding(BINARY).freeze
+  NULL_BYTE = ::String.new(0.chr, encoding: BINARY).freeze
 
   # Constant for UTF-8 string encoding.
   #
   # @since 2.0.0
-  UTF8 = "UTF-8".freeze
+  UTF8 = "UTF-8"
 end
 
 require "bson/config"
+require "bson/error"
 require "bson/registry"
 require "bson/specialized"
 require "bson/json"
@@ -70,10 +73,16 @@ require "bson/code"
 require "bson/code_with_scope"
 require "bson/date"
 require "bson/date_time"
+require "bson/db_pointer"
+require "bson/decimal128"
+require "bson/big_decimal"
 require "bson/document"
+require "bson/ext_json"
 require "bson/false_class"
 require "bson/float"
 require "bson/hash"
+require "bson/dbref"
+require "bson/open_struct"
 require "bson/max_key"
 require "bson/min_key"
 require "bson/nil_class"
@@ -86,20 +95,21 @@ require "bson/time"
 require "bson/timestamp"
 require "bson/true_class"
 require "bson/undefined"
+require "bson/vector"
 require "bson/version"
 
 # If we are using JRuby, attempt to load the Java extensions, if we are using
-# MRI or Rubinius, attempt to load the C extenstions. If either of these fail,
-# we revert back to a pure Ruby implementation of the Buffer class.
+# MRI or Rubinius, attempt to load the C extensions.
 #
 # @since 2.0.0
 begin
   if BSON::Environment.jruby?
     require "bson-ruby.jar"
-    org.bson.NativeService.new.basicLoad(JRuby.runtime)
+    JRuby::Util.load_ext("org.bson_ruby.NativeService")
   else
-    require "native"
+    require "bson_native"
   end
-rescue LoadError
-  $stderr.puts("BSON is using the pure Ruby implementation.")
+rescue LoadError => e
+  $stderr.puts("Failed to load the necessary extensions: #{e.class}: #{e}")
+  raise
 end

data/spec/README.md

@@ -0,0 +1,14 @@
+# Running BSON Ruby Tests
+
+## Quick Start
+
+The test suite requires shared tooling that is stored in a separate repository
+and is referenced as a submodule. After checking out the desired bson-ruby
+branch, check out the matching submodules:
+
+    git submodule init
+    git submodule update
+
+Then, to run the test suite:
+
+    rake

data/spec/bson/array_spec.rb

@@ -1,4 +1,5 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# 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.
@@ -34,65 +35,6 @@ describe Array do
         [ { "$testing" => "value" } ]
       end
 
-      context "when validating keys" do
-
-        context "when validating globally" do
-
-          before do
-            BSON::Config.validating_keys = true
-          end
-
-          after do
-            BSON::Config.validating_keys = false
-          end
-
-          it "raises an error" do
-            expect {
-              obj.to_bson
-            }.to raise_error(BSON::String::IllegalKey)
-          end
-        end
-
-        context "when validating locally" do
-
-          it "raises an error" do
-            expect {
-              obj.to_bson(BSON::ByteBuffer.new, true)
-            }.to raise_error(BSON::String::IllegalKey)
-          end
-
-          context "when serializing different types" do
-
-            let(:obj) do
-              [ BSON::Binary.new("testing", :generic),
-                BSON::Code.new("this.value = 5"),
-                BSON::CodeWithScope.new("this.value = val", "test"),
-                Date.new(2012, 1, 1),
-                Time.utc(2012, 1, 1),
-                DateTime.new(2012, 1, 1, 0, 0, 0),
-                false,
-                1.2332,
-                Integer::MAX_32BIT - 1,
-                BSON::ObjectId.new,
-                /\W+/i,
-                'a string',
-                :a_symbol,
-                Time.utc(2012, 1, 1, 0, 0, 0),
-                BSON::Timestamp.new(1, 10),
-                true,
-                { "$testing" => "value" }
-              ]
-            end
-
-            it "raises an error" do
-              expect {
-                obj.to_bson(BSON::ByteBuffer.new, true)
-              }.to raise_error(BSON::String::IllegalKey)
-            end
-          end
-        end
-      end
-
       context "when not validating keys" do
 
         let(:bson) do
@@ -127,11 +69,28 @@ describe Array do
           end
 
           it "serializes the hash" do
-            expect(obj.to_bson.length).to eq(251)
+            expect(obj.to_bson.length).to eq(252)
           end
         end
       end
     end
+
+    context 'when array contains value of an unserializable class' do
+      class ArraySpecUnserializableClass
+      end
+
+      let(:obj) do
+        [ArraySpecUnserializableClass.new]
+      end
+
+      it 'raises UnserializableClass' do
+        lambda do
+          obj.to_bson
+        end.should raise_error(BSON::Error::UnserializableClass,
+          # C extension does not provide element position in the exception message.
+          /(Array element at position 0|Value) does not define its BSON serialized type:.*ArraySpecUnserializableClass/)
+      end
+    end
   end
 
   describe "#to_bson_normalized_value" do
@@ -169,8 +128,25 @@ describe Array do
       it "raises an exception" do
         expect {
           [ 1 ].to_bson_object_id
-        }.to raise_error(BSON::ObjectId::Invalid)
+        }.to raise_error(BSON::Error::InvalidObjectId)
       end
     end
   end
+
+  describe '#as_extended_json' do
+
+    let(:object) do
+      ['one', :two, 3, 4.0, nil]
+    end
+
+    let(:expected) do
+      ["one", { "$symbol" => "two" }, { "$numberInt" => "3" }, { "$numberDouble"=> "4.0" }, nil]
+    end
+
+    it 'returns the extended serialization' do
+      expect(object.as_extended_json).to eq(expected)
+    end
+
+    it_behaves_like 'an Extended JSON serializable object'
+  end
 end