bson 5.0.2 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41a002d14b035c9cf01534ee489ca61c012202aac1e2729fa850960c359ba5cd
-  data.tar.gz: f63478ad673c6dfbed91eaed8477b45287a264fa6c06e29d2273c41a0951e4e1
+  metadata.gz: db8071ad65b8a0ef6e4c10b76f1143ce627b5d2ba0e3c9f7eed13d3868425c3e
+  data.tar.gz: 3d76edf4c97a81d2362e1b08c4cee08074561f16b74f468b7cb1aac70fb614c4
 SHA512:
-  metadata.gz: 67721ba06f0154a5dc37bc460602f878843243706e0194375c0350a095774beb06ba7a5b861b137d95bd0e753ed74b35d3b541283864aaec02b61dd94952d9ed
-  data.tar.gz: 525cc2a1da23ceaec40243cf7cc9ab504e81c11b56bf22e9f51f156c24294231fcd300874ae3b22c80fa473be568d84d43c627eabd4434c3895458c332364f6a
+  metadata.gz: dde49d3d741174610fa32ba697c238285209f0074ba04a1d6758604665c1c817a9d96bc1c44c7a731530ebdc94a8ac9e74da3c4ea340a6d6d6d4a0bf4d6ab17e
+  data.tar.gz: f29560d3d3830b34d33567671328dca0dc9b7b5ba173d6a193ed2b3150ae79a17f715666bc106a3c6fda0399ab4e7724bb3efc9a97733076464cd10698a366b3

data/Rakefile

@@ -25,6 +25,8 @@ require "rake/extensiontask"
 require "rspec/core/rake_task"
 require 'fileutils'
 
+load 'spec/shared/lib/tasks/candidate.rake'
+
 def jruby?
   defined?(JRUBY_VERSION)
 end

data/ext/bson/extconf.rb

@@ -3,6 +3,6 @@
 
 require 'mkmf'
 
-$CFLAGS << ' -Wall -g -std=c99'
+append_cflags(["-Wall", "-g", "-std=c99"])
 
 create_makefile('bson_native')

data/lib/bson/binary.rb

@@ -1,5 +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");
@@ -50,6 +50,7 @@ module BSON
       ciphertext: 6.chr,
       column: 7.chr,
       sensitive: 8.chr,
+      vector: 9.chr,
       user: 128.chr,
     }.freeze
 
@@ -61,6 +62,16 @@ module BSON
     # @since 2.0.0
     TYPES = SUBTYPES.invert.freeze
 
+    # Types of vector data.
+    VECTOR_DATA_TYPES = {
+      int8: '0x03'.hex,
+      float32: '0x27'.hex,
+      packed_bit: '0x10'.hex
+    }.freeze
+
+    # @api private
+    VECTOR_DATA_TYPES_INVERSE = VECTOR_DATA_TYPES.invert.freeze
+
     # @return [ String ] The raw binary data.
     #
     # The string is always stored in BINARY encoding.
@@ -89,6 +100,7 @@ module BSON
 
       type == other.type && data == other.data
     end
+
     alias eql? ==
 
     # Compare this binary object to another object. The two objects must have
@@ -113,7 +125,7 @@ module BSON
     #
     # @since 2.3.1
     def hash
-      [ data, type ].hash
+      [data, type].hash
     end
 
     # Return a representation of the object for use in
@@ -146,6 +158,26 @@ module BSON
       end
     end
 
+    # Decode the binary data as a vector data type.
+    #
+    # @return [ BSON::Vector ] The decoded vector data.
+    def as_vector
+      raise BSON::Error, "Cannot decode subtype #{type} as vector" unless type == :vector
+
+      dtype_value, padding, = data[0..1].unpack('CC')
+      dtype = VECTOR_DATA_TYPES_INVERSE[dtype_value]
+      raise ArgumentError, "Unsupported vector type: #{dtype_value}" unless dtype
+
+      format = case dtype
+               when :int8 then 'c*'
+               when :float32 then 'f*'
+               when :packed_bit then 'C*'
+               else
+                 raise ArgumentError, "Unsupported type: #{dtype}"
+               end
+      BSON::Vector.new(data[2..-1].unpack(format), dtype, padding)
+    end
+
     # Instantiate the new binary object.
     #
     # This method accepts a string in any encoding; however, if a string is
@@ -368,8 +400,97 @@ module BSON
       new(uuid_binary, :uuid_old)
     end
 
