:fiber level only works reliably on Ruby 3.2+

Author: jamis

lib/config/locales/en.yml

@@ -712,6 +712,16 @@ en:
             the expression %{javascript} is not allowed."
           resolution: "Please provide a standard hash to #where when the criteria
             is for an embedded association."
+        unsupported_isolation_level:
+          message: "The isolation level '%{level}' is not supported."
+          summary: >
+            You requested an isolation level of '%{level}', which is not
+            supported. Only `:thread` and `:fiber` isolation levels are
+            currently supported; note that the `:fiber` level is only
+            supported on Ruby versions 3.2 and higher.
+          resolution: >
+            Use `:thread` as the isolation level. If you are using Ruby 3.2
+            or higher, you may also use `:fiber`.
         validations:
           message: "Validation of %{document} failed."
           summary: "The following errors were found: %{errors}"

lib/mongoid/config.rb

@@ -121,7 +121,19 @@ module Config
     # If set to `:fiber`, Mongoid will use fiber-local storage instead. This
     # may be necessary if you are using libraries like Falcon, which use
     # fibers to manage concurrency.
-    option :isolation_level, default: :thread
+    #
+    # Note that the `:fiber` isolation level is only supported in Ruby 3.2
+    # and later, due to semantic differences in how fiber storage is handled
+    # in earlier Ruby versions.
+    option :isolation_level, default: :thread, on_change: -> (level) do
+      if %i[ thread fiber ].exclude?(level)
+        raise Errors::UnsupportedIsolationLevel.new(level)
+      end
+
+      if level == :fiber && RUBY_VERSION < '3.2'
+        raise Errors::UnsupportedIsolationLevel.new(level)
+      end
+    end
 
     # When this flag is false, a document will become read-only only once the
     # #readonly! method is called, and an error will be raised on attempting

lib/mongoid/config/options.rb

@@ -40,8 +40,17 @@ def option(name, options = {})
           end
 
           define_method("#{name}=") do |value|
+            old_value = settings[name]
             settings[name] = value
-            options[:on_change]&.call(value)
+
+            begin
+              options[:on_change]&.call(value)
+            rescue
+              # If the on_change callback raises an error, we need to roll
+              # the change back.
+              settings[name] = old_value
+              raise
+            end
           end
 
           define_method("#{name}?") do

lib/mongoid/errors.rb

@@ -74,5 +74,6 @@
 require 'mongoid/errors/unregistered_class'
 require "mongoid/errors/unsaved_document"
 require "mongoid/errors/unsupported_javascript"
+require "mongoid/errors/unsupported_isolation_level"
 require "mongoid/errors/validations"
 require "mongoid/errors/delete_restriction"

lib/mongoid/errors/unsupported_isolation_level.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an unsupported isolation level is used in Mongoid
+    # configuration.
+    class UnsupportedIsolationLevel < MongoidError
+      # Create the new error caused by attempting to select an unsupported
+      # isolation level.
+      #
+      # @param [ Symbol ] level The requested isolation level.
+      def initialize(level)
+        super(
+          compose_message(
+            "unsupported_isolation_level",
+            { level: level }
+          )
+        )
+      end
+    end
+  end
+end

spec/integration/isolation_state_spec.rb

@@ -20,6 +20,41 @@ def fiber_operation(value)
     end.resume
   end
 
