MONGOID-5234 Add Feature Flag: Remove BSON::ObjectId#as_json override (#5141)

* Revert "MONGOID-???? - Remove BSON::ObjectId#as_json as we will defer to the bson-ruby gem implementation. (#5057)"

This reverts commit e8aae88.

* MONGOID-5234 add feature flag for as_json

* MONGOID-5234 add docs for new feature flag

* MONGOID-5234 remove irrelevant tests and add docstring

* MONGOID-5234 add default to configuration docs

* MONGOID-5234 use dots instead of ::

* MONGOID-5234 put test back

* MONGOID-5234 update documentation and flip the flag

* MONGOID-5234 fix up as_json comment

* MONGOID-5234 update release notes

* MONGOID-5234 change method signature

Author: neilshweky

docs/reference/configuration.txt

@@ -372,6 +372,14 @@ for details on driver options.
       # further information. (default: true)
       use_activesupport_time_zone: true
 
+      # In Mongoid 7.3.3 and earlier, the BSON::ObjectId#as_json method would
+      # default to returning { "$oid" => id.to_s }. Turning on this flag will
+      # defer the as_json call to bson-ruby's implementation of
+      # BSON::ObjectId#as_json. In bson-ruby 5.x.x as_json will return
+      # the id as a string. In bson-ruby 4.x.x as_json will return
+      # { "$oid" => id.to_s }. (default: false)
+      use_bson_ruby_as_json: false
+
       # Return stored times as UTC. See the time zone section below for
       # further information. Most applications should not use this option.
       # (default: false)

docs/release-notes/mongoid-7.4.txt

@@ -118,6 +118,10 @@ Mongoid 7.4 and later will inherit the new implementation provided by
 ``bson-ruby`` while Mongoid 7.3 and earlier will continue with the
 implementation returning a hash of ``{"$oid" => "..."}``.
 
+..  note::
+
+  In order to get this functionality, the ``Mongoid.use_bson_ruby_as_json``
+  feature flag must be turned on.
 
 Scoped Associations
 -------------------

lib/mongoid/config.rb

@@ -103,6 +103,10 @@ module Config
     # function.
     option :compare_time_by_ms, default: false
 
+    # Use bson-ruby's implementation of as_json for BSON::ObjectId instead of
+    # the one monkey-patched into Mongoid.
+    option :use_bson_ruby_as_json, default: false
+
     # Has Mongoid been configured? This is checking that at least a valid
     # client config exists.
     #

lib/mongoid/extensions.rb

@@ -1,5 +1,24 @@
 # frozen_string_literal: true
 
+class BSON::ObjectId
+  alias :bson_ruby_as_json :as_json
+
+  # Return a string representation of the object id for use in
+  # application-level JSON serialization.
+  #
+  # @example Get the object id as a JSON-serializable object.
+  #   object_id.as_json
+  #
+  # @return [ String ] The object id as a string.
+  def as_json(*args)
+    if Mongoid::use_bson_ruby_as_json
+      bson_ruby_as_json(*args)
+    else
+      { "$oid" => to_s }
+    end
+  end
+end
+
 class BSON::Document
   # We need to override this as ActiveSupport creates a new Object, instead of a new Hash
   # see https://github.com/rails/rails/commit/f1bad130d0c9bd77c94e43b696adca56c46a66aa

spec/mongoid/config_spec.rb

@@ -321,6 +321,13 @@
     it_behaves_like "a config option"
   end
 
+  context 'when setting the use_bson_ruby_as_json option in the config' do
+    let(:option) { :use_bson_ruby_as_json }
+    let(:default) { false }
+
+    it_behaves_like "a config option"
+  end
+
   describe "#load!" do
 
     before(:all) do

spec/mongoid/extensions_spec.rb

@@ -2,6 +2,48 @@
 
 require "spec_helper"
 
+describe BSON::ObjectId do
+
+  describe "#as_json" do
+
+    let(:object_id) do
+      described_class.new
+    end
+
+    context "when use_bson_ruby_as_json is set" do
+      around do |example|
+        saved_flag = Mongoid.use_bson_ruby_as_json
+        Mongoid.use_bson_ruby_as_json = true
+        begin
+          example.run
+        ensure
+          Mongoid.use_bson_ruby_as_json = saved_flag
+        end
+      end
+
+      it "uses bson-ruby's implementation of as_json" do
+        expect(object_id.as_json).to eq(object_id.bson_ruby_as_json)
+      end
+    end
+
+    context "when use_bson_ruby_as_json is not set" do
+      around do |example|
+        saved_flag = Mongoid.use_bson_ruby_as_json
+        Mongoid.use_bson_ruby_as_json = false
+        begin
+          example.run
+        ensure
+          Mongoid.use_bson_ruby_as_json = saved_flag
+        end
+      end
+
+      it "returns the $oid plus string" do
+        expect(object_id.as_json).to eq("$oid" => object_id.to_s)
+      end
+    end
+  end
+end
+
 describe BSON::Document do
 
   describe "#symbolize_keys" do