+    # Constructs a new binary object from a binary vector.
+
+    # @param [ BSON::Vector | Array ] vector The vector data.
+    # @param [ Symbol | nil ] dtype The vector data type, must be nil if vector is a BSON::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. Must be 0 if vector is a BSON::Vector.
+    # @param [ Boolean ] validate_vector_data Whether to validate the vector data.
+    #
+    # @return [ BSON::Binary ] The binary object.
+    def self.from_vector(vector, dtype = nil, padding = 0, validate_vector_data: false)
+      data, dtype, padding = extract_args_for_vector(vector, dtype, padding)
+      validate_args_for_vector!(data, dtype, padding)
+
+      format = case dtype
+               when :int8 then 'c*'
+               when :float32 then 'f*'
+               when :packed_bit then 'C*'
+               else raise ArgumentError, "Unsupported type: #{dtype}"
+               end
+      if validate_vector_data
+        validate_vector_data!(data, dtype)
+      end
+      metadata = [ VECTOR_DATA_TYPES[dtype], padding ].pack('CC')
+      data = data.pack(format)
+      new(metadata.concat(data), :vector)
+    end
+
     private
 
+    # Extracts the arguments for a binary vector.
+    #
+    # @param [ BSON::Vector | Array ] vector The vector data.
+    # @param [ ::Symbol | nil ] dtype The vector data type, must be nil if vector is a BSON::Vector.
+    # @param [ Integer ] padding The padding. Must be 0 if vector is a BSON::Vector.
+    #
+    # @return [ Array ] The extracted data, dtype, and padding.
+    def self.extract_args_for_vector(vector, dtype, padding)
+      if vector.is_a?(BSON::Vector)
+        if dtype || padding != 0
+          raise ArgumentError, 'Do not specify dtype and padding if the first argument is BSON::Vector'
+        end
+
+        data = vector.data
+        dtype = vector.dtype
+        padding = vector.padding
+      else
+        data = vector
+      end
+      [ data, dtype, padding ]
+    end
+    private_class_method :extract_args_for_vector
+
+    # Validate the arguments for a binary vector.
+    # @param [ Array ] data The vector data.
+    # @param [ ::Symbol ] dtype The vector data type.
+    # @param [ Integer ] padding The padding. Must be 0 if vector is a BSON::Vector.
+    # @raise [ ArgumentError ] If the arguments are invalid.
+    def self.validate_args_for_vector!(data, dtype, padding)
+      raise ArgumentError, "Unknown dtype #{dtype}" unless VECTOR_DATA_TYPES.key?(dtype)
+
+      if %i[int8 float32].include?(dtype)
+        raise ArgumentError, 'Padding applies only to packed_bit' if padding != 0
+      elsif padding.positive? && data.empty?
+        raise ArgumentError, 'Padding must be zero when the vector is empty for PACKED_BIT'
+      elsif padding.negative? || padding > 7
+        raise ArgumentError, "Padding must be between 0 and 7, got #{padding}"
+      end
+    end
+    private_class_method :validate_args_for_vector!
+
+    # Validate that all the values in the vector data are valid for the given dtype.
+    #
+    # @param [ Array ] data The vector data.
+    # @param [ ::Symbol ] dtype The vector data type.
+    def self.validate_vector_data!(data, dtype)
+      validator = case dtype
+                  when :int8
+                    ->(v) { v.is_a?(Integer) && v.between?(-128, 127) }
+                  when :float32
+                    ->(v) { v.is_a?(Float) }
+                  when :packed_bit
+                    ->(v) { v.is_a?(Integer) && v.between?(0, 255) }
+                  else
+                    raise ArgumentError, "Unsupported type: #{dtype}"
+                  end
+      data.each do |v|
+        raise ArgumentError, "Invalid value #{v} for type #{dtype}" unless validator.call(v)
+      end
+    end
+    private_class_method :validate_vector_data!
+
     # initializes an instance of BSON::Binary.
     #
     # @param [ String ] data the data to initialize the object with
@@ -398,7 +519,7 @@ module BSON
       if representation != :standard
         raise ArgumentError,
               'Binary of type :uuid can only be stringified to :standard representation, ' \
-              "requested: #{representation.inspect}"
+                "requested: #{representation.inspect}"
       end
 
       data
@@ -490,7 +611,8 @@ module BSON
           validate_integer_type!(type.bytes.first)
         end
       when Symbol then validate_symbol_type!(type)
-      else raise BSON::Error::InvalidBinaryType, type
+      else
+        raise BSON::Error::InvalidBinaryType, type
       end
     end
 

data/lib/bson/document.rb

@@ -321,6 +321,14 @@ module BSON
       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
 
