phlex-reactive 0.13.3 → 0.14.0

data/lib/phlex/reactive/doctor/fiber_isolation.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    class Doctor
+      # Falcon serves each request as a fiber on one thread (issue #321). Under
+      # Rails' default `config.active_support.isolation_level = :thread`, all
+      # thread-keyed state — CurrentAttributes, IsolatedExecutionState, the lock
+      # on the connection transactional tests pin, thread variables —
+      # is shared by every request on that thread. phlex-reactive's own
+      # request state is fiber-local and unaffected; the app around it is not.
+      #
+      # Detection never loads a server: it reads the bundle (Gem.loaded_specs)
+      # and which server constants are already defined.
+      module FiberIsolation
+        # Server gem => the constant it defines once loaded.
+        SERVERS = {
+          "falcon" => "Falcon",
+          "puma" => "Puma",
+          "unicorn" => "Unicorn",
+          "pitchfork" => "Pitchfork",
+          "passenger" => "PhusionPassenger",
+          "thin" => "Thin",
+          "iodine" => "Iodine"
+        }.freeze
+
+        FIBER_FIX = "Under :thread, thread-keyed state (CurrentAttributes, IsolatedExecutionState, " \
+                    "thread variables) is shared by every request Falcon serves on a thread. " \
+                    "Set in config/application.rb:\n  config.active_support.isolation_level = :fiber"
+
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # The server gem serving the app: Falcon when it is the only one
+          # loaded, else the only one bundled. A lone loaded non-Falcon server
+          # only counts when Falcon isn't bundled — the doctor runs as a rake
+          # task, where "loaded" is whatever Bundler.require pulled in (Rails'
+          # default `gem "puma"` beside `gem "falcon", require: false`). nil
+          # when Falcon is present beside another server and neither is
+          # singled out; :none when no Falcon is anywhere.
+          def detect_server(bundled: bundled_servers, loaded: loaded_servers)
+            return loaded.first if loaded.one? && (loaded.first == "falcon" || bundled.exclude?("falcon"))
+            return bundled.first if bundled.one?
+
+            (bundled | loaded).include?("falcon") ? nil : :none
+          end
+
+          def bundled_servers
+            SERVERS.keys.select { Gem.loaded_specs.key?(it) }
+          end
+
+          def loaded_servers
+            SERVERS.select { |_gem, const| Object.const_defined?(const) }.keys
+          end
+
+          def isolation_level
+            ActiveSupport::IsolatedExecutionState.isolation_level
+          end
+        end
+
+        def fiber_isolation_check(server: Doctor.detect_server, isolation: Doctor.isolation_level)
+          if isolation == :fiber
+            Check.new(:ok, "config.active_support.isolation_level is :fiber", name: :fiber_isolation)
+          elsif server == "falcon"
+            Check.new(:fail, "Falcon serves requests as fibers, but config.active_support.isolation_level " \
+                             "is :#{isolation}", name: :fiber_isolation, fix: FIBER_FIX)
+          elsif server.nil?
+            Check.new(:unknown, "Falcon is in the bundle beside another server; could not tell which serves " \
+                                "the app (isolation_level is :#{isolation})", name: :fiber_isolation,
+              fix: "If Falcon serves the app: #{FIBER_FIX}")
+          else
+            Check.new(:ok, "#{server_label(server)}; :#{isolation} isolation is fine", name: :fiber_isolation)
+          end
+        end
+
+        private
+
+        def server_label(server)
+          server == :none ? "no Falcon in the bundle" : "#{server} does not serve requests as fibers"
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/doctor.rb

@@ -16,6 +16,8 @@ module Phlex
     # default-deny boundary; the worst it does is a throwaway sign→verify round
     # trip and (for the component checks) iterate the loaded Streamable registry.
     class Doctor
+      include FiberIsolation
+
       # 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
       # plain value object (not Data) so it takes positional status/message plus
@@ -70,14 +72,19 @@ module Phlex
         [
           route_check,
           defer_route_check,
+          fragment_route_check,
+          fragment_path_meta_check,
           stimulus_check,
           csrf_check,
           verifier_check,
           base_controller_check,
+          fiber_isolation_check,
           action_check(components),
           id_check(components),
-          authorization_check(components)
-        ]
+          authorization_check(components),
+          dormant_check(components),
+          *early_pin_check(components)
+        ].compact
       end
 
       # --- individual checks ------------------------------------------------
@@ -97,6 +104,45 @@ module Phlex
         path_check(Phlex::Reactive.defer_path, :defer_route, "Phlex::Reactive.defer_path")
       end
 
