ractor-rails-shim 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ebcbda319623aa7003caf170774074e19fdf2d6452ed086fbc5edbfec037fa5
-  data.tar.gz: 7ab60400652444ccbc5ca39ac403d387c156cc8a6178700f10c9d744db9c3fad
+  metadata.gz: c9a5a31eef9fc564a38af828fa80c55909878e502952358a129760441b36844b
+  data.tar.gz: ed5bee3ef13dd02d95ab06e806cebc2a1248da438e6f82133654419a85485c28
 SHA512:
-  metadata.gz: 69433fe039a2e2bea0302e13117a0ba701b786eaaec6e2e636d1d4786d74428e11701db2c703bc6fdb10c698febb6d5bce646adba24011513802d76de237349f
-  data.tar.gz: 615e99053521f65e7aa013d8a5c23e97991bd8b3f8593a92c9c2cf57e2ab245796bde664731ac943fe6b52681a8416c4bddac9635a7c5be6b2c3cc6339ecbdd2
+  metadata.gz: c77e93d1676466dd59164e597f888837df387669a8579e0e3f5d2056fab47e4a9b7bcca7502993f932fdffc7e906b933a9724a71ab167bfb835680e083dba3d6
+  data.tar.gz: 5822e8b0c5cb9c9ab204b9b052cb1501a1ecb4bf9a3d8737881095771835d8be5b7441f5d5d665ef1bb6781d422240a0135bc56079f02e5d08823bb8a8142c46