+    def deep_symbolize_keys!
+      warn <<~WARN
+        [DEPRECATION] `deep_symbolize_keys!` is not supported on BSON::Document instances.
+        Please convert the document to a Hash first (using `#to_h`), then call `#deep_symbolize_keys!` on the Hash.
+        This will raise an error starting with the v6.0.0 release.
+      WARN
+    end
+
     # Override the Hash implementation of to_bson_normalized_value.
     #
     # BSON::Document is already of the correct type and already provides

data/lib/bson/object_id.rb

@@ -360,7 +360,7 @@ module BSON
       # NUM2UINT. Further, the spec dictates that the time component of an
       # ObjectID must be no more than 4 bytes long, so the spec itself is
       # constrained in this regard.
-      MAX_INTEGER = 2 ** 32
+      MAX_INTEGER = 2**32
 
       # Returns an integer timestamp (seconds since the Epoch). Primarily used
       # by the generator to produce object ids.

data/lib/bson/regexp.rb

@@ -99,16 +99,16 @@ module BSON
     end
 
     def bson_extended
-      (options & ::Regexp::EXTENDED).zero? ? NO_VALUE : EXTENDED_VALUE
+      options.nobits?(::Regexp::EXTENDED) ? NO_VALUE : EXTENDED_VALUE
     end
 
     def bson_ignorecase
-      (options & ::Regexp::IGNORECASE).zero? ? NO_VALUE : IGNORECASE_VALUE
+      options.nobits?(::Regexp::IGNORECASE) ? NO_VALUE : IGNORECASE_VALUE
     end
 
     def bson_dotall
       # Ruby Regexp's MULTILINE is equivalent to BSON's dotall value
-      (options & ::Regexp::MULTILINE).zero? ? NO_VALUE : NEWLINE_VALUE
+      options.nobits?(::Regexp::MULTILINE) ? NO_VALUE : NEWLINE_VALUE
     end
 
     # Represents the raw values for the regular expression.

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,20 +1,9 @@
 # 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.
-# 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
-  VERSION = "5.0.2"
+  # 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.1.0'
 end

data/lib/bson.rb

@@ -95,6 +95,7 @@ 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

data/spec/bson/document_as_spec.rb

@@ -44,4 +44,18 @@ describe BSON::Document do
       end
     end
   end
+
+  describe '#deep_symbolize_keys!' do
+    context 'string keys' do
+      let(:doc) do
+        described_class.new('foo' => 'bar')
+      end
+
+      it 'raises ArgumentError' do
+        expect do
+          doc.deep_symbolize_keys!
+        end.to output(/\[DEPRECATION\] `deep_symbolize_keys!` is not supported on BSON::Document instances./).to_stderr
+      end
+    end
+  end
 end

data/spec/bson/vector_spec.rb

@@ -0,0 +1,33 @@
+# 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.
+
+require 'spec_helper'
+
+describe BSON::Vector do
+  it 'behaves like an Array' do
+    expect(described_class.new([ 1, 2, 3 ], :int8)).to be_a(Array)
+  end
+
+  describe '#initialize' do
+    context 'when padding is not provided' do
+      let(:vector) { described_class.new([ 1, 2, 3 ], :int8) }
+
+      it 'sets the padding to 0' do
+        expect(vector.padding).to eq(0)
+      end
+    end
+  end
+end

data/spec/runners/binary_vector.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'runners/common_driver'
+
+module BSON
+  module BinaryVector
+    class Spec < CommonDriver::Spec
+      def initialize(file)
+        super
+        @valid = @invalid = nil
+      end
+
+      def tests
+        @spec['tests'].collect do |test|
+          BSON::BinaryVector::Test.new(self, test)
+        end
+      end
+
+      def valid_tests
+        tests.select(&:valid?)
+      end
+
+      def invalid_tests
+        tests.reject(&:valid?)
+      end
+    end
+
+    class Test
+      attr_reader :canonical_bson, :description, :dtype, :padding, :vector
+
+      def initialize(spec, test)
+        @spec = spec
+        @description = test['description']
+        @valid = test['valid']
+        @vector = ExtJSON.parse_obj(test['vector'])
+        @dtype_hex = test['dtype_hex']
+        @dtype_alias = test['dtype_alias']
+        @dtype = @dtype_alias.downcase.to_sym
+        @padding = test['padding']
+        @canonical_bson = test['canonical_bson']
+      end
+
+      def valid?
+        @valid
+      end
+
+      def document_from_canonical_bson
+        bson_bytes = decode_hex(@canonical_bson)
+        buffer = BSON::ByteBuffer.new(bson_bytes)
+        BSON::Document.from_bson(buffer)
+      end
+
+      def canonical_bson_from_document(use_vector_type: false, validate_vector_data: false)
+        args = if use_vector_type
+                 [ BSON::Vector.new(@vector, @dtype, @padding) ]
+               else
+                 [ @vector, @dtype, @padding ]
+               end
+        {
+          @spec.test_key => BSON::Binary.from_vector(
+            *args,
+            validate_vector_data: validate_vector_data
+          ),
+        }.to_bson.to_s
+      end
+
+      def bson
+        decode_hex(@canonical_bson)
+      end
+
+      private
+
+      def decode_hex(obj)
+        [ obj ].pack('H*')
+      end
+    end
+  end
+end