+      # The cacheable-fragment GET endpoint (issue #277): a host GET catch-all
+      # that shadows it makes every `reactive_lazy cache:` fetch load the host's
+      # fallback page instead of the fragment.
+      def fragment_route_check
+        path = "#{Phlex::Reactive.fragment_path}/:id"
+        if Phlex::Reactive.fragment_route_ok?
+          Check.new(:ok, "GET #{path} routes to phlex/reactive/fragments", name: :fragment_route)
+        else
+          Check.new(:fail, "GET #{path} does not resolve to phlex/reactive/fragments", name: :fragment_route,
+            fix: "A host catch-all route (get \"*path\", ...) likely shadows it. Exempt " \
+                 "#{Phlex::Reactive.fragment_path.delete_prefix("/")} from the catch-all, or set " \
+                 "Phlex::Reactive.fragment_path to an unshadowed path.")
+        end
+      end
+
+      # A custom fragment_path the client was never told about (issue #277): the
+      # client only fetches a fragment URL under the path it knows — the meta
+      # tag, else the default — so every `reactive_lazy cache:` shell would be
+      # refused (reactive:error, the shell never loads). Only checked when the
+      # path was changed; nil (no check) otherwise.
+      def fragment_path_meta_check
+        path = Phlex::Reactive.fragment_path
+        return if path == "/reactive/fragment"
+
+        # A file must name the meta AND supply this path — literally, or from
+        # the setting (`Phlex::Reactive.fragment_path`). A tag left behind with
+        # an old path is as broken as none. Whether it sits in <head> (the only
+        # place the client reads it) can't be told from source; the fix says so.
+        if layout_references?("phlex-reactive-fragment-path") { it.include?(path) || it.include?("fragment_path") }
+          Check.new(:ok, "phlex-reactive-fragment-path meta found for #{path} (it must be in <head>)",
+            name: :fragment_path_meta)
+        else
+          Check.new(:fail, "Phlex::Reactive.fragment_path is #{path} but no layout renders its meta tag with that path",
+            name: :fragment_path_meta,
+            fix: "Add <meta name=\"phlex-reactive-fragment-path\" content=\"#{path}\"> to your layout's " \
+                 "<head> — the client refuses a fragment URL outside the path it knows.")
+        end
+      end
+
       # Shared body for the two endpoint-route checks: both POST to the gem's
       # ActionsController, so action_route_ok? answers for either path.
       def path_check(path, name, setting)
@@ -212,6 +258,42 @@ module Phlex
                "`skip_verify_authorized`. See the Debugging & tooling docs page.")
       end
 
+      # Dormant roots (issue #274): how many components declare `reactive_dormant`
+      # and whether a Stimulus entrypoint imports phlex/reactive/early — the
+      # module that wakes them (without it a dormant root never mounts). No line
+      # at all when nothing is dormant. ADVISORY when the import isn't found: it
+      # may live in a file the doctor doesn't scan. A per-render
+      # reactive_root(dormant: true) is invisible here (it isn't a declaration).
+      def dormant_check(components, early: imports_early?)
+        dormant = dormant_components(components)
+        return if dormant.empty?
+
+        label = "#{dormant.size} dormant #{dormant.one? ? "component" : "components"} (#{dormant.map(&:name).join(", ")})"
+        return Check.new(:ok, "#{label}; phlex/reactive/early is imported#{early_location(early)}", name: :dormant) if early
+
+        Check.new(:unknown, "#{label}, but no import of phlex/reactive/early was found", name: :dormant,
+          fix: "A dormant root is woken by that module — without it the root never mounts. Add to " \
+               "your entrypoint, before any controller loads:\n  import \"phlex/reactive/early\"")
+      end
+
+      # Every import map the app registers must pin phlex/reactive/early when a
+      # dormant root exists (issue #307): a map without the pin cannot resolve
+      # the specifier, so the import fails on the pages that map serves. One
+      # advisory check per map lacking the pin; none when every map has it.
+      # Maps: Rails.application.importmap, or Phlex::Reactive.importmaps (a
+      # callable returning { name => Importmap::Map }) for an app with its own.
+      def early_pin_check(components)
+        return [] if dormant_components(components).empty?
+
+        import_maps.filter_map do |name, map|
+          next if map_pins_early?(map)
+
+          Check.new(:unknown, "import map \"#{name}\" does not pin phlex/reactive/early", name: :early_pin,
+            fix: "A dormant root rendered on a page served by this map cannot load the module. Add to " \
+                 "the map's file:\n  pin \"phlex/reactive/early\", to: \"phlex/reactive/early.min.js\", preload: true")
+        end
+      end
+
       # --- rendering --------------------------------------------------------
 
       # The full plain-text report: a line per check, plus an indented fix under
