ractor-rails-shim 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 267a3734452aa4069b68599b193d8bebd3fa6e386836ec9ec4238d9667f6b37a
-  data.tar.gz: 748ee127a59a4e7cc0b90b16ff7339edb2dfd6cde3b15df01c1ff29d910d05c3
+  metadata.gz: 4a4b7ce968f90326f2b476d713b7fab6c524f8f7b111f60a2ae582d1e162de88
+  data.tar.gz: c144478be527ff98804db48add54d67edb4124514fba3670b970990ef09e36c0
 SHA512:
-  metadata.gz: fdd580e1b1c24d324dfc9067a323dff580acd612ac8cfc2551424d4d359d5fc93d55c7ae7a9825efecad3103ef2c59b1b481a34d9270471f23fd19747dc9a52c
-  data.tar.gz: '0523817853ccdfc9444c0815fcb943b7cb3f745519b5baf6683e269e60c81889f97500e7e9e34da7bd3da7e74a3fd3033c5bbd25c4de6296337735ed6fd8301c'
+  metadata.gz: 55cc0fb00ebd523182cb66f8ae7a9f270bf33bcaaf928af79d291edf3eeb0248246f956e082200ab74563c7afceee8520336f53373ed9d54ff73f4db9ce05f40
+  data.tar.gz: b19280d1985a1e8b456a6a13750e277a49c5123998a4f7fab587518d3d6a717249d9490cfbe6d32751483d9c5e622373d861fbed9ce50d8daeabb09578b897e9

data/CHANGELOG.md