data/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0]
+
+### Added — Rails feature support for worker Ractors
+- **`render json:` / `render xml:` / `render js:` in worker Ractors.**
+  ActionController::Renderers defines `_render_with_renderer_*` via
+  `define_method(&block)` at boot — the block is compiled in the main Ractor
+  and can't be called from a worker. Redefined all three as string-eval'd
+  `def`s (no captured binding) callable from any Ractor.
+  (`_install_json_renderer_patch`, `patches/action_controller.rb`)
+
+- **ActionMailer `deliver_now` from a worker Ractor.** The full build +
+  ERB render + deliver path works in a worker Ractor. Patches the `mail`
+  gem (raw `@@cvar`s routed through per-Ractor IES; `Mail::Configuration`
+  per-worker; `Mail::Parsers::*Parser` + `Mail::Utilities` module ivars
+  captured into a shareable constant with string-eval `def` readers;
+  `Mail::TestMailer.deliveries` per-Ractor; `Mail::PartsList` /
+  `AttachmentsList` `DelegateClass` delegating methods redefined as
+  shareable `def`s). Patches `ActionMailer::Base` (`mailer_name` callers
+  reimplemented via string-eval; `PROTECTED_IVARS` made shareable; `config`
+  falls back to empty `OrderedOptions` when `class_attribute` resolves nil;
+  `local_prefixes` overridden for mailers). SMTP delivery also viable
+  (`Mail::SMTP::DEFAULTS` made shareable). (`patches/mail.rb`)
+
+- **ActiveStorage `has_one_attached` in a worker Ractor.** Blob creation,
+  file upload, attachment persistence, and cross-worker read-back all work.
+  16 patched layers:
+  - `has_one_attached` / `has_many_attached` scope lambda built with a
+    shareable `self` so `User.reflections` is Ractor-shareable.
+  - `Blob.build_after_unfurling` / `compute_checksum_in_chunks` redefined
+    without `tap` blocks.
+  - `Blob#service_name` falls back to `self.class.service&.name`.
+  - `Blob.type_for_attribute(:metadata)` / `attribute_types` / per-worker
+    `_default_attributes` force `Type::Serialized` with
+    `IndifferentCoder(JSON)` for `:metadata`.
+  - `generated_attribute_methods` modules captured in
+    `SHAREABLE_GEN_ATTR_METHODS` at prepare time; workers read via per-Ractor
+    IES instead of creating an empty Module.
+  - `ActiveRecord::Store#store_accessor` redefined as string-eval `def`s;
+    `store_accessor_for` coder resolution block-free.
+  - `ThroughReflection#source_reflection_name` respects `options[:source]`.
+  - `ThroughReflection#check_validity!` uses per-worker cache (was writing
+    `@validated` on frozen reflection → FrozenError).
+  - `full_table_name_prefix` / `full_table_name_suffix` reimplemented
+    without un-shareable `module_parents.detect { }` blocks.
+  - `attribute_names` aliased to `_rrs_orig_attribute_names` (was `super`
+    with no superclass method); `define_attribute_methods` calls original
+    in main (was no-op everywhere).
+  - `SecureRandom::BASE36_ALPHABET` / `BASE58_ALPHABET` deep-frozen at
+    `prepare_for_ractors!` time.
+  - `ActiveStorage.table_name_prefix` / `table_name_suffix` redefined as
+    shareable string-eval `def`s; `_seed_active_storage_prefix!` seeds
+    constants and resets `Blob`/`Attachment` `table_name` in main.
+  - `Marcel::MimeType` / `Marcel::Magic` block-based methods redefined as
+    string-eval `def`s; lookup tables frozen.
+  - `ActiveStorage::Service::Registry#fetch` works via `class_attribute`
+    fallback.
+  - `Devise.mailer` `@@mailer_ref` cvar captured as shareable constant;
+    workers read the captured copy.
+  - Callback `if:` / `unless:` Symbol conditions captured and checked via
+    `condition_allows?` in SymbolicTransport.
+  (`patches/active_storage.rb`, `patches/active_record_store.rb`,
+  `patches/marcel.rb`, `patches/active_model_attribute.rb`,
+  `patches/activerecord.rb`, `patches/activerecord_reflection.rb`,
+  `patches/devise.rb`, `callbacks/symbolic_transport.rb`,
+  `roles/callback_capture.rb`, `roles/shareability_traversal.rb`)
+
+- **`FEATURES.md` — feature support matrix.** Documents every supported /
+  unsupported / unverified feature for worker Ractor mode, with known
+  limitations (around callbacks, sanitize/Nokogiri, ActiveJob
+  `perform_later`, block `after_save` workaround, GlobalID
+  `after_create_commit` workaround).
+
+### Known limitations
+- `around_action` / `:around` callbacks — not transported (must wrap yield).
+- `sanitize` / `simple_format` (Nokogiri) — ractor-unsafe C extension.
+- ActiveJob `perform_later` / `deliver_later` — `queue_adapter`
+  `class_attribute` resolves nil in workers; `GlobalID.app` class ivar not
+  captured by the shim (nil in workers). **TODO #5**.
+- `has_one_attached` block `after_save` callback — lambda can't cross
+  Ractor boundary. Probe uses `blob.unfurl` + `insert!` workaround.
+- `ActiveStorage::Attachment` `after_create_commit` callbacks — enqueue
+  ActiveJobs via GlobalID (`@app` nil in workers). Probe uses `insert!`.
+
 ## [0.3.0]
 
 ### Changed — breaking (public API)

