MONGOID-5144 Add a deprecation warning when using the legacy query cache (#5042)

* MONGOID-5144 Add a deprecation warning when using the legacy query cache.

* fix the feature/test with old drivers

* Update query_cache_spec.rb

* account for instance variable removal failing better

* Minor improvement in a spec

Co-authored-by: shields <[email protected]>
Co-authored-by: Oleg Pudeyev <[email protected]>
Co-authored-by: Dmitry Rybakov <[email protected]>

Author: 3 people

lib/mongoid/query_cache.rb

@@ -7,8 +7,14 @@ module Mongoid
   #
   # @since 4.0.0
   module QueryCache
-    class << self
+    # @api private
+    LEGACY_WARNING = <<~DOC
+      You are using the legacy Mongoid query cache which has known issues.
+      Please upgrade the `mongo' gem to at least 2.14.0 to use the improved driver query cache.
+      Refer to: https://docs.mongodb.com/mongoid/current/tutorials/mongoid-queries/#the-improved-driver-query-cache
+    DOC
 
+    class << self
       # Get the cached queries.
       #
       # @example Get the cached queries from the current thread.
@@ -86,6 +92,10 @@ def cache(&block)
         if defined?(Mongo::QueryCache)
           Mongo::QueryCache.cache(&block)
         else
+          @legacy_query_cache_warned ||= begin
+            Mongoid.logger.warn(LEGACY_WARNING)
+            true
+          end
           enabled = QueryCache.enabled?
           QueryCache.enabled = true
           begin

spec/mongoid/query_cache_spec.rb

@@ -24,10 +24,27 @@
     SessionRegistry.instance.verify_sessions_ended!
   end
 
+  let(:reset_legacy_qc_warning) do
+    begin
+      Mongoid::QueryCache.remove_instance_variable('@legacy_query_cache_warned')
+    rescue NameError
+      # raised if the instance variable wasn't set
+    end
+  end
+
   describe '#cache' do
     context 'with driver query cache' do
       min_driver_version '2.14'
 
+      it 'does not log a deprecation warning' do
+        reset_legacy_qc_warning
+
+        expect_any_instance_of(Logger).to_not receive(:warn).with(
+          described_class::LEGACY_WARNING
+        )
+        described_class.cache { }
+      end
+
       context 'when query cache is not enabled' do
         before do
           Mongoid::QueryCache.enabled = false
@@ -180,6 +197,13 @@
     context 'with mongoid query cache' do
       max_driver_version '2.13'
 
+      it 'logs a deprecation warning' do
+        reset_legacy_qc_warning
+
+        expect_any_instance_of(Logger).to receive(:warn).with(described_class::LEGACY_WARNING)
+        described_class.cache { }
+      end
+
       context 'when query cache is not enabled' do
         before do
           Mongoid::QueryCache.enabled = false