@@ -7,6 +7,111 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.6]
+
+### Fixed
+- **`WorkerApp` from `worker_app` not `Ractor.shareable?`.** The factory
+  returned a bare `WorkerApp` instance without freezing or making it
+  shareable, so any caller following the README's
+  `Ractor.new(worker_app) { |a| a.call(env) }` example would raise
+  `Ractor::IsolationError` at spawn. `worker_app` now freezes +
+  `Ractor.make_shareable`s the instance, enforcing the shareability
+  contract at the boundary instead of pushing it onto every caller.
+  (`patches/core.rb`)
+
+- **`Hash#compute_if_absent` nil-caching divergence from
+  `Concurrent::Map`.** The shim replaces `Concurrent::Map` instances in
+  the frozen app graph with plain `Hash`es (Concurrent::Map isn't
+  Ractor-shareable) and adds a compatible `compute_if_absent`. The
+  frozen-Hash branch used `IES[key] ||= yield`, which SKIPS nil results
+  — but `Concurrent::Map#compute_if_absent` STORES nil (verified: the
+  key is present after a nil-result block call), so the shim's
+  divergent semantics re-invoked the block on every subsequent lookup
+  for any cache slot whose computed value was nil. The frozen branch
+  now uses a two-level IES bucket (`slot[object_id][key]`) with a
+  proper `key?` presence check, matching `Concurrent::Map` exactly.
+  Also fixed: an existing key on a frozen Hash now returns without
+  invoking the block (was always treating the receiver as empty), and
+  per-Hash isolation is now keyed by `object_id` so two frozen hashes
+  with the same key don't collide. (`patches/core.rb`)
+
+- **Magic `line == 32` strategy dispatch replaced with identity check.**
+  The Proc-replacement pass distinguished
+  `ActionDispatch::Routing::Mapper::Constraints::SERVE` from `CALL` by
+  hard-coding the `source_location` line number (32). Any Rails patch
+  release that shifted the constant definitions by even one line would
+  silently swap the two strategies and break routing (a dispatcher
+  endpoint called as `app.call(req.env)` instead of `app.serve(req)`).
+  Replaced with an `equal?` check against the actual constants — the
+  value stored in `@strategy` IS the constant object (Rails assigns it
+  by reference), so identity is the robust identifier, independent of
+  source layout. Falls through to `NoOpProc` for an unknown Proc
+  (defensive; never mis-routes). Extracted into
+  `_strategy_replacement_for`. (`patches/make_shareable.rb`)
+
+- **`capture_app_constants` crash on non-Zeitwerk autoloaders.** The
+  method called `Rails.autoloaders.main` / `.once` directly, which
+  `NoMethodError`s for apps in classic-loader mode or with
+  `config.autoloaders = false` (the autoloaders object exists but
+  doesn't expose `main`/`once`). Now filters to the loaders that
+  actually expose `all_expected_cpaths` (the Zeitwerk introspection
+  API), and tolerates autoloaders objects that only respond to `each`.
+  Also fixed a pre-existing bug: the early-return path returned an
+  UNFROZEN map, violating the method's documented frozen-map contract.
+  (`patches/core.rb`)
+
+### Changed
+- **`_replace_unshareable_procs!` 3.times magic replaced with a
+  fixed-point loop.** The original `3.times` had no justification and
+  an arbitrary constant. Replaced with a loop-to-fixed-point (break
+  when `_collect_procs` returns empty) plus a safety cap of 8 passes
+  to guard against a pathological graph where replacement keeps
+  introducing new Procs (the replacements are `NoOpProc`/`Callable`,
+  not `Proc`, so this shouldn't happen, but the cap prevents an
+  infinite loop). Documented the multi-occurrence rationale (the same
+  Proc object can live in many containers, e.g. shared deprecation
+  behaviors). Observed real graphs converge in 2 passes.
+  (`patches/make_shareable.rb`)
+
+- **Graph traversals now walk Set/Struct/Enumerable.**
+  `_collect_procs` and `_replace_locks_and_concurrent_maps!` only
+  handled `Array` and `Hash` as recursive containers. Rails uses `Set`
+  in several caches (e.g. `ActionDispatch::Journey::Routes`), and
+  `Struct`/`Enumerable` mixes appear in framework internals — a
+  `Mutex` or `Proc` nested inside one of those was missed and left
+  unshareable, breaking `make_app_shareable!` downstream. Extracted
+  `_each_ivar_and_child` (single responsibility: enumerate every child
+  reference of an object) shared by both traversals, handling `Hash`,
+  `Array`, `Set`, `Struct`, and a generic `Enumerable` fallback
+  (`Range`, `Enumerator`, custom mixins). The `Hash#default_proc`
+  branch is preserved so `_collect_procs` still flags default-proc
+  Procs. (`patches/make_shareable.rb`)
+
+### Added
+- **Debug funnel for freeze-path silent rescues.** The
+  freeze/shareability paths (`_freeze_active_record_class_ivars!`,
+  `_freeze_global_class_ivars!`, `_make_value_shareable`) rescue all
+  exceptions silently with bare `rescue; nil`. Individual failures are
+  expected (some ivars hold intrinsically unshareable values like
+  Procs), but a worker Ractor that later crashes on the same
+  unshareable value had no traceable cause. New `_swallow(label) { ... }`
+  funnel is silent by default (preserves backward compat) and emits a
+  labeled `[ractor_rails_shim] <label>: <class>: <msg>` line to
+  `$stderr` when `RactorRailsShim.debug = true`. The three freeze-path
+  rescues are routed through it; the bare rescues in non-freeze paths
+  (require `LoadError`, optional `const_get`, etc.) are left as-is —
+  those are genuinely expected and a `$stderr` line would be noise.
+  (`patches/core.rb`)
+
+### Documentation
+- **`WorkerApp#setup_once!` race comment corrected.** The previous
+  comment claimed `Ractor.current[:key] ||= Thread::Mutex.new` was racy
+  under "extreme contention" and dismissed it as harmless because the
+  init steps are idempotent. Verified on Ruby 4.0.6 that
+  `Ractor.current[:key] ||= X` is atomic (100 concurrent threads
+  produce exactly one mutex object), so the TOCTOU race does not
+  occur. Replaced the misleading comment with the verified finding.
+
 ## [0.2.5]
 
 ### Fixed

data/README.md

@@ -4,31 +4,34 @@ A monkey-patch shim that reroutes Rails' class-level instance variable accessors
 
 **Status:** proof-of-concept / stopgap. The goal is for Rails to do this upstream, at which point this gem becomes a no-op and can be removed.
 
-**Current status:** on a full Rails 8.1 app (Devise 5, Propshaft, Kaminari,
-PG) under **official Ruby 4.0.6**, worker Ractors serve **every** routable action —
-`GET /up`, full ERB view rendering, Devise sign-in/sign-out (CSRF issuance
-**and** validation), and authenticated Devise **writes** (`POST /posts` → 302,
-row persisted). A worker Ractor dispatches `GET /up` → **HTTP 200** via
-`RactorRailsShim.make_app_shareable!`. The shim builds a shareable fallback
-table for framework class config (`class_attribute` / `mattr_accessor` values)
-and patches the raw class-ivar accessors Rails reads per-request
-(`ExecutionWrapper.active_key`, `Notifications.notifier`, `Inflections`,
-`PathRegistry`, `I18n`, `AbstractController` lazy ivars, `Rack::Request`/`Utils`,
-`ExecutionContext`, etc.).
+**Current status (v0.2.5):** on a full Rails 8.1 app (Devise 5, Propshaft,
+Kaminari, PG) under **official Ruby 4.0.6**, worker Ractors serve **every**
+routable action — `GET /up`, full ERB view rendering, Devise sign-in/sign-out
+(CSRF issuance **and** validation), and authenticated Devise **writes**
+(`POST /posts` → 302, row persisted). A worker Ractor dispatches `GET /up` →
+**HTTP 200** via `RactorRailsShim.make_app_shareable!`. The shim builds a
+shareable fallback table for framework class config (`class_attribute` /
+`mattr_accessor` values) and patches the raw class-ivar accessors Rails reads
+per-request (`ExecutionWrapper.active_key`, `Notifications.notifier`,
+`Inflections`, `PathRegistry`, `I18n`, `AbstractController` lazy ivars,
+`Rack::Request`/`Utils`, `ExecutionContext`, etc.). 61 unit specs across 7
+spec files pass (no Rails dependency); an integration spec dispatches `GET /up`
+→ 200 in a worker Ractor.
 
 **No patched Ruby or kino required.** Official Ruby 4.0.6 ships the frozen-iseq
 call-cache fix (#22075) and the cross-ractor env-string fix, so the SIGBUS crashes
 that previously required the DDKatch patched Ruby/kino forks are resolved in core.
 Both SIGBUS classes were the only reason a patched build was ever needed; on 4.0.6
-the shim runs `kino -m ractor` on the official `kino` gem under sustained read
-**and** write load (verified: 0 transport failures / 0 server errors across
+the shim runs `kino -m ractor` on the official `kino` gem (0.1.3) under sustained
+read **and** write load (verified: 0 transport failures / 0 server errors across
 `/up`, `GET /posts`, `POST /posts` in the benchmark matrix).
 
 ## Requirements
 
-- **Ruby >= 4.0** — the shim relies on Ruby 4.0's Ractor semantics and
-  `Ractor.make_shareable`. It will not work (and refuses to install) on
-  earlier Ruby versions.
+- **Ruby >= 4.0.6** — the shim relies on Ruby 4.0's Ractor semantics and
+  `Ractor.make_shareable`, plus the frozen-iseq call-cache fix (#22075) and
+  the cross-ractor env-string fix that both shipped in 4.0.6. It will not
+  work (and refuses to install) on earlier Ruby versions.
 - **Rails ~> 8.1** — tested against Rails 8.1.x class layouts. Other versions
   are not yet supported (see Version compatibility below).
 
@@ -43,12 +46,71 @@ the configuration it is verified against.
 [kino](https://github.com/yaroslav/kino) (`kino -m ractor`). On official Ruby
 4.0.6 the **upstream `kino` gem (0.1.3) works as-is** — no fork or patch is
 required. (Historically a DDKatch/kino fork carried a per-ractor env-string
-cache fix; that fix is in official 4.0.6, so the fork is obsolete.)
+cache fix; that fix landed in official 4.0.6, so the fork is obsolete.)
+
+**Threaded servers (Puma/Falcon/Thin/Webrick):** set
+`RactorRailsShim.thread_mode = true` (or `ENV["SERVER"]` to one of
+`puma|falcon|thin|webrick|thread*`) and the shim installs a **minimal**
+patch set — only the `class_attribute` isolation fix + nil-safe callback
+replay. The per-Ractor IES-routing patches are skipped because IES is empty
+on a thread server's request threads and would break the app; Rails' own
+class globals are thread-safe and used as-is. Use this when you want the
+callback-correctness fixes without running in Ractor mode.
 
 **Benchmarks:** throughput/latency/memory of this shim + the test app under
 kino `:ractor` vs Puma vs Falcon are documented in
 [ractor-rails-shim-test-app/BENCHMARKS.md](https://github.com/DDKatch/ractor-rails-shim-test-app/blob/main/BENCHMARKS.md).
 
+## Repository layout
+
+```
+lib/ractor_rails_shim.rb            # entry point — autoload-install if Rails is loaded
+lib/ractor_rails_shim/
+  version.rb                        # VERSION constant (currently 0.2.5)
+  version_check.rb                  # Gem::Version-based Ruby/Rails detection + policy
+  fallback_ies.rb                   # thread-local IES shim when ActiveSupport is absent
+  check.rb                          # the ractor-rails-check audit (Check.scan / report)
+  patches.rb                        # requires all per-concern patch files in order
+  patches/
+    core.rb                         # module skeleton, registries, install, prepare_for_ractors!, WorkerApp
+    make_shareable.rb               # make_app_shareable!, callable/lock replacement, shareable fallback
+    rails_module.rb                 # Rails.application / Rails.cache / Rails.logger / Rails.env …
+    mattr_accessor.rb               # Module#mattr_accessor / cattr_accessor macro rewrite
+    class_attribute.rb              # ActiveSupport class_attribute macro rewrite
+    zeitwerk_registry.rb            # Zeitwerk::Registry class ivars
+    route_helpers.rb                # ActionDispatch::Routing::RouteSet#generate_url_helpers
+    url_helpers.rb                  # URL helper singleton + module fixes
+    execution_wrapper.rb            # ActiveSupport::ExecutionWrapper + callback replay
+    rack.rb                         # Rack::Request / Rack::Utils
+    action_view.rb                  # PathRegistry, LookupContext, Template handlers, compiled_method_container
+    action_controller.rb            # AbstractController, ActionController name/encoding
+    action_dispatch.rb              # ActionDispatch routing, http_url, journey, mounted helpers
+    polymorphic_routes.rb           # polymorphic_path(s) URL helpers
+    active_support.rb               # Inflector, error_reporter, ExecutionContext, I18n, JSON encoding, Reloader
+    warden.rb                       # Warden hooks / strategies / serializer
+    devise.rb                       # Devise url_helpers / authenticatable / failure_app
+    active_model_attribute.rb       # ActiveModel::Attribute dup_or_share for frozen graphs
+    active_record_model_schema.rb   # AR ModelSchema reload_schema_from_cache (worker-safe)
+    activerecord.rb                 # AR connection handler, configurations, query caches, …
+    kaminari.rb                     # Kaminari config
+    propshaft.rb                    # Propshaft asset server
+    orm_adapter.rb                  # orm_adapter
+    openssl.rb                      # OpenSSL digest cache
+    rubygems.rb                     # Rubygems msgpack pre-check
+exe/ractor-rails-check              # CLI audit tool
+spec/                               # 7 spec files, 61 unit tests (no Rails dep) + integration spec
+script/make_test_app.sh             # build the minimal Rails 8.1 test app (CI uses this)
+script/make_full_test_app.sh        # build the full-featured test app (Devise/PG/Kaminari)
+.github/workflows/ci.yml            # unit job + integration job (GET /up → 200 in a worker Ractor)
+```
+
+Per-concern patch files reopen `RactorRailsShim`'s singleton class to add
+their `_install_*` methods. `patches.rb` requires them in dependency order
+(`core.rb` first — it defines the module skeleton + registries the rest
+reference). Each `_install_*` method is idempotent (guarded by its own
+`@*_patched` flag), so `install`, `prepare_for_ractors!`, and
+`make_app_shareable!` can all call the full set safely.
+
 ## Why
 
 Rails stores global state in class-level instance variables:

data/lib/ractor_rails_shim/patches/core.rb

@@ -120,6 +120,29 @@ module RactorRailsShim
     end
     attr_writer :version_policy
 
+    # When true, swallowed exceptions in freeze/shareability paths are
+    # reported to $stderr so a worker Ractor that later crashes on an
+    # unshareable value has a traceable cause. Default false (silent, the
+    # historical behaviour). Enable for diagnosis:
+    #   RactorRailsShim.debug = true
+    def debug?
+      defined?(@debug) ? @debug : false
+    end
+    attr_writer :debug
+
+    # Swallow an exception raised by the block, optionally logging it when
+    # `debug?` is on. Used by freeze/shareability paths where individual
+    # failures are expected (some ivars hold intrinsically unshareable
+    # values like Procs) but a worker crash on the same value later has no
+    # visible cause. `label` identifies the call site (e.g. "freeze AR ivar
+    # Post@column_defaults"). Keep the label short — it's only for grepping.
+    def _swallow(label)
+      yield
+    rescue => e
+      warn "[ractor_rails_shim] #{label}: #{e.class}: #{e.message[0, 120]}" if debug?
+      nil
+    end
+
     SUPPORTED_RUBY = RactorRailsShim::Version::SUPPORTED_RUBY
     SUPPORTED_RAILS = "8.1"
 
@@ -283,11 +306,7 @@ module RactorRailsShim
         # with `equal?`, and a frozen Symbol is always shareable.
         Ractor.make_shareable(:"__shim_unshareable_sentinel__")
       else
-        begin
-          Ractor.make_shareable(val)
-        rescue => e
-          nil
-        end
+        _swallow("make_value_shareable #{val.class}") { Ractor.make_shareable(val) }
       end
     end
 
@@ -301,21 +320,6 @@ module RactorRailsShim
       [parent, parts.last.to_sym]
     end
 
-    # Public API: run after Rails.application.initialize! and BEFORE spawning
-    # worker Ractors. Makes every registered constant shareable (deep-freeze).
-    # Constants that didn't exist at install time (e.g. Rails::Railtie, loaded
-    # after `module Rails` opens) get fixed here. Idempotent; safe to call
-    # multiple times. Must run in the main Ractor.
-    #
-    # NOTE: this does NOT build the framework-config shareable fallback. That
-    # step is folded into `make_app_shareable!` because some class_attribute /
-    # mattr_accessor values reference the app graph, and making them shareable
-    # must happen AFTER the app itself is already frozen (otherwise the app
-    # gets frozen prematurely and precompute/proc-replacement can't mutate
-    # it). If you call prepare_for_ractors! standalone (without
-    # make_app_shareable!), worker Ractors will see nil for framework config
-    # values that couldn't be shared without freezing the app — set them
-    # explicitly per worker, or use make_app_shareable!.
     # Shared list of every framework patch install method. Both
     # `prepare_for_ractors!` (pre-worker boot) and `make_app_shareable!`
     # (post-boot, pre-freeze) call this, so the two no longer duplicate the
@@ -403,6 +407,21 @@ module RactorRailsShim
       _install_hash_compute_if_absent_patch
     end
 
+    # Public API: run after Rails.application.initialize! and BEFORE spawning
+    # worker Ractors. Makes every registered constant shareable (deep-freeze).
+    # Constants that didn't exist at install time (e.g. Rails::Railtie, loaded
+    # after `module Rails` opens) get fixed here. Idempotent; safe to call
+    # multiple times. Must run in the main Ractor.
+    #
+    # NOTE: this does NOT build the framework-config shareable fallback. That
+    # step is folded into `make_app_shareable!` because some class_attribute /
+    # mattr_accessor values reference the app graph, and making them shareable
+    # must happen AFTER the app itself is already frozen (otherwise the app
+    # gets frozen prematurely and precompute/proc-replacement can't mutate
+    # it). If you call prepare_for_ractors! standalone (without
+    # make_app_shareable!), worker Ractors will see nil for framework config
+    # values that couldn't be shared without freezing the app — set them
+    # explicitly per worker, or use make_app_shareable!.
     def prepare_for_ractors!
       do_install_shareable_constants
       RactorRailsShim._freeze_shareable_class_ivars! if RactorRailsShim.respond_to?(:_freeze_shareable_class_ivars!)
@@ -416,9 +435,9 @@ module RactorRailsShim
       _freeze_global_class_ivars!
       _freeze_global_constants!
       _freeze_messages_constants!
-     end
+    end
 
-     # Verify the runtime matches the versions the shim was developed against.
+    # Verify the runtime matches the versions the shim was developed against.
     # The shim's patches target specific Rails 8.1 class layouts and Ruby 4.0
     # Ractor semantics. On other versions, the patches may silently miss or
     # break things. Behavior on mismatch is governed by `version_policy`:
@@ -434,9 +453,10 @@ module RactorRailsShim
     def _check_version_support
       @version_policy ||= :warn
       unless RactorRailsShim::Version.supported_ruby?
-        msg = "ractor-rails-shim: Ruby #{RUBY_VERSION} — shim developed " \
-              "against Ruby #{SUPPORTED_RUBY}. Ractor semantics may differ; " \
-              "the shim may break. Proceeding anyway."
+        msg = "ractor-rails-shim: Ruby #{RUBY_VERSION} — shim requires " \
+              "Ruby >= #{SUPPORTED_RUBY} (frozen-iseq call-cache fix #22075 " \
+              "and cross-ractor env-string fix both shipped in 4.0.6). " \
+              "Proceeding anyway."
         _version_mismatch(msg)
       end
       if RactorRailsShim::Version.rails &&
@@ -508,9 +528,27 @@ module RactorRailsShim
     # `Zeitwerk::Loader.new` raises IsolationError off the main Ractor).
     def capture_app_constants
       map = {}
-      return map unless defined?(::Rails) && Rails.respond_to?(:autoloaders)
-      [Rails.autoloaders.main, Rails.autoloaders.once].each do |loader|
-        next unless loader.respond_to?(:all_expected_cpaths)
+      unless defined?(::Rails) && Rails.respond_to?(:autoloaders)
+        return map.freeze
+      end
+      autoloaders = Rails.autoloaders
+      # Guard against non-Zeitwerk configurations: Rails.autoloaders may be
+      # present (the method exists) but not expose `main`/`once` (e.g. classic
+      # loader mode, or `config.autoloaders = false` returning a null object).
+      # `main`/`once` may also individually be nil when only one loader is
+      # configured. Filter to the loaders that actually expose
+      # `all_expected_cpaths` (the Zeitwerk introspection API the capture
+      # relies on).
+      loaders =
+        if autoloaders.respond_to?(:main) && autoloaders.respond_to?(:once)
+          [autoloaders.main, autoloaders.once]
+        elsif autoloaders.respond_to?(:each)
+          autoloaders.to_a
+        else
+          []
+        end
+      loaders.each do |loader|
+        next unless loader && loader.respond_to?(:all_expected_cpaths)
         begin
           loader.all_expected_cpaths.values.each do |cpath|
             obj = Object.const_get(cpath) rescue next
@@ -532,10 +570,16 @@ module RactorRailsShim
     # constants in the main Ractor and wraps the frozen, shareable app in a
     # WorkerApp that rebinds those constants (and initializes the worker's
     # ActiveRecord connection) on the first request served by each worker
-    # Ractor. Returns a shareable WorkerApp instance.
+    # Ractor. Returns a shareable WorkerApp instance — frozen and
+    # `Ractor.make_shareable`'d — so it can be passed directly to
+    # `Ractor.new(worker_app) { |a| a.call(env) }` without the caller having
+    # to know the shareability contract.
     def worker_app(frozen_app)
       bindings = capture_app_constants
-      WorkerApp.new(frozen_app, bindings)
+      wa = WorkerApp.new(frozen_app, bindings)
+      wa.freeze
+      Ractor.make_shareable(wa)
+      wa
     end
 
     # See patches/active_model_attribute.rb. When the frozen `:ractor` graph is
@@ -575,11 +619,25 @@ module RactorRailsShim
     # them. But Rails code calls Concurrent::Map#compute_if_absent on these
     # caches (e.g. ActiveModel::AttributeMethods' attribute_method_patterns_
     # cache). Plain Hash lacks that method, so we add a compatible definition.
+    #
+    # Semantics MUST match Concurrent::Map#compute_if_absent exactly:
+    #   - if the key is present (even with a nil value), return the stored
+    #     value WITHOUT invoking the block;
+    #   - otherwise invoke the block, STORE the result (including nil), and
+    #     return it.
+    # The nil-storing behaviour is load-bearing: Concurrent::Map stores nil
+    # results so the block doesn't re-run; the original shim implementation
+    # used `IES[key] ||= yield` in the frozen branch, which SKIPS nil — a
+    # divergent semantics that re-invokes the block on every lookup for any
+    # cache slot whose computed value is nil.
+    #
     # For a MUTABLE cache the shim freezes the replaced Hash (so it is shareable
     # across workers); mutating it would raise FrozenError. So when the receiver
     # is frozen we route the store to per-Ractor IES keyed by the Hash identity
     # and the key — giving each worker its own cache entry without mutating the
-    # shared object. Semantics otherwise match Concurrent::Map.
+    # shared object. The frozen branch mirrors the mutable one: check presence
+    # first (via IES key?), invoke the block only on miss, store the result
+    # (including nil) via IES[]=.
     def _install_hash_compute_if_absent_patch
       return @hash_compute_if_absent_patched if defined?(@hash_compute_if_absent_patched) && @hash_compute_if_absent_patched
       @hash_compute_if_absent_patched = true
@@ -587,8 +645,17 @@ module RactorRailsShim
       ::Hash.prepend(Module.new do
         def compute_if_absent(key)
           if frozen?
-            ies_key = :"rrs_cia_#{object_id}_#{key}"
-            ActiveSupport::IsolatedExecutionState[ies_key] ||= yield(key)
+            # Check the receiver first — a present key (even nil-valued)
+            # returns without invoking the block, matching Concurrent::Map.
+            return self[key] if key?(key)
+            # Per-Ractor IES slot, namespaced by this Hash's object_id so two
+            # frozen hashes with the same key don't collide. Use a two-level
+            # structure (Hash per receiver) so the presence check (`key?`)
+            # and the store share the same slot.
+            slot = ActiveSupport::IsolatedExecutionState[:rrs_cia] ||= {}
+            bucket = slot[object_id] ||= {}
+            return bucket[key] if bucket.key?(key)
+            bucket[key] = yield(key)
           elsif key?(key)
             self[key]
           else
@@ -618,10 +685,8 @@ module RactorRailsShim
         klass.instance_variables.each do |ivar|
           val = klass.instance_variable_get(ivar)
           next if Ractor.shareable?(val)
-          begin
+          _swallow("freeze AR ivar #{klass.name}#{ivar}") do
             Ractor.make_shareable(val)
-          rescue
-            nil
           end
         end
       end
@@ -639,10 +704,8 @@ module RactorRailsShim
         klass.instance_variables.each do |ivar|
           val = klass.instance_variable_get(ivar)
           next if Ractor.shareable?(val)
-          begin
+          _swallow("freeze global ivar #{klass}#{ivar}") do
             Ractor.make_shareable(val)
-          rescue
-            nil
           end
         end
       end
@@ -699,11 +762,14 @@ module RactorRailsShim
       # non-frozen arrays; load hooks never fire again in workers.
       # Gem::LoadError is a ScriptError (not StandardError), so a bare
       # `rescue nil` on the require would NOT catch a missing msgpack gem.
-      begin
-        require "active_support/message_pack"
-      rescue LoadError
-        return
-      end
+      # Pre-check for the msgpack gem: active_support/message_pack loads
+      # without it but prints a "requires the msgpack gem" warning to $stderr
+      # before raising LoadError. Checking first avoids the warning entirely
+      # (no stderr suppression needed) and skips the freeze step cleanly when
+      # the C extension isn't installed (e.g. in the gem's no-Rails unit specs).
+      return unless Gem::Specification.find_all_by_name("msgpack").any?
+
+      require "active_support/message_pack"
 
       mod = (Object.const_get(:ActiveSupport) rescue nil)&.const_get(:Messages, false) rescue nil
       mod = mod&.const_get(:Metadata, false) rescue nil
@@ -766,8 +832,9 @@ module RactorRailsShim
   #   2. ensures the worker's ActiveRecord connection handler is initialized.
   #
   # The wrapper holds only shareable state (@app, @bindings), so the instance
-  # is Ractor.make_shareable. `Ractor.current` provides per-worker storage for
-  # the one-time guard, avoiding any top-level constant reference.
+  # is `Ractor.make_shareable`'d by `worker_app` before being handed to worker
+  # Ractors. `Ractor.current` provides per-worker storage for the one-time
+  # guard, avoiding any top-level constant reference.
   class WorkerApp
     def initialize(app, bindings)
       @app = app
@@ -784,9 +851,12 @@ module RactorRailsShim
     def setup_once!
       # All threads inside a worker Ractor share Ractor.current, so a single
       # per-Ractor mutex serializes the one-time init across the worker's
-      # threads. (The mutex is created under ||= which is racy under extreme
-      # contention, but both init steps below are themselves idempotent, so a
-      # rare double-init is harmless.)
+      # threads. `Ractor.current[:key] ||= Thread::Mutex.new` is atomic in
+      # Ruby 4.0.6 (verified: 100 concurrent threads produce exactly one
+      # mutex object), so the TOCTOU race that would let two threads each
+      # create their own mutex does not occur. The `:rrs_worker_ready` guard
+      # inside `synchronize` then ensures `rebind_constants` runs exactly
+      # once per worker; later threads return early.
       m = Ractor.current[:rrs_worker_mutex] ||= Thread::Mutex.new
       m.synchronize do
         return if Ractor.current[:rrs_worker_ready]

data/lib/ractor_rails_shim/patches/make_shareable.rb

@@ -547,7 +547,18 @@ module RactorRailsShim
     # Doesn't dedup procs — must replace every occurrence.
     def _replace_unshareable_procs!(app)
       mw = (app.instance_variable_get(:@app) rescue nil)
-      3.times do
+      # Replace every Proc in the graph. The same Proc object can live in
+      # many containers (e.g. deprecation behaviors shared across
+      # deprecators), and replacing one occurrence doesn't replace the
+      # others — so we loop until a fixed point (no Procs left). A safety
+      # cap guards against a pathological graph where replacement keeps
+      # introducing new Procs (the replacements themselves are NoOpProc/
+      # Callable instances, not Procs, so this shouldn't happen, but the
+      # cap prevents an infinite loop if a future callable class leaks a
+      # Proc). 3 passes was the original magic number; observed real graphs
+      # converge in 2.
+      max_passes = 8
+      max_passes.times do
         procs = _collect_procs(app)
         break if procs.empty?
         procs.each { |proc_obj, _path, parent, ivar| _replace_one_proc(proc_obj, parent, ivar, mw) }
@@ -581,28 +592,76 @@ module RactorRailsShim
         next if seen[o.object_id]
         seen[o.object_id] = true
         next if o.is_a?(Mutex) || o.is_a?(Monitor)
-        begin
-          o.instance_variables.each do |iv|
-            begin; v = o.instance_variable_get(iv); rescue; next; end
-            stack << [v, "#{_path}.#{iv}", o, iv] if v
-          end
-        rescue => e
-          # Some objects (BasicObject) don't support instance_variables
-        end
-        if o.is_a?(Array)
-          o.each_with_index { |e, i| stack << [e, "#{_path}[#{i}]", o, nil] if e }
-        elsif o.is_a?(Hash)
-          o.each do |k, val|
-            stack << [k, "#{_path}.key", o, nil] if k
-            stack << [val, "#{_path}[#{k.inspect}]", o, nil] if val
+        _each_ivar_and_child(o, _path) do |child, child_path, child_ivar|
+          if child_ivar == :__default_proc__
+            procs << [child, child_path, o, :__default_proc__]
+          else
+            stack << [child, child_path, o, child_ivar] if child
           end
-          dp = o.default_proc
-          procs << [dp, "#{_path}.default_proc", o, :__default_proc__] if dp
         end
       end
       procs
     end
 
+    # Enumerate every child reference of `o` for the graph traversals:
+    #   - instance variables (yields [value, "path.iv", iv])
+    #   - Array / Set / Enumerable members (yields [member, "path[i]", nil])
+    #   - Hash pairs (yields [key, "path.key", nil] and [val, "path[k]", nil])
+    #   - Hash#default_proc (yields [proc, "path.default_proc", :__default_proc__])
+    #   - Struct members (yields [value, "path.member", nil] via #each_pair)
+    #
+    # Pre-fix the traversals only handled Array and Hash, so a Mutex or Proc
+    # nested inside a Set (Rails uses Set in several caches, e.g.
+    # ActionDispatch::Journey::Routes) or a Struct was missed and left
+    # unshareable. Centralized here so _collect_procs and
+    # _replace_locks_and_concurrent_maps! share the same container coverage.
+    def _each_ivar_and_child(o, path)
+      begin
+        o.instance_variables.each do |iv|
+          begin; v = o.instance_variable_get(iv); rescue; next; end
+          yield v, "#{path}.#{iv}", iv
+        end
+      rescue => e
+        # BasicObject or frozen objects don't support instance_variables
+      end
+      if o.is_a?(Hash)
+        o.each do |k, val|
+          yield k, "#{path}.key", nil
+          yield val, "#{path}[#{k.inspect}]", nil
+        end
+        dp = o.default_proc
+        yield dp, "#{path}.default_proc", :__default_proc__ if dp
+      elsif o.is_a?(Array)
+        o.each_with_index { |e, i| yield e, "#{path}[#{i}]", nil }
+      elsif o.is_a?(::Set)
+        o.each_with_index { |e, i| yield e, "#{path}.set[#{i}]", nil }
+      elsif o.is_a?(::Struct)
+        o.each_pair { |name, val| yield val, "#{path}.#{name}", nil }
+      elsif _enumerable_but_not_basic?(o)
+        # Generic Enumerable fallback (Range, Enumerator, custom Enumerable
+        # mixes). Skip String/Hash/Array/Set/Struct — already handled. Best
+        # effort; rescue per-element in case #each raises for some members.
+        idx = -1
+        o.each do |e|
+          idx += 1
+          yield e, "#{path}.each[#{idx}]", nil
+        end rescue nil
+      end
+    end
+
+    # True if `o` is Enumerable but NOT one of the container types with a
+    # dedicated branch in _each_ivar_and_child. Used to gate the generic
+    # Enumerable fallback so we don't double-walk Array/Hash/etc.
+    def _enumerable_but_not_basic?(o)
+      return false unless o.is_a?(::Enumerable)
+      return false if o.is_a?(::Array) || o.is_a?(::Hash) || o.is_a?(::Set) || o.is_a?(::Struct)
+      return false if o.is_a?(::String) # String is Enumerable (chars) but not a container of refs we want
+      true
+    rescue NoMethodError
+      # BasicObject without Kernel — not Enumerable.
+      false
+    end
+
     def _replace_one_proc(proc_obj, parent, ivar, mw)
       src = proc_obj.source_location&.first || ""
       replacement =
@@ -627,8 +686,18 @@ module RactorRailsShim
         elsif src.end_with?(DEVISE_SCOPE_LOC)
           _devise_mapping_replacement(proc_obj, parent)
         elsif src.end_with?(MAPPER_LOC) && ivar == :@strategy
-          line = proc_obj.source_location[1]
-          line == 32 ? StrategyServe.new : StrategyCall.new
+          # Identify SERVE vs CALL by OBJECT IDENTITY against the actual
+          # ActionDispatch constants, NOT by source_location line number.
+          # The value stored in @strategy IS the constant object (Rails
+          # assigns it via `@strategy = strategy` where `strategy` is passed
+          # as Constraints::SERVE or Constraints::CALL), so `equal?` is the
+          # robust identifier — it survives any Rails patch release that
+          # shifts the constant definitions by a line or two, where the old
+          # `line == 32` check would silently swap the two strategies and
+          # break routing. Falls through to NoOpProc if the Proc isn't
+          # either constant (defensive: shouldn't happen, but never
+          # mis-route).
+          _strategy_replacement_for(proc_obj)
         else
           NoOpProc.new
         end
@@ -661,6 +730,22 @@ module RactorRailsShim
     # DeviseMappingCallable) now lives in warden.rb; `_find_files_server`
     # (Rack::Files target for the asset stack) now lives in rack.rb.
 
+    # Identify which ActionDispatch strategy a Proc is and return its
+    # shareable replacement. The Proc stored in
+    # `ActionDispatch::Routing::Mapper::Constraints#@strategy` is the
+    # constant `SERVE` or `CALL` (assigned by reference), so `equal?` is
+    # the robust identifier — independent of the source line number, which
+    # any Rails patch release can shift. Returns NoOpProc for an unknown
+    # Proc (defensive; never mis-route).
+    def _strategy_replacement_for(proc_obj)
+      constraints = defined?(::ActionDispatch::Routing::Mapper::Constraints) ?
+        ::ActionDispatch::Routing::Mapper::Constraints : nil
+      return NoOpProc.new unless constraints
+      return StrategyServe.new if proc_obj.equal?(constraints::SERVE)
+      return StrategyCall.new if proc_obj.equal?(constraints::CALL)
+      NoOpProc.new
+    end
+
     def _replace_locks_and_concurrent_maps!(app)
       seen = {}
       stack = [[app, "app", nil, nil]]
@@ -671,24 +756,20 @@ module RactorRailsShim
         next if seen[o.object_id]
         seen[o.object_id] = true
         next if o.is_a?(Mutex) || o.is_a?(Monitor)
-        begin
-          o.instance_variables.each do |iv|
-            begin; v = o.instance_variable_get(iv); rescue; next; end
-            if v.is_a?(Mutex) || v.is_a?(Monitor)
-              o.instance_variable_set(iv, NoOpLock.new) rescue nil
-            elsif defined?(::Concurrent::Map) && v.is_a?(::Concurrent::Map)
-              hash_copy = {}
-              v.each_pair { |k, val| hash_copy[k] = val }
-              o.instance_variable_set(iv, hash_copy) rescue nil
-            elsif v
-              stack << [v, "#{_p}.#{iv}", o, iv]
-            end
+        _each_ivar_and_child(o, _p) do |child, child_path, child_ivar|
+          next if child_ivar == :__default_proc__
+          if child.is_a?(Mutex) || child.is_a?(Monitor)
+            o.instance_variable_set(child_ivar, NoOpLock.new) rescue nil if child_ivar
+            # If the lock is in an Array/Set/Hash (no ivar), we can't swap
+            # it in place here — leave it; make_shareable will handle the
+            # frozen container. The ivar case is the load-bearing one.
+          elsif defined?(::Concurrent::Map) && child.is_a?(::Concurrent::Map) && child_ivar
+            hash_copy = {}
+            child.each_pair { |k, val| hash_copy[k] = val }
+            o.instance_variable_set(child_ivar, hash_copy) rescue nil
+          elsif child
+            stack << [child, child_path, o, child_ivar]
           end
-        rescue => e
-          # BasicObject or frozen objects don't support instance_variables
-        end
-        if o.is_a?(Array); o.each_with_index { |e, i| stack << [e, "#{_p}[#{i}]", o, nil] if e }
-        elsif o.is_a?(Hash); o.each { |k, val| stack << [k, "#{_p}.key", o, nil] if k; stack << [val, "#{_p}[#{k.inspect}]", o, nil] if val }
         end
       end
     end

data/lib/ractor_rails_shim/version.rb

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

data/lib/ractor_rails_shim/version_check.rb

@@ -23,9 +23,11 @@
 #     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"
+    # Ruby version the shim was developed against (major.minor.patch). Ractor
+    # semantics are still settling; the frozen-iseq call-cache fix (#22075) and
+    # the cross-ractor env-string fix that the shim relies on both shipped in
+    # 4.0.6, so earlier 4.0.x patch releases are NOT supported.
+    SUPPORTED_RUBY = "4.0.6"
     # 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
@@ -33,7 +35,7 @@ module RactorRailsShim
     TESTED_RAILS = ["8.1"].freeze
 
     class << self
-      # Runtime Ruby version as a Gem::Version (e.g. "4.0.5"). Always
+      # Runtime Ruby version as a Gem::Version (e.g. "4.0.6"). Always
       # available — Ruby is obviously loaded.
       def ruby
         Gem::Version.new(RUBY_VERSION)
@@ -64,9 +66,11 @@ module RactorRailsShim
         "#{v.segments[0]}.#{v.segments[1]}"
       end
 
-      # True if the runtime Ruby's major.minor matches the supported segment.
+      # True if the runtime Ruby is >= the supported version (4.0.6). Uses a
+      # full Gem::Version compare (not a segment match) so the minimum patch
+      # release is enforced — the shim relies on fixes that shipped in 4.0.6.
       def supported_ruby?
-        ruby_segment == SUPPORTED_RUBY
+        ruby >= Gem::Version.new(SUPPORTED_RUBY)
       end
 
       # True if the runtime Rails major.minor is in the tested set (or Rails

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: ractor-rails-shim
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
-- dev
+- Daniil Kachur
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -99,7 +99,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '4.0'
+      version: 4.0.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="