data/lib/ractor_rails_shim/callbacks/dependent_association_transport.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Callbacks::DependentAssociationTransport — replays a model's `dependent:`
+# association cascades on the `:destroy` kind. This is the reference transport
+# for a callback that is a LAMBDA (the `dependent:` option registers an
+# unshareable `before_destroy` lambda) but whose *effect* reduces to a
+# shareable, declarative spec: (class_name => [{name:, type:, macro:}]).
+#
+# On `:destroy`, for each captured dependent association the transport calls
+# `record.association(name).handle_dependency` — the exact method the original
+# lambda invoked — so `:destroy` / `:delete` / `:nullify` / `:restrict_*` all
+# dispatch correctly (that dispatch lives in AR's handle_dependency).
+#
+# Source shape (frozen into SHAREABLE_DEPENDENT_ASSOCIATIONS):
+#   { class_name(String) => [ {name: Symbol, type: Symbol, macro: Symbol}, … ] }
+#
+# Keyed by class *name* (not object_id) because `dependent:` replay looks up the
+# record's own class, not its ancestors (a class only cascades the associations
+# it itself declared).
+
+module RactorRailsShim
+  module Callbacks
+    class DependentAssociationTransport
+      # source: a Hash { class_name => [entry, …] } as described above, OR a
+      # callable returning that Hash (resolves the shareable constant lazily at
+      # replay time in a worker).
+      def initialize(source:)
+        @source = source
+      end
+
+      def source
+        s = @source
+        return s.call if s.respond_to?(:call)
+        return ::RactorRailsShim.const_get(s) if s.is_a?(::Symbol)
+        s
+      rescue StandardError
+        nil
+      end
+
+      # This transport ONLY owns the `:destroy` kind. (The symbolic transport
+      # also applies to :destroy for app before_destroy methods; both run.)
+      def applies_to?(kind)
+        kind == :destroy
+      end
+
+      # Re-drive every dependent association the record's class declared,
+      # BEFORE the record itself is deleted (matching the before_destroy order).
+      def before(context, kind)
+        return unless kind == :destroy
+        table = source
+        entries = table && table[class_name_of(context)]
+        return unless entries
+        entries.each do |entry|
+          assoc = association_of(context, entry[:name])
+          assoc.handle_dependency if assoc && assoc.respond_to?(:handle_dependency)
+        end
+      end
+
+      # Dependent cascades are a before_destroy concern; nothing runs after.
+      def after(_context, _kind)
+        nil
+      end
+
+      private
+
+      def class_name_of(context)
+        klass = context.class
+        klass.name if klass.respond_to?(:name)
+      rescue StandardError
+        nil
+      end
+
+      def association_of(context, name)
+        context.association(name) if context.respond_to?(:association)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim/callbacks/registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Callbacks::Registry — the coordinator that dispatches callback replay across
+# an open set of {Callbacks::Transport} objects (POODR §3 duck-typing, §5
+# message-based design, Open/Closed: add a callback *kind* by registering a new
+# transport, not by editing a `case kind` branch).
+#
+# The Registry owns the single `yield` of the real callback-chain body. Each
+# applicable transport runs its `before` work, then the block runs once, then
+# each runs its `after` work. This lets two transports legitimately share a kind
+# (e.g. on `:destroy` both the symbolic `before_destroy` filters AND the
+# `dependent:` cascade run) without any transport owning the block.
+#
+# A transport duck-types to:
+#   applies_to?(kind)   -> bool
+#   before(context, kind) -> runs before-filter work for that chain kind (no-op ok)
+#   after(context, kind)  -> runs after-filter work for that chain kind (no-op ok)
+#   install            -> hook into the framework to begin capturing (optional)
+#   capture            -> finalize the shareable snapshot (optional)
+#
+# Both `install` and `capture` are optional; the Registry forwards them and
+# ignores any transport that does not respond.
+
+module RactorRailsShim
+  module Callbacks
+    class Registry
+      # transports: an Enumerable of transport objects (duck-typed). Defaults
+      # to empty so callers can `register` incrementally.
+      def initialize(transports = [])
+        @transports = transports.is_a?(Enumerable) ? transports.to_a : Array(transports)
+      end
+
+      # Register one transport. Returns self for chaining.
+      def register(transport)
+        @transports << transport
+        self
+      end
+
+      # The subset of transports that apply to `kind`. Public so tests (and a
+      # future "is anything replayable for this kind?" check) can introspect.
+      def applicable(kind)
+        @transports.select { |t| t.applies_to?(kind) }
+      end
+
+      # Replay the empty callback chain for `context` and `kind`. Runs every
+      # applicable transport's before-work, yields the block ONCE, then runs
+      # every applicable transport's after-work. Returns the block's result.
+      # If nothing applies, just yields (matching the original empty-chain path).
+      def replay(context, kind, &block)
+        applicable = applicable(kind)
+        return yield if applicable.empty?
+        applicable.each { |t| t.before(context, kind) }
+        result = yield
+        applicable.each { |t| t.after(context, kind) }
+        result
+      end
+
+      # Forward the optional framework-hooking phase to every transport that
+      # responds. Idempotent install is each transport's own concern.
+      def install
+        @transports.each { |t| t.install if t.respond_to?(:install) }
+      end
+
+      # Forward the optional finalize-the-snapshot phase to every transport
+      # that responds. Called from the main Ractor at prepare time.
+      def capture
+        @transports.each { |t| t.capture if t.respond_to?(:capture) }
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim/callbacks/symbolic_transport.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "set"
+
+# Callbacks::SymbolicTransport — replays captured SYMBOLIC callback filters
+# (method-name filters such as `before_save :normalize_title`) for ANY callback
+# kind. This is the generic half of "a solution for any callback": a callback
+# declared with a Symbol is shareable (the Symbol crosses the Ractor boundary),
+# so we capture it at declaration time and re-invoke the method in the worker.
+#
+# Generalizes the controller-only `:process_action` replay to every kind
+# (`:save`, `:create`, `:update`, `:destroy`, `:validation`, `:commit`, …) and
+# to both controllers and ActiveRecord models.
+#
+# Source shape (frozen into SHAREABLE_DECLARED_CALLBACKS by CallbackCapture):
+#   { class_object_id => [ {chain_kind:, phase:, filter:, only:, except:}, … ] }
+# where `chain_kind` is the ActiveSupport::Callbacks chain name (e.g. :save),
+# `phase` is :before / :after, and `only`/`except` are nil or frozen Arrays of
+# action-name Symbols. All values are natively shareable.
+#
+# The transport is duck-typed around `context`:
+#   - context.class.ancestors -> Enumerable of class-like objects with object_id
+#   - context.class.object_id  -> the key the source is indexed by
+#   - context.action_name      -> Symbol or nil (only meaningful for controllers)
+#   - context.respond_to?(filter, true) + context.public_send(filter)
+#
+# `:around` symbolic filters are NOT transported (they must wrap the yield, and
+# the Registry owns the single yield). Rails `:around` callbacks are almost
+# always lambdas anyway; documented as a known limitation in ARCHITECTURE.md §5c.
+
+module RactorRailsShim
+  module Callbacks
+    class SymbolicTransport
+      # The callback chain kinds this transport owns by default. Controllers
+      # use `:process_action`; models use :save/:create/:update/:destroy and
+      # their sub-kinds (:validation, :commit, :rollback). Filter methods defined
+      # via `define_method(&block)` with an un-shareable Proc (e.g. AR's autosave
+      # association callbacks) are rescued and skipped so app `def` callbacks
+      # still run.
+      DEFAULT_KINDS = [
+        :process_action,
+        :save, :create, :update, :destroy,
+        :validation, :commit, :rollback
+      ].freeze
+
+      # source: a Hash { class_object_id => [entry, …] } as described above, OR a
+      # callable returning that Hash, OR a Symbol naming the shareable constant
+      # to resolve via const_get (so a worker reads the frozen constant after
+      # prepare, not a stale snapshot).
+      # kinds: the set of chain kinds this transport owns (default
+      # DEFAULT_KINDS, which includes model lifecycle kinds). Unshareable-Proc
+      # filters are rescued and skipped automatically.
+      def initialize(source:, kinds: DEFAULT_KINDS)
+        @source = source
+        @kinds = kinds.is_a?(::Set) ? kinds : ::Set.new(kinds.to_a)
+      end
+
+      def source
+        s = @source
+        return s.call if s.respond_to?(:call)
+        return ::RactorRailsShim.const_get(s) if s.is_a?(::Symbol)
+        s
+      rescue StandardError
+        nil
+      end
+
+      # Whether this transport owns `kind`. Configured by `kinds:` so the
+      # registry can compose multiple symbolic transports for different kind
+      # sets without editing this class (Open/Closed).
+      def applies_to?(kind)
+        @kinds.include?(kind)
+      end
+
+      # Run the matching :before filters for `kind`, ancestor-first, respecting
+      # only/except. `respond_to?` guards each send so a stale capture never
+      # raises NoMethodError (matches the original controller replay behavior).
+      #
+      # A filter defined via `define_method(&block)` with an un-shareable Proc
+      # raises "defined with an un-shareable Proc in a different Ractor" when
+      # `send`-ed in a worker. ActiveRecord generates such methods for autosave
+      # associations (e.g. `autosave_associated_records_for_*`). We SKIP those
+      # filters and continue the chain so app-defined `def` callbacks still run.
+      def before(context, kind)
+        each_applicable_filter(context, kind, :before) do |entry|
+          next unless condition_allows?(context, entry)
+          context.send(entry[:filter]) if context.respond_to?(entry[:filter], true)
+        rescue RuntimeError => e
+          raise e unless unshareable_proc_error?(e)
+          # Skip the unshareable-Proc filter; the chain continues.
+        end
+      end
+
+      # Run the matching :after filters for `kind`, ancestor-first.
+      def after(context, kind)
+        each_applicable_filter(context, kind, :after) do |entry|
+          next unless condition_allows?(context, entry)
+          context.send(entry[:filter]) if context.respond_to?(entry[:filter], true)
+        rescue RuntimeError => e
+          raise e unless unshareable_proc_error?(e)
+        end
+      end
+
+      private
+
+      # Walk the context's class hierarchy, collecting every entry whose
+      # chain_kind + phase match, then yield them in Rails' accumulation order:
+      # superclass filters BEFORE subclass filters, declaration order preserved
+      # within each class. `only`/`except` gate each entry against the context's
+      # `action_name` when present.
+      def each_applicable_filter(context, kind, phase)
+        action = action_name_of(context)
+        ancestors = ancestors_of(context)
+        # ancestors is instance-class-first; we want superclass-first so
+        # superclass filters run before subclass filters (Rails order), but
+        # declaration order is preserved within each class (no reversal).
+        collected = []
+        table = source
+        return unless table # no captured table yet → nothing to replay
+        ancestors.reverse_each do |klass|
+          entries = table[class_id_of(klass)]
+          next unless entries
+          entries.each do |entry|
+            next unless entry[:chain_kind] == kind
+            next unless entry[:phase] == phase
+            next unless action_constraint_allows?(entry, action)
+            collected << entry
+          end
+        end
+        collected.each { |e| yield e }
+      end
+
+      def action_name_of(context)
+        action = context.action_name if context.respond_to?(:action_name)
+        action = action.to_sym if action
+        action
+      rescue StandardError
+        nil
+      end
+
+      def ancestors_of(context)
+        klass = context.class
+        klass.respond_to?(:ancestors) ? klass.ancestors : [klass]
+      end
+
+      def class_id_of(klass)
+        klass.object_id
+      end
+
+      # Whether an exception is the "un-shareable Proc in a different Ractor"
+      # RuntimeError raised by `send`-ing a `define_method(&block)` method
+      # cross-Ractor. We match on a substring so the check survives minor
+      # wording changes in the Ruby error message.
+      def unshareable_proc_error?(error)
+        error.message.include?("un-shareable Proc")
+      end
+
+      # only: nil (always), [:a, :b] (only those actions); except: nil (never
+      # skip), [:a] (skip those). nil action means "no action context" — only
+      # runs if the filter has no :only constraint (i.e. :only is nil).
+      def action_constraint_allows?(entry, action)
+        only = entry[:only]
+        except = entry[:except]
+        in_only = only.nil? || (action && only.include?(action))
+        not_except = except.nil? || !(action && except.include?(action))
+        in_only && not_except
+      end
+
+      # Check Symbol if:/unless: conditions on the callback entry against the
+      # context. `if_cond` / `unless_cond` are Symbol method names (or nil).
+      # The method is called on the context; truthy = run, falsy = skip.
+      # Non-Symbol conditions (lambdas/Procs) are NOT captured (they're
+      # unshareable), so nil means "no condition" (always allow).
+      def condition_allows?(context, entry)
+        if entry[:if_cond]
+          return false unless context.respond_to?(entry[:if_cond], true) &&
+                              context.send(entry[:if_cond])
+        end
+        if entry[:unless_cond]
+          return false if context.respond_to?(entry[:unless_cond], true) &&
+                           context.send(entry[:unless_cond])
+        end
+        true
+      rescue StandardError
+        # If the condition method raises, skip the callback (safer than
+        # running it unconditionally).
+        false
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim/callbacks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Callbacks — the generalized callback-transport layer (POODR §3 duck-typed
+# interface, §5 message-based design, Open/Closed). See ARCHITECTURE.md §5c.
+#
+# This barrel requires the Registry + the two built-in transports and exposes
+# `Callbacks.registry`, a per-Ractor Registry wired to the shim's shareable
+# callback tables. The storage strategy's `replay_callbacks!` delegates to it
+# and the nil-safe `run_callbacks` patch triggers it on an empty chain. Adding a
+# new callback *kind* means registering a new transport here — no `if kind ==`
+# branches anywhere in the hot path.
+#
+# Ractor note: the Registry/transport objects are built PER Ractor and memoized
+# in Ractor.current (NOT in a class ivar) because (a) class/module ivars set in
+# the main Ractor raise IsolationError when a worker reads them, and (b) the
+# transports' source is a Symbol (the constant name) resolved via const_get,
+# which works in any Ractor — the frozen shareable constants ARE readable
+# cross-Ractor even though ivars are not.
+
+require_relative "callbacks/registry"
+require_relative "callbacks/symbolic_transport"
+require_relative "callbacks/dependent_association_transport"
+
+module RactorRailsShim
+  module Callbacks
+    # The constant names the built-in transports resolve at replay time.
+    DECLARED_CALLBACKS_CONST = :SHAREABLE_DECLARED_CALLBACKS
+    DEPENDENT_ASSOCIATIONS_CONST = :SHAREABLE_DEPENDENT_ASSOCIATIONS
+
+    class << self
+      # The active Registry for THIS Ractor. Built once per Ractor and cached
+      # in Ractor.current (a class ivar would raise IsolationError in workers).
+      # Tests may replace it via `registry=` (per-Ractor) to inject fakes.
+      def registry
+        cache = Ractor.current
+        cache[:rrs_callbacks_registry] ||= build_default_registry
+      end
+
+      def registry=(value)
+        Ractor.current[:rrs_callbacks_registry] = value
+      end
+
+      # Forget the cached registry (e.g. after a re-prepare). Per-Ractor.
+      def reset_registry
+        Ractor.current[:rrs_callbacks_registry] = nil
+      end
+
+      # Build a fresh Registry wired to the shim's shareable callback tables.
+      # Public so tests/integration can rebuild after a re-prepare. The
+      # transports take the CONSTANT NAME (a Symbol) and resolve it themselves
+      # via const_get at replay time, so no main-Ractor-bound object crosses the
+      # boundary.
+      def build_default_registry
+        Registry.new([
+          SymbolicTransport.new(source: DECLARED_CALLBACKS_CONST),
+          DependentAssociationTransport.new(source: DEPENDENT_ASSOCIATIONS_CONST)
+        ])
+      end
+    end
+  end
+end