ractor-rails-shim 0.2.0

data/lib/ractor_rails_shim/patches/zeitwerk_registry.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Patch Zeitwerk::Registry to route its class ivars (@loaders, @mutex,
+# @gem_loaders_by_root_file, @autoloads, @explicit_namespaces, @inceptions)
+# through IsolatedExecutionState. Zeitwerk uses raw class ivars (not
+# mattr_accessor), so the shim's macro rewrite doesn't catch them. Each
+# Ractor that boots a Rails app gets its own registry state (its own
+# loaders list, its own mutex, its own autoloads map), which is correct
+# for per-Ractor boot: each worker's autoloaders are independent.
+#
+# The defaults are the same classes Zeitwerk instantiates at module-load
+# time (Loaders, Hash, Autoloads, ExplicitNamespaces, Inceptions, Mutex).
+# Workers lazily build their own on first read.
+
+module RactorRailsShim
+  class << self
+    def install_zeitwerk_registry
+      return if @zeitwerk_patched
+      @zeitwerk_patched = true
+      _register_patch :zeitwerk_registry, "8.1"
+      if defined?(::Zeitwerk::Registry)
+        patch_zeitwerk_registry!
+      else
+        # Defer until Zeitwerk loads. A TracePoint(:class) fires when
+        # `module Registry` opens. One-shot.
+        @zw_tp = TracePoint.new(:class) do |trace|
+          if defined?(::Zeitwerk::Registry) && !@zeitwerk_registry_patched
+            @zw_tp.disable
+            patch_zeitwerk_registry!
+          end
+        end
+        @zw_tp.enable
+      end
+    end
+
+    def patch_zeitwerk_registry!
+      return if @zeitwerk_registry_patched
+      @zeitwerk_registry_patched = true
+
+      reg = ::Zeitwerk::Registry
+      # The ivars Zeitwerk sets at the bottom of registry.rb. Map each to an
+      # IES key and a default-builder string (eval'd in the reader when the
+      # Ractor's slot is empty). Builders reference Zeitwerk constants by
+      # full path so they're resolvable from any Ractor.
+      ivars = {
+        loaders:                  [:ractor_rails_shim_zw_loaders,    "Zeitwerk::Registry::Loaders.new"],
+        gem_loaders_by_root_file: [:ractor_rails_shim_zw_gem,        "{}"],
+        autoloads:                [:ractor_rails_shim_zw_autoloads,  "Zeitwerk::Registry::Autoloads.new"],
+        explicit_namespaces:      [:ractor_rails_shim_zw_explicit,   "Zeitwerk::Registry::ExplicitNamespaces.new"],
+        inceptions:               [:ractor_rails_shim_zw_inceptions, "Zeitwerk::Registry::Inceptions.new"],
+        mutex:                    [:ractor_rails_shim_zw_mutex,      "Mutex.new"],
+      }
+
+      # Redefine each reader (and the mutex, which is read directly as @mutex)
+      # to route through IES with lazy per-Ractor init. Use a PREPENDED module
+      # (not direct module_eval on the singleton class) because Zeitwerk's
+      # `attr_reader :loaders` etc. run LATER in the module body and would
+      # clobber a direct redefinition — same load-order issue as the Rails
+      # module accessors. A prepended module stays in front of the lookup chain.
+      #
+      # In the MAIN ractor, fall back to the existing ivar (set by Zeitwerk at
+      # the bottom of registry.rb) so main-ractor state is preserved. Worker
+      # ractors lazily build their own via the builder string.
+      reader_patch = Module.new
+      ivars.each do |ivar, (key, builder)|
+        key_str = key.inspect
+        ivar_sym = :"@#{ivar}"
+        ivar_str = ivar_sym.inspect
+        reader_patch.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{ivar}
+            v = ActiveSupport::IsolatedExecutionState[#{key_str}]
+            return v unless v.nil?
+            if Ractor.main?
+              existing = instance_variable_get(#{ivar_str}) if instance_variable_defined?(#{ivar_str})
+              if existing
+                ActiveSupport::IsolatedExecutionState[#{key_str}] = existing
+                return existing
+              end
+            end
+            v = #{builder}
+            ActiveSupport::IsolatedExecutionState[#{key_str}] = v
+            v
+          end
+        RUBY
+      end
+      reg.singleton_class.prepend(reader_patch)
+
+      # `conflicting_root_dir?` and `loader_for_gem` read @mutex / @gem_loaders
+      # directly via instance_variable_get-ish access (they use @mutex in the
+      # method body). Since we redefined the readers, the direct @mutex refs
+      # in those methods still hit the ivar. We need to rewrite those two
+      # methods to call the reader instead. Easiest: prepend a module that
+      # calls self.mutex / self.gem_loaders_by_root_file.
+      reg.singleton_class.prepend(Module.new {
+        def conflicting_root_dir?(loader, new_root_dir)
+          mutex.synchronize do
+            loaders.each do |existing_loader|
+              next if existing_loader == loader
+              existing_loader.__roots.each_key do |existing_root_dir|
+                next if !new_root_dir.start_with?(existing_root_dir) && !existing_root_dir.start_with?(new_root_dir)
+                new_root_dir_slash = new_root_dir + '/'
+                existing_root_dir_slash = existing_root_dir + '/'
+                next if !new_root_dir_slash.start_with?(existing_root_dir_slash) && !existing_root_dir_slash.start_with?(new_root_dir_slash)
+                next if loader.__ignores?(existing_root_dir)
+                break if existing_loader.__ignores?(new_root_dir)
+                return existing_loader
+              end
+            end
+            nil
+          end
+        end
+
+        def loader_for_gem(root_file, namespace:, warn_on_extra_files:)
+          h = gem_loaders_by_root_file
+          h[root_file] ||= Zeitwerk::GemLoader.__new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
+        end
+
+        def unregister_loader(loader)
+          gem_loaders_by_root_file.delete_if { |_, l| l == loader }
+        end
+      })
+    end
+  end
+end

data/lib/ractor_rails_shim/patches.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# The core shim: reroute Rails' class-level instance variable accessors
+# through Ractor-safe storage.
+#
+# Background: Rails stores global state in class ivars:
+#
+#   class Rails
+#     class << self
+#       attr_accessor :app_class, :cache, :logger
+#       def application; @application ||= ...; end
+#     end
+#   end
+#
+# From a non-main Ractor these reads/writes raise Ractor::IsolationError:
+#   "can not get unshareable values from instance variables of classes/modules
+#    from non-main Ractors"
+#
+# The fix: store the values in ActiveSupport::IsolatedExecutionState, which
+# is already Ractor-safe. It's thread-local storage (Thread.current[:key]),
+# and each Ractor has its own threads, so each Ractor gets its own slot.
+# Verified on Ruby 4.0.5: a non-main Ractor reads nil for a key the main
+# Ractor set, sets its own value without error, and main's value is intact.
+#
+# IMPORTANT: all method redefinitions use module_eval with STRING, not
+# define_method with a block. A block captures the defining Ractor's
+# binding, and calling it from another Ractor raises:
+#   "defined with an un-shareable Proc in a different Ractor"
+# String eval produces methods with no captured binding, callable from any
+# Ractor. Verified on Ruby 4.0.5.
+
+begin
+  require "active_support/isolated_execution_state"
+rescue LoadError
+  # ActiveSupport not installed — the fallback below provides the same API.
+end
+require_relative "fallback_ies"
+require_relative "version_check"
+
+# Per-concern patch files. Each reopens RactorRailsShim's singleton class
+# to add its `_install_*` method(s). The order matters only for constants
+# (core.rb defines the module skeleton + constants that others reference).
+require_relative "patches/core"
+require_relative "patches/make_shareable"
+require_relative "patches/rails_module"
+require_relative "patches/mattr_accessor"
+require_relative "patches/class_attribute"
+require_relative "patches/zeitwerk_registry"
+require_relative "patches/route_helpers"
+require_relative "patches/url_helpers"
+require_relative "patches/execution_wrapper"
+require_relative "patches/rack"
+require_relative "patches/action_view"
+require_relative "patches/action_controller"
+require_relative "patches/action_dispatch"
+require_relative "patches/polymorphic_routes"
+require_relative "patches/active_support"
+require_relative "patches/warden"
+require_relative "patches/active_model_attribute"
+require_relative "patches/active_record_model_schema"
+require_relative "patches/activerecord"
+require_relative "patches/kaminari"
+require_relative "patches/propshaft"
+require_relative "patches/devise"
+require_relative "patches/orm_adapter"
+require_relative "patches/openssl"
+require_relative "patches/rubygems"

data/lib/ractor_rails_shim/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RactorRailsShim
+  VERSION = "0.2.0"
+end

data/lib/ractor_rails_shim/version_check.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Version detection and gating for ractor-rails-shim.
+#
+# The shim's patches target specific Rails class layouts (class_attribute,
+# Callbacks, PathRegistry, LookupContext, …) and Ruby Ractor semantics that
+# change between releases. Applying an 8.1-targeted patch to a 7.1 app would
+# silently miss blockers or redefine the wrong methods. This module makes the
+# version checks robust (Gem::Version, not string prefix comparison) and gives
+# each patch a tested-versions tag so the dispatcher can apply only patches
+# that match the runtime.
+#
+# Three concerns live here:
+#
+#  1. Reading the runtime versions (Ruby + Rails) defensively — Rails may not
+#     be loaded yet at install time.
+#  2. A policy switch for mismatches: :warn (default, backward compatible),
+#     :strict (raise), or :off (silent). Set via
+#     `RactorRailsShim.version_policy = :strict`.
+#  3. A registry (`PATCH_VERSIONS`) mapping each install_* patch name to the
+#     Rails versions it was developed and tested against, plus reporters
+#     (`applicable_patches` / `skipped_patches`) so users (and CI) can see
+#     exactly what applied to their runtime.
+module RactorRailsShim
+  module Version
+    # Ruby version the shim was developed against (major.minor). Ractor
+    # semantics are still settling; non-4.0 Rubies may behave differently.
+    SUPPORTED_RUBY = "4.0"
+    # Rails versions each patch was tested against. Patches are registered
+    # with one or more entries from this list; the dispatcher applies a patch
+    # only if the runtime Rails version matches one of its tags. To add 7.x
+    # support, write the version-specific patch variants and add the tag here.
+    TESTED_RAILS = ["8.1"].freeze
+
+    class << self
+      # Runtime Ruby version as a Gem::Version (e.g. "4.0.5"). Always
+      # available — Ruby is obviously loaded.
+      def ruby
+        Gem::Version.new(RUBY_VERSION)
+      end
+
+      # Runtime Rails version as a Gem::Version, or nil if Rails isn't
+      # loaded yet (the normal config/boot.rb case — install is called before
+      # `require "rails"`).
+      def rails
+        return nil unless defined?(::Rails) && defined?(::Rails::VERSION)
+        return nil if ::Rails::VERSION::STRING.nil? || ::Rails::VERSION::STRING.empty?
+        begin
+          Gem::Version.new(::Rails::VERSION::STRING)
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      # Major.minor segment as a String ("8.1"), or nil if Rails isn't loaded.
+      def rails_segment
+        return nil unless (rv = rails)
+        "#{rv.segments[0]}.#{rv.segments[1]}"
+      end
+
+      # Major.minor segment of the running Ruby.
+      def ruby_segment
+        v = ruby
+        "#{v.segments[0]}.#{v.segments[1]}"
+      end
+
+      # True if the runtime Ruby's major.minor matches the supported segment.
+      def supported_ruby?
+        ruby_segment == SUPPORTED_RUBY
+      end
+
+      # True if the runtime Rails major.minor is in the tested set (or Rails
+      # isn't loaded yet — can't decide, so optimistic).
+      def supported_rails?
+        return true unless rails # Rails not loaded: defer decision.
+        TESTED_RAILS.include?(rails_segment)
+      end
+
+      # Compare a runtime segment ("8.1") against a Gem::Requirement string
+      # (e.g. ">= 7.0", "~> 8.1"). Returns true if the segment satisfies the
+      # requirement. Used by the patch registry to decide applicability.
+      def satisfies?(segment, requirement)
+        return false if segment.nil?
+        Gem::Requirement.new(requirement).satisfied_by?(Gem::Version.new(segment))
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "ractor_rails_shim/version"
+require_relative "ractor_rails_shim/patches"
+require_relative "ractor_rails_shim/check"
+
+# A monkey-patch shim that reroutes Rails' class-level instance variable
+# accessors (Rails.application, Rails.cache, Rails.logger, mattr_accessor,
+# etc.) through ActiveSupport::IsolatedExecutionState, which is
+# Ractor-safe (thread-local; each Ractor has its own threads).
+#
+# This lets a Rails app run in Ractor mode without forking Rails itself.
+# Each Ractor gets its own copy of the globals (same shape as forking one
+# process per core, but without heap duplication). For shareable state
+# (frozen config, route tables) use Ractor.make_shareable + a constant
+# instead — that shares one copy by reference, zero copy.
+#
+# Stopgap: the goal is for Rails to do this upstream. When it does, this
+# shim becomes a no-op and can be removed from your Gemfile.
+module RactorRailsShim
+  class << self
+    # Require this gem and the patches auto-install IF Rails is loaded.
+    # If Rails isn't loaded yet, install is deferred to the first call
+    # of `install` (call it from config/boot.rb before Rails.application).
+    def autoload_install!
+      install if defined?(::Rails) && !installed?
+    end
+  end
+end
+
+# Auto-install if Rails is already loaded (e.g. via Bundler.require in a
+# console). If not, the user calls RactorRailsShim.install from boot.
+RactorRailsShim.autoload_install!

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: ractor-rails-shim
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- dev
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: |
+  Rails stores global state (Rails.application, Rails.cache, Rails.logger,
+  config set via mattr_accessor) in class-level instance variables, which
+  are illegal to read or write from non-main Ractors. This shim reroutes
+  those accessors through ActiveSupport::IsolatedExecutionState (which is
+  already Ractor-safe, being thread-local with per-ractor threads) or
+  Ractor.store_if_absent, so a Rails app can run in Ractor mode.
+
+  This is a stopgap: the goal is for Rails to do this upstream, at which
+  point the shim becomes a no-op and can be removed.
+email:
+- kachur.daniil@gmail.com
+executables:
+- ractor-rails-check
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/ractor-rails-check
+- lib/ractor_rails_shim.rb
+- lib/ractor_rails_shim/check.rb
+- lib/ractor_rails_shim/fallback_ies.rb
+- lib/ractor_rails_shim/patches.rb
+- lib/ractor_rails_shim/patches/action_controller.rb
+- lib/ractor_rails_shim/patches/action_dispatch.rb
+- lib/ractor_rails_shim/patches/action_view.rb
+- lib/ractor_rails_shim/patches/active_model_attribute.rb
+- lib/ractor_rails_shim/patches/active_record_model_schema.rb
+- lib/ractor_rails_shim/patches/active_support.rb
+- lib/ractor_rails_shim/patches/activerecord.rb
+- lib/ractor_rails_shim/patches/class_attribute.rb
+- lib/ractor_rails_shim/patches/core.rb
+- lib/ractor_rails_shim/patches/devise.rb
+- lib/ractor_rails_shim/patches/execution_wrapper.rb
+- lib/ractor_rails_shim/patches/kaminari.rb
+- lib/ractor_rails_shim/patches/make_shareable.rb
+- lib/ractor_rails_shim/patches/mattr_accessor.rb
+- lib/ractor_rails_shim/patches/openssl.rb
+- lib/ractor_rails_shim/patches/orm_adapter.rb
+- lib/ractor_rails_shim/patches/polymorphic_routes.rb
+- lib/ractor_rails_shim/patches/propshaft.rb
+- lib/ractor_rails_shim/patches/rack.rb
+- lib/ractor_rails_shim/patches/rails_module.rb
+- lib/ractor_rails_shim/patches/route_helpers.rb
+- lib/ractor_rails_shim/patches/rubygems.rb
+- lib/ractor_rails_shim/patches/url_helpers.rb
+- lib/ractor_rails_shim/patches/warden.rb
+- lib/ractor_rails_shim/patches/zeitwerk_registry.rb
+- lib/ractor_rails_shim/version.rb
+- lib/ractor_rails_shim/version_check.rb
+homepage: https://github.com/DDKatch/ractor-rails-shim
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DDKatch/ractor-rails-shim
+  source_code_uri: https://github.com/DDKatch/ractor-rails-shim
+  changelog_uri: https://github.com/DDKatch/ractor-rails-shim/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DDKatch/ractor-rails-shim/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Monkey-patch Rails class-level globals to be Ractor-safe
+test_files: []