data/spec/shared/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2020 MongoDB, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/spec/shared/bin/get-mongodb-download-url

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+desired_version, arch = ARGV
+if arch.nil?
+  STDERR.puts "Usage: get-mongodb-download-url desired-version arch"
+  exit 1
+end
+
+$: << File.join(File.dirname(__FILE__), '../lib')
+require 'mrss/server_version_registry'
+
+begin
+  puts Mrss::ServerVersionRegistry.new(desired_version, arch).download_url
+rescue Mrss::ServerVersionRegistry::Error => exc
+  STDERR.puts "Error: #{exc}"
+  exit 2
+end

data/spec/shared/bin/s3-copy

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'aws-sdk-s3'
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: s3-copy options"
+
+  opts.on("-r", "--region=REGION", "AWS region to use (default us-east-1)") do |v|
+    options[:region] = v
+  end
+
+  opts.on("-p", "--param=KEY=VALUE", "Specify parameter for new files") do |v|
+    options[:params] ||= {}
+    k, v = v.split('=', 2)
+    options[:params][k.to_sym] = v
+  end
+
+  opts.on("-f", "--from=BUCKET:PATH", "Bucket name and key (or path) to copy from") do |v|
+    options[:from] = v
+  end
+
+  opts.on("-t", "--to=BUCKET:PATH", "Bucket name and key (or path) to write to (may be specified more than once)") do |v|
+    options[:to] ||= []
+    options[:to] << v
+  end
+end.parse!
+
+ENV['AWS_REGION'] ||= options[:region] || 'us-east-1'
+
+bucket, key = options.fetch(:from).split(':', 2)
+
+s3 = Aws::S3::Client.new
+
+options.fetch(:to).each do |dest|
+  STDERR.puts "Copying to #{dest}"
+  dbucket, dkey = dest.split(':', 2)
+  s3.copy_object(
+    bucket: dbucket,
+    key: dkey,
+    copy_source: "/#{bucket}/#{key}",
+    **options[:params] || {},
+  )
+end

data/spec/shared/bin/s3-upload

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'aws-sdk-s3'
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: s3-upload options"
+
+  opts.on("-r", "--region=REGION", "AWS region to use (default us-east-1)") do |v|
+    options[:region] = v
+  end
+
+  opts.on("-p", "--param=KEY=VALUE", "Specify parameter for S3 upload") do |v|
+    options[:params] ||= {}
+    k, v = v.split('=', 2)
+    options[:params][k.to_sym] = v
+  end
+
+  opts.on("-f", "--file=PATH", "Path to the file to upload, - to upload standard input") do |v|
+    options[:file] = v
+  end
+
+  opts.on("-w", "--write=BUCKET:PATH", "Bucket name and key (or path) to upload to") do |v|
+    options[:write] = v
+  end
+
+  opts.on("-c", "--copy=BUCKET:PATH", "Bucket name and key (or path) to copy to (may be specified more than once)") do |v|
+    options[:copy] ||= []
+    options[:copy] << v
+  end
+end.parse!
+
+ENV['AWS_REGION'] ||= options[:region] || 'us-east-1'
+
+def upload(f, options)
+  s3 = Aws::S3::Client.new
+  write = options.fetch(:write)
+  STDERR.puts "Writing #{write}"
+  bucket, key = write.split(':', 2)
+  s3.put_object(
+    body: f.read,
+    bucket: bucket,
+    key: key,
+    **options[:params] || {},
+  )
+  if copy = options[:copy]
+    copy.each do |dest|
+      STDERR.puts "Copying to #{dest}"
+      dbucket, dkey = dest.split(':', 2)
+      s3.copy_object(
+        bucket: dbucket,
+        key: dkey,
+        copy_source: "/#{bucket}/#{key}",
+        **options[:params] || {},
+      )
+    end
+  end
+end
+
+if options[:file] == '-'
+  upload(STDIN, options)
+elsif options[:file]
+  File.open(options[:file]) do |f|
+    upload(f, options)
+  end
+else
+  upload(STDIN, options)
+end