@@ -236,6 +318,27 @@ module Phlex
         "phlex/reactive/actions"
       end
 
+      STIMULUS_ENTRYPOINTS = %w[
+        app/javascript/controllers/index.js
+        app/javascript/controllers/application.js
+        app/javascript/application.js
+      ].freeze
+      EARLY_IMPORT = %r{import\s+["']phlex/reactive/early["']}
+      # Closed comments, which may span lines: HTML, JS block and ERB.
+      BLOCK_COMMENT = %r{<!--.*?-->|/\*.*?\*/|<%#.*?%>}m
+      # What precedes the import on its line when it is commented out: a //
+      # (not the one in a URL), an unclosed /*, or a block-comment's leading *.
+      COMMENT_BEFORE = %r{(?<!:)//|/\*|\A\s*\*}
+
+      # Is there an `import "phlex/reactive/early"` in `source` that actually
+      # runs? Closed comments are dropped first, then each line is read, so a
+      # commented-out import doesn't count.
+      def self.imports_early_source?(source)
+        source.gsub(BLOCK_COMMENT, "").each_line.any? do
+          (match = EARLY_IMPORT.match(it)) && !match.pre_match.match?(COMMENT_BEFORE)
+        end
+      end
+
       private
 
       # A one-line tally: how many passed, failed, and are advisory/unknown.
@@ -340,11 +443,7 @@ module Phlex
       # small/importmap app often registers inline in <head> rather than in a
       # dedicated entrypoint file. Only existing files are returned.
       def stimulus_registration_files
-        candidates = %w[
-          app/javascript/controllers/index.js
-          app/javascript/controllers/application.js
-          app/javascript/application.js
-        ].map { app_path(it) }
+        candidates = STIMULUS_ENTRYPOINTS.map { app_path(it) }
         candidates += ::Dir.glob(app_path("app/views/layouts/**/*.erb"))
         candidates.select { File.exist?(it) }
       end
@@ -355,6 +454,58 @@ module Phlex
         false
       end
 
+      # The relative path of the first file that imports phlex/reactive/early,
+      # or false. The Stimulus registration files go first, then every other app
+      # JavaScript entry (vendor excluded) and inline module scripts in views and
+      # components (issue #307).
+      def imports_early?
+        (stimulus_registration_files | early_import_candidates).each do
+          return relative(it) if Doctor.imports_early_source?(early_source(it))
+        rescue StandardError
+          next
+        end
+        false
+      end
+
+      # A Ruby file's `# …` comment lines are not code (a layout that mentions
+      # the import in a comment must not pass the check).
+      def early_source(path)
+        source = File.read(path)
+        path.end_with?(".rb") ? source.lines.grep_v(/\A\s*#/).join : source
+      end
+
+      def early_import_candidates
+        globs = %w[app/javascript/**/*.js app/views/**/*.{rb,erb} app/components/**/*.{rb,erb}].map { app_path(it) }
+        ::Dir.glob(globs).reject { it.include?("/vendor/") }.sort
+      end
+
+      # " (path)" when the import sits outside the JavaScript entrypoints the
+      # doctor always scanned (those keep their original output).
+      def early_location(early)
+        return "" unless early.is_a?(String)
+        return "" if STIMULUS_ENTRYPOINTS.include?(early)
+
+        " (#{early})"
+      end
+
+      def dormant_components(components)
+        components.select { it.respond_to?(:reactive_dormant?) && it.reactive_dormant? }
+      end
+
+      def import_maps
+        default = ::Rails.application.respond_to?(:importmap) ? ::Rails.application.importmap : nil
+        maps = default ? { "application" => default } : {}
+        maps.merge(Phlex::Reactive.importmaps&.call || {})
+      rescue StandardError
+        maps || {}
+      end
+
+      def map_pins_early?(map)
+        map.packages.key?("phlex/reactive/early")
+      rescue StandardError
+        true
+      end
+
       # Only meaningful when importmap is in use. True when importmap is present
       # but the reactive_controller pin is absent (the engine pins it, so this is
       # really "someone overrode importmap.rb and dropped the pin").
@@ -371,6 +522,12 @@ module Phlex
 
       # Grep ERB layouts AND Phlex layout files for a csrf_meta_tags reference.
       def csrf_meta_referenced?
+        layout_references?("csrf_meta_tags")
+      end
+
+      # Does any ERB view / Phlex view or component mention `needle` (and, with
+      # a block, satisfy it for that file's source)?
+      def layout_references?(needle)
         globs = %w[
           app/views/**/*.erb
           app/views/**/*.rb
@@ -379,7 +536,8 @@ module Phlex
         ].map { app_path(it) }
 
         ::Dir.glob(globs).any? do
-          File.read(it).include?("csrf_meta_tags")
+          source = File.read(it)
+          source.include?(needle) && (!block_given? || yield(source))
         rescue StandardError
           false
         end

data/lib/phlex/reactive/dormant.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # Dormant roots (issue #274). A root declared dormant — `reactive_dormant`
+    # on the class, or `reactive_root(dormant: true)` — renders
+    # data-reactive-dormant="reactive" INSTEAD of data-controller="reactive":
+    # the reactive controller is not mounted (and, when the app loads it lazily,
+    # not even fetched) until one of the root's triggers fires. The client's
+    # phlex/reactive/early module then moves the identifier into data-controller
+    # and the trigger is replayed on connect.
+    #
+    # A render made for the ACTOR's own reply is AWAKE: the reply only exists
+    # because that page's controller is loaded and connected, so a dormant
+    # replacement would save nothing and cost one more wake. The endpoint runs
+    # the action and its reply (and the defer render) inside Dormant.awake;
+    # every other render — the page, a stream built outside a reactive request,
+    # and a BROADCAST even when fired inside an action (Dormant.asleep) — stays
+    # dormant, because its receivers may never have loaded the client.
+    module Dormant
+      AWAKE_KEY = :phlex_reactive_dormant_awake
+
+      class << self
+        def awake?
+          Thread.current[AWAKE_KEY] ? true : false
+        end
+
+        # Render dormant roots awake inside the block (fiber-local, restored on
+        # exit — a raise included).
+        def awake
+          previous = Thread.current[AWAKE_KEY]
+          Thread.current[AWAKE_KEY] = true
+          yield
+        ensure
+          Thread.current[AWAKE_KEY] = previous
+        end
+
+        # A reactive_lazy(on: :visible) shell (issue #276) has no trigger
+        # descriptor — the CONTROLLER's IntersectionObserver materializes it —
+        # so a dormant one could never wake. Refused where it is declared, and
+        # (for the other declaration order) where the shell renders.
+        def reject_visible_lazy!(klass)
+          return unless klass.respond_to?(:reactive_lazy_trigger) && klass.reactive_lazy_trigger&.key?(:visible)
+
+          raise ArgumentError,
+            "#{klass}: reactive_dormant cannot be combined with reactive_lazy(on: :visible) — a dormant " \
+            "root wakes on a trigger event, and a visibility shell has none (the controller's " \
+            "IntersectionObserver loads it). Use reactive_lazy(on: \"an:event\"), or drop reactive_dormant."
+        end
+
+        # The inverse, for a render fired INSIDE an awake block that leaves the
+        # actor's page — a broadcast. A plain yield when nothing is awake.
+        def asleep
+          return yield unless Thread.current[AWAKE_KEY]
+
+          begin
+            Thread.current[AWAKE_KEY] = nil
+            yield
+          ensure
+            Thread.current[AWAKE_KEY] = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/engine.rb

@@ -11,20 +11,39 @@ module Phlex
     class Engine < ::Rails::Engine
       isolate_namespace Phlex::Reactive
 
+      # The client's feature modules (issue #275), each its own file at the
+      # bare specifier phlex/reactive/features/<name>. The DEFAULT client
+      # (phlex/reactive/reactive_controller) is one file with all of them
+      # bundled in and never fetches these. The opt-in phlex/reactive/core
+      # imports one only when a root on the page uses it. Listed here once; the
+      # precompile list and the importmap pins below are built from it. The
+      # build script (scripts/build_client.js), the core's own table and the
+      # default entry name the same features —
+      # spec/phlex/engine_client_pin_spec.rb fails when they disagree.
+      CLIENT_FEATURES = %w[persist defer form bindings compute effects hints devtools].freeze
+      # (Gzipped, bun zlib level 9: the default file 26.1 KB; the core 12.4 KB;
+      # persist 3.2, defer 2.8, form 1.0, bindings 5.4, compute 2.1, effects
+      # 1.7, hints 1.0, devtools 1.6 KB. spec/javascript/bundle_budget.test.js
+      # is the source of truth and holds a ratchet on each.)
+
       # Mount POST /reactive/actions -> Phlex::Reactive::ActionsController#create
       # and POST /reactive/defer -> #deferred (the pull-lane defer endpoint,
-      # issue #165). Apps can change the paths with Phlex::Reactive.action_path /
-      # .defer_path before boot.
+      # issue #165), and GET /reactive/fragment/:id -> FragmentsController#show
+      # (the privately cacheable lazy render, issue #277). Apps can change the
+      # paths with Phlex::Reactive.action_path / .defer_path / .fragment_path
+      # before boot.
       initializer "phlex_reactive.routes" do
         it.routes.append do
           post Phlex::Reactive.action_path, to: "phlex/reactive/actions#create", as: :phlex_reactive_action
           post Phlex::Reactive.defer_path, to: "phlex/reactive/actions#deferred", as: :phlex_reactive_defer
+          get "#{Phlex::Reactive.fragment_path}/:id", to: "phlex/reactive/fragments#show",
+            as: :phlex_reactive_fragment
         end
       end
 
       # Make the MINIFIED client build available to Propshaft/Sprockets so it can
       # be fingerprinted, served, and pinned in importmap. The browser ships the
-      # minified twin (108 KB -> 22 KB for the controller; `rake build:js`), not
+      # minified twin (about a fifth of the source; `rake build:js`), not
       # the comment-dense source. The .min.js.map is precompiled too so devtools
       # resolves the linked sourcemap back to the readable source on demand.
       initializer "phlex_reactive.assets" do
@@ -37,6 +56,10 @@ module Phlex
           it.config.assets.precompile += %w[
             phlex/reactive/reactive_controller.min.js
             phlex/reactive/reactive_controller.min.js.map
+            phlex/reactive/core.min.js
+            phlex/reactive/core.min.js.map
+            phlex/reactive/early.min.js
+            phlex/reactive/early.min.js.map
             phlex/reactive/confirm.min.js
             phlex/reactive/confirm.min.js.map
             phlex/reactive/confirm_predicate.min.js
@@ -47,6 +70,9 @@ module Phlex
             phlex/reactive/inspect.min.js.map
             phlex/reactive/effects.css
           ]
+          it.config.assets.precompile += CLIENT_FEATURES.flat_map do
+            ["phlex/reactive/features/#{it}.min.js", "phlex/reactive/features/#{it}.min.js.map"]
+          end
         end
       end
 
@@ -55,11 +81,32 @@ module Phlex
       # asset pipeline instead (see README).
       initializer "phlex_reactive.importmap", after: "importmap" do
         if defined?(::Importmap::Map) && it.respond_to?(:importmap)
+          # The DEFAULT client: one file, the core and every feature bundled.
           it.importmap.pin(
             "phlex/reactive/reactive_controller",
             to: "phlex/reactive/reactive_controller.min.js",
             preload: true
           )
+          # The OPT-IN client (issue #275): the controller without its
+          # features, which it imports on demand (the feature pins below). An
+          # app imports this INSTEAD of reactive_controller, never both. Not
+          # preloaded: an app that does not opt in must not fetch it. One that
+          # does re-pins it with preload: true, like any entry it imports
+          # eagerly.
+          it.importmap.pin(
+            "phlex/reactive/core",
+            to: "phlex/reactive/core.min.js",
+            preload: false
+          )
+          # The early-trigger capture (issue #273): a ~1 KB module the app
+          # imports EAGERLY (`import "phlex/reactive/early"`) so a trigger that
+          # fires before a lazily loaded controller connects is replayed on
+          # connect instead of lost. Preloaded: it must run before the triggers.
+          it.importmap.pin(
+            "phlex/reactive/early",
+            to: "phlex/reactive/early.min.js",
+            preload: true
+          )
           # The overridable confirm resolver (issue #55). reactive_controller.js
           # imports it by this BARE specifier — `import { confirmResolver } from
           # "phlex/reactive/confirm"` — NOT a relative "./confirm.js" (issue #57:
@@ -102,6 +149,19 @@ module Phlex
             to: "phlex/reactive/inspect.min.js",
             preload: false
           )
+          # Feature modules (issue #275), for the opt-in phlex/reactive/core.
+          # NOT preloaded: the core imports one only when a root on the page
+          # uses it, so a page without such a root never fetches it — and the
+          # default client never does. An app on the core that knows it needs
+          # one on every page re-pins it with preload: true.
+          importmap = it.importmap
+          CLIENT_FEATURES.each do
+            importmap.pin(
+              "phlex/reactive/features/#{it}",
+              to: "phlex/reactive/features/#{it}.min.js",
+              preload: false
+            )
+          end
         end
       end
 
@@ -112,6 +172,7 @@ module Phlex
       config.to_prepare do
         Phlex::Reactive::Streamable.reset_all_view_contexts!
         Phlex::Reactive.reset_stream_builder!
+        Phlex::Reactive::Pending::Markup.reset!
       end
 
       # Boot-time guard (issue #26): warn if the action path doesn't resolve to