phlex-reactive 0.15.5 → 0.16.0

data/lib/phlex/reactive/doctor.rb

@@ -17,6 +17,7 @@ module Phlex
     # trip and (for the component checks) iterate the loaded Streamable registry.
     class Doctor
       include FiberIsolation
+      include RactorReadiness
 
       # The result of one check: a status (:ok/:fail/:unknown), a human message,
       # and (on anything but :ok) a fix line telling the adopter what to do. A
@@ -79,6 +80,7 @@ module Phlex
           verifier_check,
           base_controller_check,
           fiber_isolation_check,
+          ractor_readiness_check,
           action_check(components),
           id_check(components),
           authorization_check(components),

data/lib/phlex/reactive/engine.rb

@@ -208,6 +208,31 @@ module Phlex
         # app on Action Cable boots exactly as before.
         Phlex::Reactive::Presence.install!
       end
+
+      # Finalize the configuration once boot is over (zoolutions/phlex-reactive#364).
+      # The after_initialize block is registered from an initializer that runs
+      # after the app's config/initializers, so it runs after every
+      # after_initialize block the app registered there or in
+      # config/application.rb: one that appends to authorization_errors (the
+      # documented pattern for an app's own constants) still finds the list open.
+      initializer "phlex_reactive.finalize", after: :load_config_initializers do
+        config.after_initialize { Phlex::Reactive::Engine.finalize_boot! }
+      end
+
+      # What the finalize hook runs; public so a spec can drive it. With eager
+      # loading every component class is loaded by now, so verify_authorized's
+      # interceptor is prepended to every token-bearing class, and every
+      # class's registries and render memos (a client-only view's too) are
+      # resolved here, at boot, rather than by the first request for each
+      # class (Authorization.instrument_all!, Component::Registry.warm!).
+      def self.finalize_boot!(eager_load: ::Rails.application.config.eager_load)
+        registry = Phlex::Reactive::Component::Registry
+        if Phlex::Reactive.verify_authorized
+          Phlex::Reactive::Authorization.instrument_all!(eager_load ? Phlex::Reactive::Streamable.registered_classes : [])
+        end
+        Phlex::Reactive.finalize!
+        registry.warm!(eager_load ? registry.registered_classes : [])
+      end
     end
   end
 end

data/lib/phlex/reactive/fragment.rb

@@ -41,8 +41,9 @@ module Phlex
       # a collection is walked, so no value can make the shell render slow.
       VIEWER_PART_LIMIT = 32
       VIEWER_NODE_LIMIT = 64
-      # Components already warned about (by class name): once per component.
-      VIEWER_WARNED = Concurrent::Map.new
+      # The per-Ractor table (Phlex::Reactive::Store) of the components already
+      # warned about, by class name: once per component.
+      VIEWER_WARNINGS_KEY = :phlex_reactive_fragment_viewer_warnings
 
       # A reactive_cache_viewer value that cannot name a viewer. Internal: it
       # carries the reason from the walk to viewer_param, which logs it.
@@ -207,7 +208,7 @@ module Phlex
       # component's hook — and answers nil: "this value names nobody".
       def warn_unusable_viewer(owner, reason)
         name = owner.respond_to?(:name) ? owner.name.to_s : owner.to_s