+  context 'when set to an unsupported value' do
+    it 'raises an error' do
+      old_value = Mongoid::Config.isolation_level
+      expect { Mongoid::Config.isolation_level = :unsupported }
+        .to raise_error(Mongoid::Errors::UnsupportedIsolationLevel)
+      expect(Mongoid::Config.isolation_level).to eq(old_value)
+    end
+  end
+
+  context 'when using older Ruby' do
+    ruby_version_lt '3.2'
+
+    context 'when set to :fiber' do
+      it 'raises an error' do
+        expect { Mongoid::Config.isolation_level = :fiber }
+          .to raise_error(Mongoid::Errors::UnsupportedIsolationLevel)
+      end
+    end
+
+    context 'when set to :thread' do
+      around do |example|
+        save = Mongoid::Config.isolation_level
+        example.run
+      ensure
+        Mongoid::Config.isolation_level = save
+      end
+
+      it 'sets the isolation level' do
+        expect { Mongoid::Config.isolation_level = :thread }
+          .not_to raise_error
+        expect(Mongoid::Config.isolation_level).to eq(:thread)
+      end
+    end
+  end
+
   context 'when set to :thread' do
     config_override :isolation_level, :thread
 
@@ -42,54 +77,58 @@ def fiber_operation(value)
     end
   end
 
-  context 'when set to :fiber' do
-    config_override :isolation_level, :fiber
+  context 'when using Ruby 3.2+' do
+    ruby_version_gte '3.2'
 
-    context 'when operating inside threads' do
-      let(:result) { fiber_operation('a') { thread_operation('b') } }
+    context 'when set to :fiber' do
+      config_override :isolation_level, :fiber
 
-      it 'exposes the fiber state within the thread' do
-        expect(result).to eq(%w[ a b ])
+      context 'when operating inside threads' do
+        let(:result) { fiber_operation('a') { thread_operation('b') } }
+
+        it 'exposes the fiber state within the thread' do
+          expect(result).to eq(%w[ a b ])
+        end
       end
-    end
 
-    context 'when operating in nested fibers' do
-      let(:result) { fiber_operation('a') { fiber_operation('b') } }
+      context 'when operating in nested fibers' do
+        let(:result) { fiber_operation('a') { fiber_operation('b') } }
 
-      it 'propagates fiber state to nested fibers' do
-        expect(result).to eq(%w[ a b ])
+        it 'propagates fiber state to nested fibers' do
+          expect(result).to eq(%w[ a b ])
+        end
       end
-    end
 
-    context 'when operating in adjacent fibers' do
-      let(:result1) { fiber_operation('a') { fiber_operation('b') } }
-      let(:result2) { fiber_operation('c') { fiber_operation('d') } }
+      context 'when operating in adjacent fibers' do
+        let(:result1) { fiber_operation('a') { fiber_operation('b') } }
+        let(:result2) { fiber_operation('c') { fiber_operation('d') } }
 
-      it 'maintains isolation between adjacent fibers' do
-        expect(result1).to eq(%w[ a b ])
-        expect(result2).to eq(%w[ c d ])
+        it 'maintains isolation between adjacent fibers' do
+          expect(result1).to eq(%w[ a b ])
+          expect(result2).to eq(%w[ c d ])
+        end
       end
-    end
 
-    describe '#reset!' do
-      context 'when operating in nested fibers' do
-        let (:result) do
-          fiber_operation('a') do
-            Mongoid::Threaded.reset!
-
-            # once reset, subsequent nested fibers will each have their own
-            # state; they won't touch the reset state here.
-            fiber_operation('b')
-            fiber_operation('c')
-
-            # If we then add to the stack here, it will be unaffected by
-            # the previous fiber operations.
-            Mongoid::Threaded.stack(:testing) << 'd'
+      describe '#reset!' do
+        context 'when operating in nested fibers' do
+          let (:result) do
+            fiber_operation('a') do
+              Mongoid::Threaded.reset!
+
+              # once reset, subsequent nested fibers will each have their own
+              # state; they won't touch the reset state here.
+              fiber_operation('b')
+              fiber_operation('c')
+
+              # If we then add to the stack here, it will be unaffected by
+              # the previous fiber operations.
+              Mongoid::Threaded.stack(:testing) << 'd'
+            end
           end
-        end
 
-        it 'clears the fiber state' do
-          expect(result).to eq(%w[ d ])
+          it 'clears the fiber state' do
+            expect(result).to eq(%w[ d ])
+          end
         end
       end
     end