-        return nil if VIEWER_WARNED.put_if_absent(name, true)
+        return nil unless Phlex::Reactive::Store.table(VIEWER_WARNINGS_KEY).claim?(name)
         return nil unless defined?(::Rails) && ::Rails.respond_to?(:logger)
 
         ::Rails.logger&.warn(
@@ -220,7 +221,7 @@ module Phlex
 
       # Test seam: let the once-per-component warnings fire again.
       def reset_viewer_warning!
-        VIEWER_WARNED.clear
+        Phlex::Reactive::Store.table(VIEWER_WARNINGS_KEY).clear
       end
 
       # The max-age (seconds) the endpoint answers with: the component's

data/lib/phlex/reactive/param_schema.rb

@@ -136,8 +136,9 @@ module Phlex
 
       # ActiveModel's Boolean type, instantiated once — the exact caster the
       # controller used (an unrecognized value casts to nil, which is KEPT, not
-      # dropped).
-      BOOLEAN_TYPE = ActiveModel::Type::Boolean.new
+      # dropped). Ractor-shareable (it holds no state a cast writes), so a
+      # non-main Ractor can coerce through it (zoolutions/phlex-reactive#364).
+      BOOLEAN_TYPE = defined?(::Ractor) ? ::Ractor.make_shareable(ActiveModel::Type::Boolean.new) : ActiveModel::Type::Boolean.new
       private_constant :BOOLEAN_TYPE
 
       attr_reader :schema

data/lib/phlex/reactive/pending/markup.rb

@@ -49,11 +49,28 @@ module Phlex
         # the first `>`.
         ROOT_TAG = %r{\A\s*<[^\s>/]+(?:\s+[^\s=>/]+(?:="[^"]*")?)*}
 
-        # Keyed weakly on the row class, so a class Zeitwerk replaced is not
-        # pinned between resets. A WeakKeyMap, not a WeakMap: nothing else holds
-        # the variant, so a weak VALUE would let GC drop the memo.
-        @variants = ObjectSpace::WeakKeyMap.new
-        @mutex = Mutex.new
+        # The variant memo, keyed weakly on the row class, so a class Zeitwerk
+        # replaced is not pinned between resets. A WeakKeyMap, not a WeakMap:
+        # nothing else holds the variant, so a weak VALUE would let GC drop the
+        # memo. Per-Ractor state (Phlex::Reactive::Store,
+        # zoolutions/phlex-reactive#364): a WeakKeyMap and its Mutex in module
+        # ivars could not be read from any other Ractor.
+        class Variants
+          def initialize
+            @mutex = Mutex.new
+            @map = ObjectSpace::WeakKeyMap.new
+          end
+
+          def fetch(row_class)
+            @mutex.synchronize { @map[row_class] ||= yield }
+          end
+
+          def reset!
+            @mutex.synchronize { @map = ObjectSpace::WeakKeyMap.new }
+          end
+        end
+
+        VARIANTS_KEY = :phlex_reactive_pending_variants
 
         class << self
           # The row's pending markup as HTML, or nil when the row has no hook
@@ -78,13 +95,14 @@ module Phlex
           end
 
           def variant_for(row_class)
-            @mutex.synchronize { @variants[row_class] ||= build_variant(row_class) }
+            variants.fetch(row_class) { build_variant(row_class) }
           end
 
           # Called from the engine's config.to_prepare (Rails code reload).
-          def reset!
-            @mutex.synchronize { @variants = ObjectSpace::WeakKeyMap.new }
-          end
+          def reset! = variants.reset!
+
+          # This Ractor's variant memo.
+          def variants = Phlex::Reactive::Store.fetch(VARIANTS_KEY) { Variants.new }
 
           private
 

data/lib/phlex/reactive/pending.rb

@@ -322,11 +322,11 @@ data-reactive-defer-src="#{ERB::Util.html_escape(src)}" data-reactive-defer-sinc
 
         # No settle lane is a CONFIG fact, not a per-reply event — warn once per
         # process (a pending reply can fire per click; per-reply spam would bury
-        # the signal), then degrade to a plain enqueue.
+        # the signal), then degrade to a plain enqueue. The "warned" flag is
+        # per-Ractor state (Store), never a module ivar written on the request
+        # path.
         def warn_no_lane
-          return if @no_lane_warned
-
-          @no_lane_warned = true
+          return unless Phlex::Reactive::Store.first_warning?(:pending_no_lane)
           return unless defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
 
           ::Rails.logger.warn(

data/lib/phlex/reactive/shareable.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # Ractor-shareable values for the state the gem keeps on its modules and
+    # classes (zoolutions/phlex-reactive#364): a non-main Ractor can read a
+    # module instance variable or a constant only when its value is
+    # Ractor-shareable.
+    module Shareable
+      module_function
+
+      # A Ractor-shareable version of value when one can be made, else value
+      # itself (frozen when it is a collection). Never freezes or copies
+      # anything the caller still holds behind its back:
+      #
+      #   * plain data (Strings, Arrays, Hashes, Symbols, Integers, classes...)
+      #     comes back as a deep-frozen COPY, so the app's own objects stay
+      #     mutable;
+      #   * a Proc comes back as a shareable COPY, which works only when its
+      #     self and everything it captures are shareable already (a lambda
+      #     written in a module body). Ruby never freezes what a Proc captures:
+      #     a block from an initializer (self is `main`) is kept as is, and
+      #     works on the main Ractor only;
+      #   * a Hash keeps its default value or default proc and its
+      #     compare_by_identity;
+      #   * any other object (a MessageVerifier, an APM adapter, an app object)
+      #     is kept as is.
+      #
+      # Engines without Ractor get the value back unchanged.
+      def share(value)
+        return value unless defined?(::Ractor)
+        return value if ::Ractor.shareable?(value)
+
+        case value
+        when ::Proc then share_proc(value.dup) || value
+        when ::Array then seal(value.map { share(it) })
+        when ::Hash then share_hash(value)
+        when ::String then value.dup.freeze
+        else value
+        end
+      end
+
+      # Is value shareable (and so readable from any Ractor)? True on an engine
+      # without Ractor, where there is only one.
+      def shareable?(value) = defined?(::Ractor) ? ::Ractor.shareable?(value) : true
+
+      # ActiveSupport::Concern keeps its bookkeeping in instance variables of
+      # the concern module itself: @_dependencies (the concerns it includes)
+      # and the included/prepended block. They are written while the module
+      # body loads and only read when a class includes the concern, so they
+      # are sealed at the end of the body: the list frozen, the block (whose
+      # self is the module, capturing nothing) made shareable.
+      def seal_concern(mod)
+        dependencies = mod.instance_variable_get(:@_dependencies) if mod.instance_variable_defined?(:@_dependencies)
+        dependencies&.freeze
+        %i[@_included_block @_prepended_block].each do
+          share_proc(mod.instance_variable_get(it)) if mod.instance_variable_defined?(it)
+        end
+        mod
+      end
+
+      # The Proc made shareable in place, or nil when it cannot be (or there
+      # is no Ractor).
+      def share_proc(callable)
+        return unless defined?(::Ractor)
+
+        ::Ractor.make_shareable(callable)
+      rescue ::Ractor::Error
+        nil
+      end
+
+      # A plain Hash copy with every key and value shared, keeping the
+      # default (value or proc) and compare_by_identity.
+      def share_hash(hash)
+        copy = hash.compare_by_identity? ? {}.compare_by_identity : {}
+        hash.default_proc ? copy.default_proc = share(hash.default_proc) : copy.default = share(hash.default)
+        hash.each { |key, value| copy[share(key)] = share(value) }
+        seal(copy)
+      end
+
+      # Frozen; shareable as well when everything inside it is.
+      def seal(collection) = collection.freeze
+
+      private_class_method :share_proc, :share_hash, :seal
+    end
+  end
+end

data/lib/phlex/reactive/store.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # Per-Ractor lazy state (zoolutions/phlex-reactive#364): the home for a
+    # process cache that must not live in a constant or a class instance
+    # variable, where a non-main Ractor could not read it (a Mutex or a
+    # mutable Hash is never Ractor-shareable) and never write it.
+    #
+    #   Store.fetch(:phlex_reactive_thing) { build }  # one value per Ractor
+    #   Store.table(:phlex_reactive_memo).fetch(key) { compute }
+    #
+    # On an engine with Ractor.store_if_absent (MRI 3.4+, so every Ruby
+    # phlex-reactive supports there) this is that: atomic, one value per
+    # Ractor. An engine without Ractors (JRuby, TruffleRuby) has only one, so
+    # one Mutex-guarded FALLBACK table stands in. Keys are Symbols prefixed
+    # with the gem's name. The pattern is conformance-kit's
+    # ConformanceKit::Store, copied here because the kit is a development
+    # dependency only.
+    module Store
+      # A Hash guarded by its own Mutex: the per-Ractor memo the threads of one
+      # Ractor share. Built inside the Ractor that uses it, so the lock is
+      # never shared across Ractors.
+      class Table
+        def initialize
+          @mutex = Mutex.new
+          @values = {}
+        end
+
+        # The value under key, computed once with the block when absent.
+        def fetch(key)
+          @mutex.synchronize { @values.fetch(key) { @values[key] = yield } }
+        end
+
+        # True the first time key is claimed (until #clear), false after: a
+        # once-per-Ractor guard, e.g. for a warning.
+        def claim?(key)
+          @mutex.synchronize { @values.key?(key) ? false : (@values[key] = true) }
+        end
+
+        def clear
+          @mutex.synchronize { @values.clear }
+        end
+      end
+
+      NATIVE = defined?(::Ractor) ? ::Ractor.respond_to?(:store_if_absent) : false
+      # Only an engine without Ractor.store_if_absent builds it: on MRI the
+      # module holds no lock and no mutable state at all.
+      FALLBACK = (Table.new unless NATIVE)
+
+      # The table of the once-per-process config warnings (Defer, Pending):
+      # once per Ractor, which in practice is the main one.
+      WARNINGS_KEY = :phlex_reactive_warnings
+
+      class << self
+        def fetch(key, &init)
+          raise ::ArgumentError, "Phlex::Reactive::Store.fetch(#{key.inspect}) needs an initializer block" unless init
+          return ::Ractor.store_if_absent(key, &init) if native?
+
+          FALLBACK.fetch(key, &init)
+        end
+
+        # The current Ractor's Table under key.
+        def table(key) = fetch(key) { Table.new }
+
+        # True the first time the named warning is due in this Ractor.
+        def first_warning?(name) = table(WARNINGS_KEY).claim?(name)
+
+        def native? = NATIVE
+      end
+    end
+  end
+end

data/lib/phlex/reactive/streamable.rb

@@ -97,22 +97,53 @@ module Phlex
       # WeakMap used as a set (the class is the key) so a class reloaded by
       # Zeitwerk in dev is GC'd normally — a strong Array would pin every
       # reloaded generation and leak across reloads. Guarded by a mutex;
-      # registration happens at class-load time, the reset iterates under lock.
-      @registry = ObjectSpace::WeakMap.new
-      @registry_mutex = Mutex.new
+      # registration happens at class-load time.
+      #
+      # Per-Ractor state (Phlex::Reactive::Store, zoolutions/phlex-reactive#364):
+      # a WeakMap and a Mutex are never Ractor-shareable, so in a module ivar no
+      # other Ractor could read them. Classes are defined on the main Ractor
+      # (boot, a development reload), so in practice this is one registry.
+      class ClassRegistry
+        def initialize
+          @mutex = Mutex.new
+          @classes = ObjectSpace::WeakMap.new
+        end
+
+        def add(klass)
+          @mutex.synchronize { @classes[klass] = true }
+        end
+
+        # A point-in-time snapshot, taken under the lock.
+        def to_a
+          @mutex.synchronize do
+            classes = []
+            @classes.each_key { classes << it }
+            classes
+          end
+        end
+      end
+
+      REGISTRY_KEY = :phlex_reactive_streamable_registry
 
       class << self
+        # This Ractor's ClassRegistry.
+        def class_registry = Phlex::Reactive::Store.fetch(REGISTRY_KEY) { ClassRegistry.new }
+
         # Reset every streamable class's cached view context + builder. Called
         # from the engine's reloader (config.to_prepare) so a reloaded renderer
         # controller is never served from a stale memo. No-op outside Rails.
         def reset_all_view_contexts!
-          @registry_mutex.synchronize do
-            @registry.each_key(&:reset_turbo_view_context!)
-          end
+          class_registry.to_a.each(&:reset_turbo_view_context!)
         end
 
+        # Also starts the class's view-context generation at 0 here, when the
+        # class is defined (boot, or a development reload, on the main Ractor),
+        # so reading it on the render path never writes the class
+        # (zoolutions/phlex-reactive#364).
         def register(klass)
-          @registry_mutex.synchronize { @registry[klass] = true }
+          klass.instance_variable_set(:@turbo_view_context_generation, 0) unless
+            klass.instance_variable_defined?(:@turbo_view_context_generation)
+          class_registry.add(klass)
         end
 
         # A point-in-time snapshot of every registered streamable class, taken
@@ -121,13 +152,7 @@ module Phlex
         # working; a class GC'd later simply won't appear next time. Call
         # Rails.application.eager_load! FIRST if you need every app class loaded —
         # the WeakMap only holds classes that have actually been loaded.
-        def registered_classes
-          @registry_mutex.synchronize do
-            classes = []
-            @registry.each_key { classes << it }
-            classes
-          end
-        end
+        def registered_classes = class_registry.to_a
 
         # The ONE broadcast implementation shared by the class-level
         # Streamable.broadcast_to and the module-level Phlex::Reactive.broadcast_to
@@ -423,14 +448,15 @@ module Phlex
         # this class's generation — each thread rebuilds lazily on its next use,
         # and entries for the old generation are dropped. Registered on Rails'
         # reloader by the engine; also used by specs. Thread-safe (an integer
-        # bump; no shared mutable structure to tear down).
+        # bump; no shared mutable structure to tear down), and a class ivar
+        # write that only ever runs on the main Ractor: from the engine's
+        # to_prepare (boot, a development reload) or a spec.
         def reset_turbo_view_context!
-          @turbo_view_context_generation = turbo_view_context_generation + 1
+          @turbo_view_context_generation = (turbo_view_context_generation || 0) + 1 # rubocop:disable ThreadSafety/ClassInstanceVariable
         end
 
-        def turbo_view_context_generation
-          @turbo_view_context_generation ||= 0
-        end
+        # Set to 0 when the class registers (Streamable.register).
+        attr_reader :turbo_view_context_generation
 
         # Render a component to HTML with a full Rails view context. Uses
         # phlex-rails' #render_in against our memoized off-request view context
@@ -909,6 +935,10 @@ module Phlex
           action: "remove", target: id, renders_root: false
         )
       end
+
+      # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+      # the body has loaded (zoolutions/phlex-reactive#364).
+      Phlex::Reactive::Shareable.seal_concern(self)
     end
   end
 end

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.15.5"
+    VERSION = "0.16.0"
   end
 end